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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Thu, 2011-06-02 at 18:55 +0100, Ian Jackson wrote:

You forgot your signed-off.

Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

> ---
>  docs/misc/xl-disk-configuration.txt |  249 
> +++++++++++++++++++++--------------
>  1 files changed, 150 insertions(+), 99 deletions(-)
> 
> diff --git a/docs/misc/xl-disk-configuration.txt 
> b/docs/misc/xl-disk-configuration.txt
> index 58332a9..de0a75e 100644
> --- a/docs/misc/xl-disk-configuration.txt
> +++ b/docs/misc/xl-disk-configuration.txt
> @@ -1,57 +1,98 @@
> +                     ---------------------
> +                     XL DISK CONFIGURATION
> +                     ---------------------
> 
> +This document specifies the xl config file format disk configuration
> +option.  It has the following form:
> 
> -                         ----------------------------
> -                         xl Disk Configuration Option
> -                         ----------------------------
> +    disk = [ '<diskspec>', '<diskspec>', ... ]
> 
> -This document provides a brief description of xl disk configuration
> -option, different attributes that can be passed through it and the
> -format in which they need to be specified.
> +where each diskspec is in this form:
> +
> +   [<key>=<value>|<flag>,]*,
> +     [<target>, [<format>, [<vdev>, [<access>]]]],
> +     [<key>=<value>|<flag>,]*
> +     [target=<target>]
> 
> -At a higher level, xl disk configuration option takes the following
> -format:
> 
> -    disk = [ '[format:][path],vdev[:type],attrib',
> -             '[format:][path],vdev[:type],attrib', ... ]
> +For example, these strings are equivalent:
> 
> -Not all attributes are required (the attributes enclosed within square
> -brackets above are optional) and some are deprecated.  Following is a
> -brief description of each of the attribute along with information on
> -whether or not they are mandatory.
> +  /dev/vg/guest-volume,,hda
> +  /dev/vg/guest-volume,raw,hda,rw
> +  format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
> +  raw:/dev/vg/guest-volume,hda,w   (deprecated, see below)
> 
> +As are these:
> 
> -------------------
> -Attribute Details
> -------------------
> +  /root/image.iso,,hdc,cdrom
> +  /root/image.iso,,hdc,,cdrom
> +  /root/image.iso,raw,hdc,devtype=cdrom
> +  format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
> +  raw:/root/image.iso,hdc:cdrom,ro   (deprecated, see below)
> 
> +These might be specified in the domain config file like this:
> 
> -format:
> -------
> +  disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
> 
> -Description:           Specifies the format of image file.
> -Supported values:      raw, qcow, qcow2, vhd
> -Deprecated values:     None
> -Mandatory:             No.  When not specified raw format is assumed.
> -                       For a physical block device the format must be
> -                       raw and need not be explicitly specified.  For
> -                       an image file the format could be one of the
> -                       supported values and when not specified assumed
> -                       to be raw.
> -path:
> -----
> 
> -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 '/'.
> +More formally, the string is a series of comma-separated keyword/value
> +pairs, flags and positional parameters.  Parameters which are not bare
> +keywords and which do not contain "=" symbols are assigned to the
> +so-far-unspecified positional parameters, in the order below.  The
> +positional parameters may also be specified explicitly by name.
> +
> +Each parameter may be specified at most once, either as a positional
> +parameter or a named parameter.  Default values apply if the parameter
> +is not specified, or if it is specified with an empty value (whether
> +positionally or explicitly).
> +
> +Whitespace may appear before each parameter and will be ignored.
> +
> +
> +=====================
> +POSITIONAL PARAMETERS
> +=====================
> +
> +target
> +------
> +
> +Description:           Block device or image file path.  When this is
> +                       used as a path, /dev will be prepended
> +                       if the path doesn't start with a '/'.
>  Supported values:      N/A
>  Deprecated values:     N/A
> -Mandatory:             No.  While a path is provided in most cases
> -                       there is an exception.  For a cdrom device, lack
> +Default value:         None.  While a path is provided in most cases
> +                       there is an exception: for a cdrom device, lack
>                         of this attribute would imply an empty cdrom
>                         drive.
> 
> -vdev:
> +Special syntax:
> +
> +   When this parameter is specified by name, ie with the "target="
> +   syntax in the configuration file, it consumes the whole rest of the
> +   <diskspec>.  Therefore in that case it must come last.  This is
> +   permissible even if an empty value for the target was already
> +   specifed as a positional parameter.  This is the only way to
> +   specify a target string containing metacharacters such as commas
> +   and (in some cases) colons, which would otherwise be
> +   misinterpreted.
> +
> +   Future parameter and flag names will start with an ascii letter and
> +   contain only ascii alphanumerics, hyphens and underscores, and will
> +   not be legal as vdevs.  Targets which might match that syntax
> +   should not be specified as positional parameters.
> +
> +
> +format
> +------
> +
> +Description:           Specifies the format of image file.
> +Supported values:      raw, qcow, qcow2, vhd
> +Deprecated values:     None
> +Default value:         raw
> +
> +
> +vdev
>  ----
> 
>  Description:           Virtual device as seen by the guest (also
> @@ -60,95 +101,105 @@ Description:           Virtual device as seen by the 
> guest (also
>  Supported values:      hd[x], xvd[x], sd[x] etc.  Please refer to the
>                         above specification for further details.
>  Deprecated values:     None
> -Mandatory:             Yes
> +Default Value:         None, this parameter is mandatory.
> 
> -type:
> -----
> -
> -Description:           Qualifies virtual device type.
> -Supported values:      cdrom
> -Deprecated values:     None
> -Mandatory:             No
> 
> -attrib:
> -------
> +access
> +-------
> 
>  Description:           Specified access control information.  Whether
>                         or not the block device is provided to the
>                         guest in read-only or read-write mode depends
>                         on this attribute.
> -Supported values:      'r', 'w'
> +Supported values:      ro, r   (specifies read-only)
> +                       rw, w   (specifies read/write)
>  Deprecated values:     None
> -Mandatory:             Yes
> +Default value:         rw
> +                       unless devtype=cdrom, in which case r
> 
> 
> ---------------
> -Example usages
> ---------------
> 
> -disk = [ 'vhd:/path/to/dev,hda,w', '/path/to/iso,hdc:cdrom,r' ]
> -disk = [ 'path/to/phy/dev,hda,w', '/dev/cdrom,hdc:cdrom,r' ]
> -disk = [ 'qcow:/path/to/file,hda,w' ]
> -disk = [ 'qcow2:/path/to/file,hda,w', 'raw:/path/to/dev,hdc:cdrom,r' ]
> +==========================
> +OTHER PARAMETERS AND FLAGS
> +==========================
> 
> 
> --------------------------
> -Miscellaneous Information
> --------------------------
> +devtype=<devtype>
> +-----------------
> 
> ----------------------
> -Deprecated Attributes
> ----------------------
> +Description:           Qualifies virtual device type.
> +Supported values:      cdrom
> +Deprecated values:     None
> +Mandatory:             No
> 
> -Deprecated values are acceptable and will work the way they did
> -earlier except with a warning message printed to the xl log or screen.
> -However it's usage is supported purely for backward compatibility
> -purpose and not recommended. Also, support for these deprecated
> -attributes are likely to be dropped in future versions of xl.
> 
> -The block-dev-type and access-type deprecated attributes described
> -below are prepended to the format attribute.  Example - tap:aio:qcow
> -Further details on the deprecated attributes are below:
> +cdrom
> +-----
> 
> -block-dev-type:
> ---------------
> +Convenience alias for "devtype=cdrom".
> 
> -Description:           Specifies the block device type.
> -Supported values:      phy,file, tap, tap2
> 
> -access-type:
> ------------
> +script=<script>
> +---------------
> 
> -Description:           Backend implementation option to choose from
> -                       while accessing block device.
> -                       Example: tap:aio:vhd:/path/to/file
> -Supported values:      'aio', 'tapdisk', 'ioemu'
> +Specifies that <target> is not a normal host path, but rather
> +information to be interpreted by /etc/xen/scripts/block-<script>.
> 
> ----------------------
> -Impementation Details
> ----------------------
> 
> -Backend Details:
> ----------------
> 
> -For 'phy' block device type, blkback is always used as the backend.
> -When the running dom0 instance does not support blkback, block device
> -access will fail.  For block device type 'file' with format raw or
> -when no format specfied, tapdisk2 is used when present otherwise qemu
> -fallback option is used.  For 'file', 'tap' or 'tap2' block device
> -type with format 'vhd', only tapdisk2 is used as qemu does not support
> -vhd format.  Absence of tapdisk2 support in this case will result in
> -failure.  When it comes to image format and how that affects the
> -backend choice, for qcow/qcow2 qemu backend is used as tapdisk2 does
> -not work with these formats. For raw format image file, tapdisk2 is
> -used and when not available qemu backend is used as fallback.  For vhd
> -format, as mentioned earlier tapdisk2 is used and tapdisk2
> -unavailability will result in failure as qemu fallback option does not
> -support vhd file format.
> +==================================
> +DEPRECATED PARAMETERS AND PREFIXES
> +==================================
> +
> +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:".
> +
> +
> +<format>:
> +---------
> +
> +Description:           Specifies the format (deprecated)
> +Supported values:      raw:  qcow2:  vhd:
> +
> +In xend and old versions of libxl it was necessary to specify the
> +format with a prefix.  For compatibility, these three prefixes are
> +recognised as specifying the corresponding format.  They are
> +equivalent to "format=<format>" or the specification of <format>
> +(without a colon) as a positional parameter.
> +
> +
> +<script>:
> +---------
> 
> +Description:           Specifies the script (deprecated)
> +Supported values:      iscsi:  nbd:  enbd:  drbd:
> 
> +In xend and old versions of libxl it was necessary to specify the
> +"script" (see above) with a prefix.  For compatibility, these four
> +prefixes are recognised as specifying the corresponding script.  They
> +are equivalent to "script=<script>".
> 
> 
> +<deprecated-prefix>:
> +--------------------
> 
> +Description;          Deprecated prefix, ignored
> +Supported values:     tapdisk:  tap2:  aio:  ioemu:  file:  phy:
> 
> +Various prefixes were required by xend and older versions of libxl to
> +make the block devices work.  In some cases these options would
> +override the backend type, but in other cases they would be ignored in
> +favour of "making it work"; in yet other cases it would be necessary
> +to specify several of these, for example:
> +  "tap:aio:/some/path..."
> 
> +All of these prefixes are now stripped and ignored.
> --
> 1.5.6.5
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxxxxxxxx
> http://lists.xensource.com/xen-devel



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