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

[Jürgen Groß <jgross@xxxxxxxx>]

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

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature