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


[Xen-devel] [PATCH 4/9] docs: update xl-disk-configuration.txt to descri

 docs/misc/xl-disk-configuration.txt |  249 +++++++++++++++++++++--------------
 1 files changed, 150 insertions(+), 99 deletions(-)

diff --git a/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
-    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:
+  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.
-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.
+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
+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.
+Description:           Specifies the format of image file.
+Supported values:      raw, qcow, qcow2, vhd
+Deprecated values:     None
+Default value:         raw
 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.
-Description:           Qualifies virtual device type.
-Supported values:      cdrom
-Deprecated values:     None
-Mandatory:             No
 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' ]
-Miscellaneous Information
-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:
+Convenience alias for "devtype=cdrom".
-Description:           Specifies the block device type.
-Supported values:      phy,file, tap, tap2
-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 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:".
+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.
+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>".
+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.

Xen-devel mailing list