Ian Campbell writes ("Re: [Xen-devel] [PATCH 10/14] docs: update
xl-disk-configuration.txt to describe new syntax"):
> Since this is a bit of a total rewrite I've attached the patched up
> version of the file too for other people's convenience since the diff
> itself is almost unusable, hence I have snipped most of the - lines in
> the diff before commenting on the + bits.
Right.
> > +where each diskspec is in this form:
> > +
> > + [<key>=<value>|flag]*,
> > + [<target>, [<format>, [<vdev>, [<access>]]]],
> > + [<key>=<value>]*,
> > + [target=<target>]
>
> The actual meaning of this is pretty opaque. The paragraphs following
> "More formally" does a pretty good job of describing it but I still have
> a few questions/misunderstandings.
Do you think I should get rid of this template ?
> It's not obvious that the "[<target>, [<format>, [<vdev>,
> [<access>]]]]," bit specifies the "positional parameters" (I'm assuming
> they do) nor is it mentioned in the text whether or not the positional
> parameters must be contiguous if used.
>
> Are you using "*" to mean "0 or 1 of the preceding element" as opposed
> to "0 or more of the preceding element", I initially read it as the
> second which confused me because it suggests that a valid syntax could
> be
> [<key>=<value>|flag][<key>=<value>|flag][<key>=<value>|flag],
> whereas I expected it would need to be
> [<key>=<value>|flag],[<key>=<value>|flag],[<key>=<value>|flag],
> is the placement of either the "," or the "*" wrong and/or did you mean
> "?" rather than "*"?
No, it's just that the placement of the "," is wrong.
> > +Description: Block device or image file path. For a
> > + physical block device a /dev will be prepended
> > when not specified and when the path doesn't
> > + start with a '/'.
>
> Won't we prepend a /dev/ for any path, regardless of whether it is a
> physical block device or an image file? Granted it's not likely to be
> all that useful in the second case but we can't really distinguish the
> two until too late.
Yes, this is a good point.
> > +Deprecated values are acceptable and are intended work compatibly with
> > +xend and xl from xen 4.1. In future they may print a warning.
> > +Support for deprecated parameters and syntaxes are likely to be
> > +dropped in future versions of xl.
> >
> > +There is also support for a deprecated old syntax for <diskspec>:
> >
> > + [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
> >
> > +This syntax also supports deprecated prefixes, described below. These
> > +are found prepended to the format parameter - eg "tap:aio:qcow:".
>
> Are valid <format>s a fixed list of existing formats which will not be
> extended as list of supported formats grows in the future, IOW new
> formats will only be available via the format positional paramter?
That is correct.
> > +<block-dev-type>:
> > +-----------------
>
> That tag doesn't appear anywhere in the syntax description, so it's not
> clear where it is allowable. I'd assume it was <devtype> above if I
> didn't know any better...
>
> > +Description: Specifies the block device type.
> > +Supported values: phy,file, tap, tap2
> ^ whitespace
I think this is a leftover which should be deleted.
> > +<access-type>:
> > +--------------
>
> Spelled <access> above?
No. It should be backend-type.
I will send out a fixed version.
Ian.
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel
|
Home