[PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[Julien Grall]

From: Julien Grall <jgrall@amazon.com>

Commit 13dd372834a4 removed the documentation for XS_RESUME, however
this command is still implemented (at least in C Xenstored) and used by
libxl when resuming a domain.

So re-instate the documentation for the XS_RESUME. Take the opportunity
to update it as there is a user of the command.

Fixes: 13dd372834a4 ("docs/designs: re-work the xenstore migration document...")
Signed-off-by: Julien Grall <jgrall@amazon.com>

---

Cc: raphning@gmail.com
Cc: jgross@suse.com
Cc: paul@xen.org

Ian, would you still consider documentation update for 4.15?

I looked at the implementation of domain_resume() in Xen, it doesn't
look like we can get away with XS_RESUME because Xen will not send
VIRQ_DOM_EXC on resume.
---
 docs/misc/xenstore.txt | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 148074233001..334dc8b6fdf5 100644
--- a/docs/misc/xenstore.txt
+++ b/docs/misc/xenstore.txt
@@ -294,6 +294,22 @@ IS_DOMAIN_INTRODUCED	<domid>|		T| or F|
 	ie, if INTRODUCE for the domain has not yet been followed by
 	domain destruction or explicit RELEASE.
 
+RESUME			<domid>|
+
+	Arranges that @releaseDomain events will once more be
+	generated when the domain becomes shut down.  This might have
+	to be used if a domain were to be shut down (generating one
+	@releaseDomain) and then subsequently restarted, since the
+	state-sensitive algorithm in xenstored will not otherwise send
+	further watch event notifications if the domain were to be
+	shut down again.
+
+	This command will be issued in place such as resume because
+	Xen will "shutdown" the domain on suspend.
+
+	xenstored prevents the use of RESUME other than by dom0.
+
+
 SET_TARGET		<domid>|<tdomid>|
 	Notifies xenstored that domain <domid> is targeting domain
 	<tdomid>. This grants domain <domid> full access to paths
-- 
2.17.1

Re: [PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[Paul Durrant]

On 25/03/2021 18:06, Julien Grall wrote:
> From: Julien Grall <jgrall@amazon.com>
> 
> Commit 13dd372834a4 removed the documentation for XS_RESUME, however
> this command is still implemented (at least in C Xenstored) and used by
> libxl when resuming a domain.
> 
> So re-instate the documentation for the XS_RESUME. Take the opportunity
> to update it as there is a user of the command.
> 
> Fixes: 13dd372834a4 ("docs/designs: re-work the xenstore migration document...")
> Signed-off-by: Julien Grall <jgrall@amazon.com>
> 
> ---
> 
> Cc: raphning@gmail.com
> Cc: jgross@suse.com
> Cc: paul@xen.org

Reviewed-by: Paul Durrant <paul@xen.org>

> 
> Ian, would you still consider documentation update for 4.15?
> 
> I looked at the implementation of domain_resume() in Xen, it doesn't
> look like we can get away with XS_RESUME because Xen will not send
> VIRQ_DOM_EXC on resume.
> ---
>   docs/misc/xenstore.txt | 16 ++++++++++++++++
>   1 file changed, 16 insertions(+)
> 
> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
> index 148074233001..334dc8b6fdf5 100644
> --- a/docs/misc/xenstore.txt
> +++ b/docs/misc/xenstore.txt
> @@ -294,6 +294,22 @@ IS_DOMAIN_INTRODUCED	<domid>|		T| or F|
>   	ie, if INTRODUCE for the domain has not yet been followed by
>   	domain destruction or explicit RELEASE.
>   
> +RESUME			<domid>|
> +
> +	Arranges that @releaseDomain events will once more be
> +	generated when the domain becomes shut down.  This might have
> +	to be used if a domain were to be shut down (generating one
> +	@releaseDomain) and then subsequently restarted, since the
> +	state-sensitive algorithm in xenstored will not otherwise send
> +	further watch event notifications if the domain were to be
> +	shut down again.
> +
> +	This command will be issued in place such as resume because
> +	Xen will "shutdown" the domain on suspend.
> +
> +	xenstored prevents the use of RESUME other than by dom0.
> +
> +
>   SET_TARGET		<domid>|<tdomid>|
>   	Notifies xenstored that domain <domid> is targeting domain
>   	<tdomid>. This grants domain <domid> full access to paths
> 

Re: [PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[Jürgen Groß]

[-- Attachment #1.1.1: Type: text/plain, Size: 596 bytes --]

On 25.03.21 19:06, Julien Grall wrote:
> From: Julien Grall <jgrall@amazon.com>
> 
> Commit 13dd372834a4 removed the documentation for XS_RESUME, however
> this command is still implemented (at least in C Xenstored) and used by
> libxl when resuming a domain.
> 
> So re-instate the documentation for the XS_RESUME. Take the opportunity
> to update it as there is a user of the command.
> 
> Fixes: 13dd372834a4 ("docs/designs: re-work the xenstore migration document...")
> Signed-off-by: Julien Grall <jgrall@amazon.com>

Reviewed-by: Juergen Gross <jgross@suse.com>


Juergen

[-- Attachment #1.1.2: OpenPGP_0xB0DE9DD628BF132F.asc --]
[-- Type: application/pgp-keys, Size: 3135 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 495 bytes --]

Re: [PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[Ian Jackson]

Julien Grall writes ("[PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME"):
> From: Julien Grall <jgrall@amazon.com>
> 
> Commit 13dd372834a4 removed the documentation for XS_RESUME, however
> this command is still implemented (at least in C Xenstored) and used by
> libxl when resuming a domain.
> 
> So re-instate the documentation for the XS_RESUME. Take the opportunity
> to update it as there is a user of the command.

This is just docs, so:

Release-Acked-by: Ian Jackson <iwj@xenproject.org>
Reviewed-by: Ian Jackson <iwj@xenproject.org>

Re: [PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME

[Julien Grall]

Hi Ian,

On 26/03/2021 12:05, Ian Jackson wrote:
> Julien Grall writes ("[PATCH for-4.15?] docs/misc: xenstored: Re-instate and tweak the documentation for XS_RESUME"):
>> From: Julien Grall <jgrall@amazon.com>
>>
>> Commit 13dd372834a4 removed the documentation for XS_RESUME, however
>> this command is still implemented (at least in C Xenstored) and used by
>> libxl when resuming a domain.
>>
>> So re-instate the documentation for the XS_RESUME. Take the opportunity
>> to update it as there is a user of the command.
> 
> This is just docs, so:
> 
> Release-Acked-by: Ian Jackson <iwj@xenproject.org>
> Reviewed-by: Ian Jackson <iwj@xenproject.org>

Thanks! I have committed the patch to staging and cherry-pick in 
staging-4.15.

Cheers,

-- 
Julien Grall