| Message ID | 20220316161017.3579-4-jgross@suse.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | tools/xenstore: add some new features to the documentation | expand |
> 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
On 16.03.22 19:16, Luca Fancellu wrote: > > >> 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/? I think "semantics" is a plural word, but I've found some references that it is often used with a singular verb. It seems both variants are in use. > I’m not an English native speaker so apologies if there is no mistake. Me neither. Any advice from a native English speaker? Juergen
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> + 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
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(-)