[xen staging] tools/xenstore: add documentation for extended watch command

[patchbot@xxxxxxx]

commit 3db29e8fac3f874aba0198f398e8eeaad9a091b8
Author:     Juergen Gross <jgross@xxxxxxxx>
AuthorDate: Mon Jul 18 17:47:23 2022 +0200
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Mon Jul 18 17:47:23 2022 +0200

    tools/xenstore: add documentation for extended watch command
    
    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>
    Reviewed-by: Luca Fancellu <luca.fancellu@xxxxxxx>
---
 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 aa71c56e4c..a1e6c7bb3a 100644
--- a/docs/misc/xenstore-ring.txt
+++ b/docs/misc/xenstore-ring.txt
@@ -71,6 +71,7 @@ Bit     Description
 1       Connection error indicator (see connection error feature below)
 2       GET_FEATURE and SET_FEATURE Xenstore wire commands are available
 3       GET_QUOTA and SET_QUOTA Xenstore wire commands are available
+4       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 629f962bb5..ee0b51394f 100644
--- a/docs/misc/xenstore.txt
+++ b/docs/misc/xenstore.txt
@@ -176,7 +176,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,
@@ -187,7 +187,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
@@ -198,7 +202,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>
+       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
--
generated by git-patchbot for /home/xen/git/xen.git#staging