Re: [Xen-devel] [PATCH 10/14] docs: update xl-disk-configuration.txt to describe new syntax

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

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.

On Thu, 2011-05-12 at 15:36 +0100, Ian Jackson wrote:
> ---
>  docs/misc/xl-disk-configuration.txt |  221 +++++++++++++++++++---------------
>  1 files changed, 123 insertions(+), 98 deletions(-)
> 
> diff --git a/docs/misc/xl-disk-configuration.txt 
> b/docs/misc/xl-disk-configuration.txt
> index 58332a9..90ba54e 100644
> --- a/docs/misc/xl-disk-configuration.txt
> +++ b/docs/misc/xl-disk-configuration.txt
> @@ -1,57 +1,99 @@
> +                     ---------------------
> +                     XL DISK CONFIGURATION
> +                     ---------------------
> 
> +This document specifies the xl config file format disk configuration
> +option.  It the following form:

            In ?

[...]
> +    disk = [ '<diskspec>', '<diskspec>', ... ]
[...]
> +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.

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 "*"?

> +=====================
> +POSITIONAL PARAMETERS
> +=====================
> +
> +target
> +------
> +
> +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.

[...]

> +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?
 
> 
> +<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
> 
> +<access-type>:
> +--------------

Spelled <access> above?

> +Description:           Backend implementation option to choose from
> +                       while accessing block device.
> +                       Example: tap:aio:vhd:/path/to/file
> +Supported values:      'aio', 'tapdisk', 'ioemu'
> --
> 1.7.2.5
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxxxxxxxx
> http://lists.xensource.com/xen-devel

Attachment: xl-disk-configuration.txt
Description: Text document

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel