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

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

On 06.03.25 14:09, Jan Beulich wrote:
> On 06.03.2025 13:56, Jürgen Groß wrote:
> > On 06.03.25 13:32, Jan Beulich wrote:
> > > On 06.03.2025 13:23, Juergen Gross wrote:
> > > > --- a/docs/misc/xenstore.txt
> > > > +++ b/docs/misc/xenstore.txt
> > > > @@ -86,6 +86,65 @@ 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.
> > > > +       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 moŕe than ca. 1000 domains active.
> > > Nit: Odd 'ŕ' here.
> > Thanks for spotting.
> >
> > > Also the 1000 domains boundary is just an example aiui, so you may want
> > > to add "e.g.".
> > The boundary is related to the amount of data returned by XS_DIRECTORY
> > for "/local/domain". As soon as the sum of (strlen(domid_string) + 1)
> > of all domains is larger than 4080 (XENSTORE_PAYLOAD_MAX - sizeof(struct
> > xsd_sockmsg)), XS_DIRECTORY won't be able to return the list of children
> > for "/local/domain". The limit will depend on the domid distribution:
> > in the worst case it can be 640 (all domids 5 digits), in the best case
> > it will be 1038 (all domids below 1000 present, the rest below 10000).
> 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'm further uncertain here regarding your use of hard tabs.
> > I'm following the style of the rest of the document, which is making use
> > of hard tabs as well. I can switch to spaces if you want.
> I'm not demanding a change. I'd like it to be considered though that people
> may in principle be using different tab-to-nr-of-blanks mappings, which
> causes tabular arrangements like the above one to come out distorted.
Fair enough.

I'm going to switch to blanks for the table.


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature