This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
Home Products Support Community News


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

To: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
Subject: Re: [Xen-devel] [PATCH 10/14] docs: update xl-disk-configuration.txt to describe new syntax
From: Ian Campbell <Ian.Campbell@xxxxxxxxxx>
Date: Fri, 13 May 2011 13:45:47 +0100
Cc: "xen-devel@xxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxx>
Delivery-date: Fri, 13 May 2011 05:48:38 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
In-reply-to: <1305211004-31687-11-git-send-email-ian.jackson@xxxxxxxxxxxxx>
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
Organization: Citrix Systems, Inc.
References: <1305211004-31687-1-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-2-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-3-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-4-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-5-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-6-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-7-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-8-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-9-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-10-git-send-email-ian.jackson@xxxxxxxxxxxxx> <1305211004-31687-11-git-send-email-ian.jackson@xxxxxxxxxxxxx>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
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
whereas I expected it would need to be
is the placement of either the "," or the "*" wrong and/or did you mean
"?" rather than "*"?

> +=====================
> +=====================
> +
> +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'
> --
> _______________________________________________
> 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
<Prev in Thread] Current Thread [Next in Thread>