[PATCH 1/5] Xl Disk Configuration Option Documentation

[PATCH 1/5] Xl Disk Configuration Option Documentation

[Kamala Narasimhan]

[-- Attachment #1: Type: text/plain, Size: 166 bytes --]

Attached is a documentation of Xl disk configuration option that has already been reviewed.

Signed-off-by: Kamala Narasimhan <kamala.narasimhan@citrix.com>

Kamala


[-- Attachment #2: xl-disk-config-option-doc.diff --]
[-- Type: text/x-diff, Size: 5598 bytes --]

diff -r e4406b9fb064 docs/misc/xl-disk-configuration.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/xl-disk-configuration.txt	Mon Feb 07 12:37:47 2011 -0500
@@ -0,0 +1,155 @@
+
+
+                         ----------------------------
+                         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).  [ @TODO:  Refer to IanJ's virtual
+                       disk specification here.]
+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.
+
+
+
+
+
+
+

[-- Attachment #3: Type: text/plain, Size: 138 bytes --]

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

Re: [PATCH 1/5] Xl Disk Configuration Option Documentation

[Ian Jackson]

Kamala Narasimhan writes ("[xen-devel][PATCH 1/5] Xl Disk Configuration Option Documentation"):
> Attached is a documentation of Xl disk configuration option that has already been reviewed.

Thanks, this looks good.  AIUI it describes the situation after the
rest of your series has been applied so it should be committed after
all the rest, or at least with the rest ?

There are a couple of tiny formatting issues which I can fix up when I
commit it:

> +Description:           Qualifies  virtual device type.
                                   ^^
and the trailing whitespace.

And:

> +                       specifications).  [ @TODO:  Refer to IanJ's virtual
> +                       disk specification here.]

I think this TODO is fine to commit as-is, but you'll see that I've
just reposted my vbd specification doc.  Depending on the order of the
commits I will fix this up.

Ian.

Re: [PATCH 1/5] Xl Disk Configuration Option Documentation

[Kamala Narasimhan]

Ian Jackson wrote:
> Kamala Narasimhan writes ("[xen-devel][PATCH 1/5] Xl Disk Configuration Option Documentation"):
>> Attached is a documentation of Xl disk configuration option that has already been reviewed.
> 
> Thanks, this looks good.  AIUI it describes the situation after the
> rest of your series has been applied so it should be committed after
> all the rest, or at least with the rest ?
> 
Good point.  I think it can go first as most part of it describes the current
state.  But there are a couple of changes that switches some attributes to
optional that would be better handled once the rest of the patches are applied.
 But the core details hasn't changed as much. So could be applied first IMO.

> There are a couple of tiny formatting issues which I can fix up when I
> commit it:
> 
>> +Description:           Qualifies  virtual device type.
>                                    ^^
> and the trailing whitespace.
> 
> And:
> 
>> +                       specifications).  [ @TODO:  Refer to IanJ's virtual
>> +                       disk specification here.]
> 
> I think this TODO is fine to commit as-is, but you'll see that I've
> just reposted my vbd specification doc.  Depending on the order of the
> commits I will fix this up.
> 
Thanks for fixing up those.

Kamala