Re: [Xen-devel] [DOCDAY PATCH] docs: initial documentation for xenstore paths

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Ian Campbell writes ("Re: [DOCDAY PATCH] docs: initial documentation for 
xenstore paths"):
> On Thu, 2012-08-09 at 15:02 +0100, Ian Jackson wrote:
> > Ian Campbell writes ("Re: [DOCDAY PATCH] docs: initial documentation for 
> > xenstore paths"):
> > ...
> > > > --- a/docs/misc/xenstore-paths.markdown
> > > > +++ b/docs/misc/xenstore-paths.markdown
> > > > @@ -0,0 +1,294 @@
> > ...
> > > > +PATH can contain simple regex constructs following the POSIX regexp
> > > > +syntax described in regexp(7). In addition the following additional
> > > > +wild card names are defined and are evaluated before regexp expansion:
> > 
> > Can we use a restricted perl re syntax ?  That avoids weirdness with
> > the rules for \.
> 
> Is "restricted perl re syntax" a well defined thing (reference?) or do
> you just mean perlre(1)--?

I mean pcre, or perlre(1), probably.

> What's the weirdness with \.?

In Perl syntax, a punctuation character preceded by \ is always a
literal, and all metacharacters are unbackslashed punctuation.

In regexp(7) you need to remember which of ( ) | [ ] . & $ need
\-escaping to be literals and which need \-annotating to be
metacharacters.  (And there are various dialects of this too; for
example Emacs regexps require \ in front of a different subset of the
punctuation.)

I don't particularly care about all the fancy (?:...) etc. extensions,
but being able to write the regexp without referring to the manual, or
experimenting, is very good - particularly in a document which will be
tested at most rather indirectly.

> > > > +The process ID of the device model associated with this domain, if it
> > > > +has one.
> > > > +
> > > > +XXX why is this visible to the guest?
> > 
> > I think some of these things were put here just because there wasn't
> > another place for the toolstack to store things.  See also the
> > arbitrary junk stored by scripts in the device backend directories.
> 
> Should we define a proper home for these? e.g. /$toolstack/$domid?

Yes, we should, but the purpose of the doc is to document what we do
now, not what we will do :-).  I just replied to explain your XXX.

> > Should have a cross-reference to the cpu online/offline protocol,
> > which appears to be in xen/include/public/vcpu.h.  It doesn't seem to
> > be fully documented yet.
> 
> vcpu.h has the hypercalls which are the mechanism by which a guest
> brings a cpu up/down but nothing on the xenstore protocol which might
> cause it to do so.
> 
> I don't think a reference currently exists for that protocol. This
> probably belongs in the same (non-existent) protocol doc as
> ~/control/shutdown in so much as it is a toolstack<->guest kernel
> protocol.

Right.  Well, then a cross-reference to vcpu.h is in order along with
remarks along the lines you quote about the lack of a proper protocol
document.

> > This should have a cross-reference to the documentation defining
> > static-max etc.  I thought we had some in tree but I can't seem to
> > find it.  The best I can find is docs/man/xl.cfg.pod.5.
> 
> I think you might be thinking of tools/libxl/libxl_memory.txt.
> 
> Shall we move that doc to docs/misc?

Good idea.

> Perhaps:
> 
>         every effort to ... reach this target
> 
> ? but I'm not sure that is strictly correct, a guest can use less if it
> wants to. So perhaps
> 
>         every effort to ... not use more than this
>         
> ? seems clumsy though.

:-).  These all seem fine to me.

> > > > +#### ~/device/suspend/event-channel = ""|EVTCHN [w]
> > > > +
> > > > +The domain's suspend event channel. The use of a suspend event channel
> > > > +is optional at the domain's discression. If it is not used then this
> > > > +path will be left blank.
> > 
> > May it be ENOENT ?  Does the toolstack create it as "" then ?
> 
> libxl seems to *mkdir* it:
>     libxl__xs_mkdir(gc, t,
>                     libxl__sprintf(gc, "%s/device/suspend/event-channel", 
> dom_path),
>                     rwperm, ARRAY_SIZE(rwperm));
> 
> which I suppose is the same as writing it as "" (unless there is some
> subtle xenstore semantic difference I'm not thinking of)

As docs/misc/xenstore.txt says:

 If a particular path exists, all of its parents do too.  Every
 existing path maps to a possibly empty value, and may also have zero
 or more immediate children.  There is thus no particular distinction
 between directories and leaf nodes.  However, it is conventional not
 to store nonempty values at nodes which also have children.

The difference between MKDIR and WRITE is simply that if there is an
existing node, WRITE overwrites its value and MKDIR leaves it
unchanged.  See the doc.

> > > > +XXX why is this exposed to the guest?
> > 
> > Is there really only one event channel ?  Ie the same evtchn is used
> > to signal to xenstore that the guest has sent a command, and to signal
> > the guest that xenstore has written the response ?
> 
> Yes, event channels are bidirectional so that's quite common.

Oh, I didn't realise they were bidirectional.

> > Anyway surely this is something the guest needs to know.  Why it's in
> > xenstore is a bit of a mystery since you can't use xenstore without it
> > and it's in the start_info.
> 
> I should have written "why is this exposed to the guest via xenstore?"

Right.  OK.

> > Is this the same value as start_info.store_evtchn ?  Cross reference ?
> 
> I'd be semi inclined to ditch/deprecate it unless we can figure out what
> it is for -- as you say there is something of a chicken and egg problem
> with using it.

I think it's fine to deprecate it.

> > I think it's not specified anywhere.  It's ad-hoc.  The guest
> > shouldn't need to see it but exposing it readonly is probably
> > harmless.  Except perhaps for the vnc password ?
> 
> vnc password appears to go into /vm/$uuid/vncpass (looking at libxl code
> only).

Yuk.  We want to abolish /vm/$uuid/ surely.

> AFAIK it does nothing special with the perms, but /vm/$uuid is not guest
> readable (perms are "n0") so I think that works out ok.
> 
> I wonder if that's part of the point of /vm/$uuid.

Perhaps we should make a new directory for this.  We do seem to have
quite a bit of cruft in our system which attempting to write this
document is revealing.

The right answer is probably to mention it in the doc as "likely to
move".

> > > > +### /vm/$UUID/uuid = UUID []
> > > > +
> > > > +Value is the same UUID as the path.
> > > > +
> > > > +### /vm/$UUID/name = STRING []
> > > > +
> > > > +The domains name.
> > 
> > IMO this should be
> >   (a) in /local/domain/$DOMID
> >   (b) also a copy in /byname/$NAME = $DOMID   for fast lookup
> > but not in 4.2.
> > 
> > Guests shouldn't rely on it.  In fact do guests actually need anything
> > from here ?
> 
> I'd say definitely not, but it has existed with xend for many years so
> I'd be surprised if something hadn't crept in somewhere :-(

Yers.

We should at least say that guests shouldn't use it.

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel