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

[Jan Beulich <jbeulich@xxxxxxxx>]

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.

Also the 1000 domains boundary is just an example aiui, so you may want
to add "e.g.".

> +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?

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

I'm further uncertain here regarding your use of hard tabs.

Jan