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@suse.com>
Signed-off-by: Juergen Gross <jgross@suse.com>
---
docs/misc/xenstore.txt | 59 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 7e1f031520..76001c6ee6 100644
--- 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.
+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.
+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.
+XS_INVALID 65535
+ Guaranteed invalid type (never supported).
---------- Xenstore protocol details - introduction ----------
--
2.43.0
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
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
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
On 06.03.25 14:09, Jan Beulich wrote: > 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? Not without someone trying to force this by will (only possible by a root user of dom0, e.g. via creating lots of nodes in the same directory via "xenstore-write"). Having lots of domains is an "easy" way to create this scenario via perfectly valid and sensible operations. > >>> 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. Fair enough. I'm going to switch to blanks for the table. Juergen
© 2016 - 2025 Red Hat, Inc.