Re: [PATCH v2] docs: specify numerical values of Xenstore commands

[Jürgen Groß <jgross@xxxxxxxx>]

On 11.03.25 10:21, Julien Grall wrote:
> Hi Juergen,
>
> On 11/03/2025 07:31, Juergen Gross wrote:
> > In docs/misc/xenstore.txt all Xenstore commands are specified, but
> > the specifications lack the numerical values of the commands.
> >
> > Add a table with all commands, their values, and a potential remark
> > (e.g. whether the command is optional).
> >
> > Reported-by: Jan Beulich <jbeulich@xxxxxxxx>
> > Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> > ---
> > V2:
> > - replace "ŕ" with plain "r" (Jan Beulich)
> > - replace hard tabs with blanks (Jan Beulich)
> > - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich)
> > ---
> >   docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 57 insertions(+)
> >
> > diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
> > index 7e1f031520..8b4b790e11 100644
> > --- a/docs/misc/xenstore.txt
> > +++ b/docs/misc/xenstore.txt
> > @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients.  In any 
> > case passing
> >   bulk data through xenstore is not recommended as the performance
> >   properties are poor.
> > +---------- Defined Xenstore message types ----------
> > +
> > +Below is a table with all defined Xenstore message types (type name
> > +and its associated numerical value).
> > +
> > +Some types are optional to be supported by a specific Xenstore
> > +implementation.  If an optional type is not supported by a Xenstore
> > +implementation, Xen tools will continue to work, maybe with slightly
> > +reduced functionality.  A mandatory type not being supported will
> > +result in severely reduced functionality, like inability to create
> > +domains.  In case a type is optional, this is stated in the table with
> > +the lost functionality in case Xenstore doesn't support that type.
> > +
> > +XS_CONTROL               0    optional
> > +    If not supported, xenstore-control command will not work.
> Are we documenting anywhere how a user could figure out if the command is not 
> supported? Is it a specific error code?
I can add that not supported commands will return "ENOSYS" as an error
response.

> > +    XS_DEBUG is a deprecated alias of XS_CONTROL.
>  > +XS_DIRECTORY             1> +XS_READ                  2
> > +XS_GET_PERMS             3
> > +XS_WATCH                 4
> > +XS_UNWATCH               5
> > +XS_TRANSACTION_START     6
> > +XS_TRANSACTION_END       7
> > +XS_INTRODUCE             8
> > +XS_RELEASE               9
> > +XS_GET_DOMAIN_PATH      10
> > +XS_WRITE                11
> > +XS_MKDIR                12
> > +XS_RM                   13
> > +XS_SET_PERMS            14
> > +XS_WATCH_EVENT          15
> > +    Not valid in client sent messages.
> > +    Only valid in Xenstore replies.
> > +XS_ERROR                16
> > +    Not valid in client sent messages.
> > +    Only valid in Xenstore replies.
> > +XS_IS_DOMAIN_INTRODUCED 17
> > +XS_RESUME               18
> > +XS_SET_TARGET           19
> > +XS_RESTRICT             20    no longer supported
> > +    XS_RESTRICT has been removed, the type value 20 is invalid.
> > +XS_RESET_WATCHES        21
> > +XS_DIRECTORY_PART       22    optional
> > +    If not supported, the output of xenstore-ls might be incomplete
> > +    with more than ca. 1000 domains active.
> Why are we making this specific to number of domains? Wouldn't the problem be 
> the same if you have 1000 node within a parent node?
Let me reiterate the answer I gave to Jan when he asked:

  And elsewhere there can't be very many nodes resulting in a similar
  situation?

Not without someone trying to force this by will (only possible by a
root user of dom0, e.g. via creating lots of nodes in the same directory
via "xenstore-write").

Having lots of domains is an "easy" way to create this scenario via
perfectly valid and sensible operations.


I can rephrase the remark like this:

    If not supported, the output of xenstore-ls might be incomplete
    with a node's sub-node list exceeding the maximum payload size
    (e.g. the "/local/domain" node with more than ca. 1000 domains
    active).


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature