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

[Paul Durrant <xadimgnik@xxxxxxxxx>]

On 25/03/2021 18:06, Julien Grall wrote:
> From: Julien Grall <jgrall@xxxxxxxxxx>
>
> 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@xxxxxxxxxx>
>
> ---
>
> Cc: raphning@xxxxxxxxx
> Cc: jgross@xxxxxxxx
> Cc: paul@xxxxxxx
Reviewed-by: Paul Durrant <paul@xxxxxxx>

> 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