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

[Jürgen Groß]

On 13.03.25 11:16, Anthony PERARD wrote:

On Thu, Mar 13, 2025 at 10:51:06AM +0100, Jürgen Groß wrote:

On 12.03.25 17:46, Anthony PERARD wrote:

On Wed, Mar 12, 2025 at 09:41:43AM +0100, Juergen Gross wrote:

diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 7e1f031520..72db73deef 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
+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

This new table prefix message type names with "XS_", but the rest of the
document describe each type without the prefix. Isn't it going to be
confusing, and make it slightly harder to link this table to rest of the
document? (I often search by full word, like '\<GET_PERMS\>', because
that one key stroke in vim '*', so having different prefix makes it
harder to search)

Question is, should I change the table to drop "XS_", or the rest document
to add "XS_" instead? After all xs_wire.h is defining the names with "XS_".

I'm slightly leaning towards a preparatory patch adding "XS_".

Well, I'm actually for dropping the prefix from the table. The prefix is
more of a C specific namespace than anything else. The ocaml
implementation in tree doesn't use this prefix, but a different one (if
we ignore the different case:

Xenbus.Xb.Op.Watch

https://elixir.bootlin.com/xen/v4.20.0/source/tools/ocaml/xenstored/process.ml#L632
And have a link to a string without the prefix:

| Watch                 -> "WATCH"

https://elixir.bootlin.com/xen/v4.20.0/source/tools/ocaml/libs/xb/op.ml#L49

There's also a version in Rust which also use a different prefix,
"XsMessageType::".
https://github.com/Wenzel/xenstore/blob/f82bd45cbcd1aa98306c57d35847e3d77f7cc8ee/src/wire.rs#L55

So the prefix is really programming language specific and I don't think
introducing it to this document would be useful.

Fair enough. Stay tuned for V4. :-)


Juergen

OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

OpenPGP_signature.asc
Description: OpenPGP digital signature