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

[Luca Fancellu <Luca.Fancellu@arm.com>]

> On 16 Mar 2022, at 16:10, Juergen Gross <jgross@suse.com> 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@suse.com>
> ---
> 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@arm.com>

Cheers,
Luca