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

[Julien Grall <julien@xxxxxxx>]

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?
> +    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?
> +XS_GET_FEATURE          23    optional
> +XS_SET_FEATURE          24    optional
> +    XS_SET_FEATURE requires XS_GET_FEATURE to be supported.
> +    If unsupported, setting availability of Xenstore features per
> +    domain is not possible.
> +XS_GET_QUOTA            25    optional
> +XS_SET_QUOTA            26    optional
> +    XS_SET_QUOTA requires XS_GET_QUOTA to be supported.
> +    If unsupported, setting of Xenstore quota per domain is not
> +    possible.
> +XS_INVALID           65535
> +    Guaranteed invalid type (never supported).
>   
>   ---------- Xenstore protocol details - introduction ----------
>   
Cheers,

--
Julien Grall