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

[Jan Beulich <jbeulich@xxxxxxxx>]

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?

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

Jan