# HG changeset patch
# User Kamala Narasimhan <kamala.narasimhan@citrix.com>
# Date 1297800164 0
# Node ID e2fb56dfebdaebf4fe979ba0cf240ee3e315bc48
# Parent 2ede5d7934932f61095beeedcb2389c4b664cbe5
docs: document disk configuration string syntax (particularly, xl's syntax)
Signed-off-by: Kamala Narasimhan <kamala.narasimhan@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
docs/misc/xl-disk-configuration.txt | 154 ++++++++++++++++++++++++++++++++++++
1 files changed, 154 insertions(+)
diff -r 2ede5d793493 -r e2fb56dfebda docs/misc/xl-disk-configuration.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/xl-disk-configuration.txt Tue Feb 15 20:02:44 2011 +0000
@@ -0,0 +1,154 @@
+
+
+ ----------------------------
+ xl Disk Configuration Option
+ ----------------------------
+
+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.
+
+At a higher level, xl disk configuration option takes the following
+format:
+
+ disk = [ '[format:][path],vdev[:type],attrib',
+ '[format:][path],vdev[:type],attrib', ... ]
+
+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.
+
+
+------------------
+Attribute Details
+------------------
+
+
+format:
+------
+
+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 '/'.
+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
+ of this attribute would imply an empty cdrom
+ drive.
+
+vdev:
+----
+
+Description: Virtual device as seen by the guest (also
+ referred to as guest drive designation in some
+ specifications). See docs/misc/vbd-interface.txt.
+Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
+ above specification for further details.
+Deprecated values: None
+Mandatory: Yes
+
+type:
+----
+
+Description: Qualifies virtual device type.
+Supported values: cdrom
+Deprecated values: None
+Mandatory: No
+
+attrib:
+------
+
+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'
+Deprecated values: None
+Mandatory: Yes
+
+
+--------------
+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
+---------------------
+
+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:
+
+block-dev-type:
+--------------
+
+Description: Specifies the block device type.
+Supported values: phy,file, tap, tap2
+
+access-type:
+-----------
+
+Description: Backend implementation option to choose from
+ while accessing block device.
+ Example: tap:aio:vhd:/path/to/file
+Supported values: 'aio', 'tapdisk', 'ioemu'
+
+---------------------
+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.
+
+
+
+
+
+
+
_______________________________________________
Xen-changelog mailing list
Xen-changelog@lists.xensource.com
http://lists.xensource.com/xen-changelog
# User Kamala Narasimhan <kamala.narasimhan@citrix.com>
# Date 1297800164 0
# Node ID e2fb56dfebdaebf4fe979ba0cf240ee3e315bc48
# Parent 2ede5d7934932f61095beeedcb2389c4b664cbe5
docs: document disk configuration string syntax (particularly, xl's syntax)
Signed-off-by: Kamala Narasimhan <kamala.narasimhan@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
docs/misc/xl-disk-configuration.txt | 154 ++++++++++++++++++++++++++++++++++++
1 files changed, 154 insertions(+)
diff -r 2ede5d793493 -r e2fb56dfebda docs/misc/xl-disk-configuration.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/xl-disk-configuration.txt Tue Feb 15 20:02:44 2011 +0000
@@ -0,0 +1,154 @@
+
+
+ ----------------------------
+ xl Disk Configuration Option
+ ----------------------------
+
+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.
+
+At a higher level, xl disk configuration option takes the following
+format:
+
+ disk = [ '[format:][path],vdev[:type],attrib',
+ '[format:][path],vdev[:type],attrib', ... ]
+
+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.
+
+
+------------------
+Attribute Details
+------------------
+
+
+format:
+------
+
+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 '/'.
+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
+ of this attribute would imply an empty cdrom
+ drive.
+
+vdev:
+----
+
+Description: Virtual device as seen by the guest (also
+ referred to as guest drive designation in some
+ specifications). See docs/misc/vbd-interface.txt.
+Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
+ above specification for further details.
+Deprecated values: None
+Mandatory: Yes
+
+type:
+----
+
+Description: Qualifies virtual device type.
+Supported values: cdrom
+Deprecated values: None
+Mandatory: No
+
+attrib:
+------
+
+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'
+Deprecated values: None
+Mandatory: Yes
+
+
+--------------
+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
+---------------------
+
+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:
+
+block-dev-type:
+--------------
+
+Description: Specifies the block device type.
+Supported values: phy,file, tap, tap2
+
+access-type:
+-----------
+
+Description: Backend implementation option to choose from
+ while accessing block device.
+ Example: tap:aio:vhd:/path/to/file
+Supported values: 'aio', 'tapdisk', 'ioemu'
+
+---------------------
+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.
+
+
+
+
+
+
+
_______________________________________________
Xen-changelog mailing list
Xen-changelog@lists.xensource.com
http://lists.xensource.com/xen-changelog