Re: [PATCH 3/3] tools/xenstore: add documentation for extended watch command

[Luca Fancellu <Luca.Fancellu@xxxxxxx>]

> On 16 Mar 2022, at 16:10, Juergen Gross <jgross@xxxxxxxx> wrote:
> 
> Add documentation for an extension of the WATCH command used to limit
> the scope of watched paths. Additionally it enables to receive more
> information in the events related to special watches (@introduceDomain
> or @releaseDomain).
> 
> Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> ---
> docs/misc/xenstore-ring.txt |  1 +
> docs/misc/xenstore.txt      | 16 +++++++++++++---
> 2 files changed, 14 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/misc/xenstore-ring.txt b/docs/misc/xenstore-ring.txt
> index 0cb72a3e35..eaa6d0a1a3 100644
> --- a/docs/misc/xenstore-ring.txt
> +++ b/docs/misc/xenstore-ring.txt
> @@ -70,6 +70,7 @@ Mask    Description
> 2       Connection error indicator (see connection error feature below)
> 4       GET_FEATURE and SET_FEATURE Xenstore wire commands are available
> 8       GET_QUOTA and SET_QUOTA Xenstore wire commands are available
> +16      WATCH can take a third parameter limiting its scope
> 
> The "Connection state" field is used to request a ring close and reconnect.
> The "Connection state" field only contains valid data if the server has
> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
> index dd75a81328..f86c6d9757 100644
> --- a/docs/misc/xenstore.txt
> +++ b/docs/misc/xenstore.txt
> @@ -188,7 +188,7 @@ SET_PERMS         <path>|<perm-as-string>|+?
> 
> ---------- Watches ----------
> 
> -WATCH                        <wpath>|<token>|?
> +WATCH                        <wpath>|<token>|[<depth>|]?
>       Adds a watch.
> 
>       When a <path> is modified (including path creation, removal,
> @@ -199,7 +199,11 @@ WATCH                    <wpath>|<token>|?
>       matching watch results in a WATCH_EVENT message (see below).
> 
>       The event's path matches the watch's <wpath> if it is an child
> -     of <wpath>.
> +     of <wpath>. This match can be limited by specifying <depth> (a
> +     decimal value of 0 or larger): it denotes the directory levels
> +     below <wpath> to consider for a match ("0" would not match for
> +     a child of <wpath>, "1" would match only for a direct child,
> +     etc.).
> 
>       <wpath> can be a <path> to watch or @<wspecial>.  In the
>       latter case <wspecial> may have any syntax but it matches
> @@ -210,7 +214,13 @@ WATCH                    <wpath>|<token>|?
>                               shutdown, and also on RELEASE
>                               and domain destruction
>       <wspecial> events are sent to privileged callers or explicitly
> -     via SET_PERMS enabled domains only.
> +     via SET_PERMS enabled domains only. The semantics for a
> +     specification of <depth> differ for generating <wspecial>

Typo: s/differ/differs/?

> +     events: specifying "1" will report the related domid by using
> +     @<wspecial>/<domid> for the reported path. Other <depth>
> +     values are not supported.
> +     For @releaseDomain it is possible to watch only for a specific
> +     domain by specifying @releaseDomain/<domid> for the path.
> 
>       When a watch is first set up it is triggered once straight
>       away, with <path> equal to <wpath>.  Watches may be triggered
> -- 
> 2.34.1
> 
> 

I’m not an English native speaker so apologies if there is no mistake.

With that fixed (if it’s wrong):

Reviewed-by: Luca Fancellu <luca.fancellu@xxxxxxx>

Cheers,
Luca