> On 16 Mar 2022, at 16:10, Juergen Gross <jgr...@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 <jgr...@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.fance...@arm.com>
Cheers,
Luca
