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

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

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).

> > +XS_GET_FEATURE         23      optional
> > +XS_SET_FEATURE         24      optional
> > +       XS_GET_FEATURE and XS_SET_FEATURE must either be both supported
> > +       or both unsupported.
> > +       If unsupported, setting availability of Xenstore features per
> > +       domain is not possible.
> Why would GET_FEATURES alone not be permitted?
I can allow that. There might be the use case to query availability of
a feature via a dom0 socket connection.

> > +XS_GET_QUOTA           25      optional
> > +XS_SET_QUOTA           26      optional
> > +       XS_GET_QUOTA and XS_SET_QUOTA must either be both supported
> > +       or both unsupported.
> > +       If unsupported, setting of Xenstore quota per domain is not
> > +       possible.
> Same, maybe to lesser degree, for GET_QUOTA.
Technically possible, too. So I can allow this one as well.

> 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.


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature