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

["Anthony PERARD" <anthony.perard@xxxxxxxxxx>]

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.

Thanks,

--

Anthony Perard | Vates XCP-ng Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech