[v4] docs: specify numerical values of Xenstore commands

Commit Message

Jürgen Groß March 13, 2025, 11:06 a.m. UTC

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 <[e-mail]>
Signed-off-by: Juergen Gross <[e-mail]>
---
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)
V3:
- specify error code returned for unsupported commands (Julien Grall)
- reword XS_DIRECTORY_PART related text (Julien Grall)
V4:
- drop "XS_" prefixes as they are language specific (Anthony Perard)
---
 docs/misc/xenstore.txt | 61 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

Comments

Anthony PERARD March 13, 2025, 12:53 p.m. UTC | #1

On Thu, Mar 13, 2025 at 12:06:40PM +0100, 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 <[e-mail]>
> Signed-off-by: Juergen Gross <[e-mail]>
> ---
> 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)
> V3:
> - specify error code returned for unsupported commands (Julien Grall)
> - reword XS_DIRECTORY_PART related text (Julien Grall)
> V4:
> - drop "XS_" prefixes as they are language specific (Anthony Perard)

Reviewed-by: Anthony PERARD <[e-mail]>

Thanks,

Patch

diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 7e1f031520..4eccbc2f7f 100644
--- a/docs/misc/xenstore.txt
+++ b/docs/misc/xenstore.txt
@@ -86,6 +86,67 @@  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.
+Any not supported type sent to Xenstore will result in an error response
+with the "ENOSYS" error.
+
+CONTROL               0    optional
+    If not supported, xenstore-control command will not work.
+    DEBUG is a deprecated alias of CONTROL.
+DIRECTORY             1
+READ                  2
+GET_PERMS             3
+WATCH                 4
+UNWATCH               5
+TRANSACTION_START     6
+TRANSACTION_END       7
+INTRODUCE             8
+RELEASE               9
+GET_DOMAIN_PATH      10
+WRITE                11
+MKDIR                12
+RM                   13
+SET_PERMS            14
+WATCH_EVENT          15
+    Not valid in client sent messages.
+    Only valid in Xenstore replies.
+ERROR                16
+    Not valid in client sent messages.
+    Only valid in Xenstore replies.
+IS_DOMAIN_INTRODUCED 17
+RESUME               18
+SET_TARGET           19
+RESTRICT             20    no longer supported
+    RESTRICT has been removed, the type value 20 is invalid.
+RESET_WATCHES        21
+DIRECTORY_PART       22    optional
+    If not supported, the output of xenstore-ls might be incomplete
+    with a node's sub-node list exceeding the maximum payload size
+    (e.g. the "/local/domain" node with more than ca. 1000 domains
+    active).
+GET_FEATURE          23    optional
+SET_FEATURE          24    optional
+    SET_FEATURE requires GET_FEATURE to be supported.
+    If unsupported, setting availability of Xenstore features per
+    domain is not possible.
+GET_QUOTA            25    optional
+SET_QUOTA            26    optional
+    SET_QUOTA requires GET_QUOTA to be supported.
+    If unsupported, setting of Xenstore quota per domain is not
+    possible.
+INVALID           65535
+    Guaranteed invalid type (never supported).
 
 ---------- Xenstore protocol details - introduction ----------