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"):
...
> > --- 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 \.  Also how does this interact with markdown ?

> > +#### ~/image/device-model-pid = INTEGER   [r]

This [r] tag is not defined above.  I assume you mean "readonly to the
domain" but that's the default.  Left over from an earlier version ?

> > +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.

> > +#### ~/cpu/[0-9]+/availability = ("online"|"offline") [PV]
> > +
> > +One node for each virtual CPU up to the guest's configured
> > +maximum. Valid values are "online" and "offline". 

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.

> > +#### ~/memory/static-max = MEMKB []
> > +
> > +Specifies a static maximum amount memory which this domain should
> > +expect to be given. In the absence of in-guest memory hotplug support
> > +this set on domain boot and is usually the maximum amount of RAM which
> > +a guest can make use of .

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.

> > +#### ~/memory/target = MEMKB []
> > +
> > +The current balloon target for the domain. The balloon driver within the 
> > guest is expected to make every effort 

every effort to ... ?

The interaction with the Xen maximum should be stated, preferably by
cross-reference.  In general it might be better to have a single place
where all these values and their semantics are written down ?

> > +#### ~/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 ?

> > +#### ~/device/serial/$DEVID/* [HVM]
> > +
> > +An emulated serial device

You should presumably add
    XXX documentation for the protocol needed
here.

> > +#### ~/store/port = EVTCHN []
> > +
> > +The event channel used by the domains connection to XenStore.

Apostrophe.

> > +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 ?

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.

Is this the same value as start_info.store_evtchn ?  Cross reference ?

> > +#### ~/store/ring-ref = GNTREF []
> > +
> > +The grant reference of the domain's XenStore ring.
> > +
> > +XXX why is this exposed to the guest?

See above.

> > +#### ~/device-model/$DOMID/* []
> > +
> > +Information relating to device models running in the domain. $DOMID is
> > +the target domain of the device model.
> > +
> > +XXX where is the contents of this directory specified?

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 ?

> > +## Virtual Machine paths
> > +
> > +XXX somehow describe how /vm is different to /local/domain/

See my other email.

> > +### /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 ?

Ian.

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