[PATCH] Improve documentation of the blkif interface

[PATCH] Improve documentation of the blkif interface

[Justin T. Gibbs]

 o Fix typo "discard-aligment" -> "discard-alignment"
 o Fix typo "unamp" -> "unmap"
 o Fix typo "formated" -> "formatted"
 o Clarify the text for "params".
 o Clarify the text for "sector-size".

No functional changes.

Signed-off-by: Justin T. Gibbs <justing@spectralogic.com>

diff -r a7bacdc5449a -r 932a05fb73bb xen/include/public/io/blkif.h
--- a/xen/include/public/io/blkif.h	Mon Feb 27 17:05:18 2012 +0000
+++ b/xen/include/public/io/blkif.h	Wed Feb 29 15:07:54 2012 -0700
@@ -59,7 +59,7 @@
  * All data in the XenStore is stored as strings.  Nodes specifying numeric
  * values are encoded in decimal.  Integer value ranges listed below are
  * expressed as fixed sized integer types capable of storing the conversion
- * of a properly formated node string, without loss of information.
+ * of a properly formatted node string, without loss of information.
  *
  * Any specified default value is in effect if the corresponding XenBus node
  * is not present in the XenStore.
@@ -88,9 +88,9 @@
  * params
  *      Values:         string
  *
- *      A free formatted string providing sufficient information for the
- *      backend driver to open the backing device.  (e.g. the path to the
- *      file or block device representing the backing store.)
+ *      Data used by the backend driver to locate and configure the backing
+ *      device.  The format and semantics of this data vary according to the
+ *      backing device in use and are outside the scope of this specification.
  *
  * type
  *      Values:         "file", "phy", "tap"
@@ -147,7 +147,7 @@
  *
  *------------------------- Backend Device Properties -------------------------
  *
- * discard-aligment
+ * discard-alignment
  *      Values:         <uint32_t>
  *      Default Value:  0
  *      Notes:          4, 5
@@ -180,7 +180,8 @@
  * sector-size
  *      Values:         <uint32_t>
  *
- *      The native sector size, in bytes, of the backend device.
+ *      The size, in bytes, of the individually addressible data blocks
+ *      on the backend device.
  *
  * sectors
  *      Values:         <uint64_t>
@@ -261,11 +262,11 @@
  * -----
  * (1) Multi-page ring buffer scheme first developed in the Citrix XenServer
  *     PV drivers.
- * (2) Multi-page ring buffer scheme first used in some RedHat distributions
+ * (2) Multi-page ring buffer scheme first used in some Red Hat distributions
  *     including a distribution deployed on certain nodes of the Amazon
  *     EC2 cluster.
  * (3) Support for multi-page ring buffers was implemented independently,
- *     in slightly different forms, by both Citrix and RedHat/Amazon.
+ *     in slightly different forms, by both Citrix and Red Hat/Amazon.
  *     For full interoperability, block front and backends should publish
  *     identical ring parameters, adjusted for unit differences, to the
  *     XenStore nodes used in both schemes.
@@ -387,7 +388,7 @@
  * discarded region on the device must be rendered unrecoverable before the
  * command returns.
  *
- * This operation is analogous to performing a trim (ATA) or unamp (SCSI),
+ * This operation is analogous to performing a trim (ATA) or unmap (SCSI),
  * command on a native device.
  *
  * More information about trim/unmap operations can be found at:

Re: [PATCH] Improve documentation of the blkif interface

[Ian Jackson]

Justin T. Gibbs writes ("[Xen-devel] [PATCH] Improve documentation of the blkif interface"):
>  o Fix typo "discard-aligment" -> "discard-alignment"
>  o Fix typo "unamp" -> "unmap"
>  o Fix typo "formated" -> "formatted"
>  o Clarify the text for "params".
>  o Clarify the text for "sector-size".
> 
> No functional changes.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Keir, is it OK in general for me to commit these kind of docs changes
to the xen headers (provided they strictly are docs changes and don't
mess with the #defines etc.) ?

Thanks,
Ian.

Re: [PATCH] Improve documentation of the blkif interface

[Keir Fraser]

On 01/03/2012 15:32, "Ian Jackson" <Ian.Jackson@eu.citrix.com> wrote:

> Justin T. Gibbs writes ("[Xen-devel] [PATCH] Improve documentation of the
> blkif interface"):
>>  o Fix typo "discard-aligment" -> "discard-alignment"
>>  o Fix typo "unamp" -> "unmap"
>>  o Fix typo "formated" -> "formatted"
>>  o Clarify the text for "params".
>>  o Clarify the text for "sector-size".
>> 
>> No functional changes.
> 
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
> 
> Keir, is it OK in general for me to commit these kind of docs changes
> to the xen headers (provided they strictly are docs changes and don't
> mess with the #defines etc.) ?

Yep, fine with me.

 -- Keir

> Thanks,
> Ian.