[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Xen-devel] [PATCH 4 of 5] blkif.h: Document the RedHat and Citrix blkif multi-page ring extensions



 xen/include/public/io/blkif.h |  101 ++++++++++++++++++++++++++++++++++++-----
 1 files changed, 87 insertions(+), 14 deletions(-)


No functional changes.

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

diff -r 65403351f4b4 -r c3609ad53946 xen/include/public/io/blkif.h
--- a/xen/include/public/io/blkif.h     Thu Feb 02 16:19:57 2012 -0700
+++ b/xen/include/public/io/blkif.h     Thu Feb 02 16:19:57 2012 -0700
@@ -100,6 +100,25 @@
  *      of this type may still be returned at any time with the
  *      BLKIF_RSP_EOPNOTSUPP result code.
  *
+ *----------------------- Request Transport Parameters ------------------------
+ *
+ * max-ring-page-order
+ *      Values:         <uint32_t>
+ *      Default Value:  0
+ *      Notes:          1, 3
+ *
+ *      The maximum supported size of the request ring buffer in units of
+ *      lb(machine pages). (e.g. 0 == 1 page,  1 = 2 pages, 2 == 4 pages,
+ *      etc.).
+ *
+ * max-ring-pages
+ *      Values:         <uint32_t>
+ *      Default Value:  1
+ *      Notes:          2, 3
+ *
+ *      The maximum supported size of the request ring buffer in units of
+ *      machine pages.  The value must be a power of 2.
+ *
  *----------------------- Backend Device Identification -----------------------
  * mode
  *      Values:         "r" (read only), "w" (writable)
@@ -124,7 +143,7 @@
  * discard-aligment
  *      Values:         <uint32_t>
  *      Default Value:  0
- *      Notes:          1, 2
+ *      Notes:          4, 5
  *
  *      The offset, in bytes from the beginning of the virtual block device,
  *      to the first, addressable, discard extent on the underlying device.
@@ -132,7 +151,7 @@
  * discard-granularity
  *      Values:         <uint32_t>
  *      Default Value:  <"sector-size">
- *      Notes:          1
+ *      Notes:          4
  *
  *      The size, in bytes, of the individually addressable discard extents
  *      of the underlying device.
@@ -176,10 +195,20 @@
  *
  * ring-ref
  *      Values:         <uint32_t>
+ *      Notes:          6
  *
  *      The Xen grant reference granting permission for the backend to map
  *      the sole page in a single page sized ring buffer.
  *
+ * ring-ref%u
+ *      Values:         <uint32_t>
+ *      Notes:          6
+ *
+ *      For a frontend providing a multi-page ring, a "ring-pages" sized
+ *      list of nodes, each containing a Xen grant reference granting
+ *      permission for the backend to map the page of the ring located
+ *      at page index "%u".  Page indexes are zero based.
+ *
  * protocol
  *      Values:         string (XEN_IO_PROTO_ABI_*)
  *      Default Value:  XEN_IO_PROTO_ABI_NATIVE
@@ -187,6 +216,25 @@
  *      The machine ABI rules governing the format of all ring request and
  *      response structures.
  *
+ * ring-page-order
+ *      Values:         <uint32_t>
+ *      Default Value:  0
+ *      Maximum Value:  MAX(ffs(max-ring-pages) - 1, max-ring-page-order)
+ *      Notes:          1, 3
+ *
+ *      The size of the frontend allocated request ring buffer in units
+ *      of lb(machine pages). (e.g. 0 == 1 page, 1 = 2 pages, 2 == 4 pages,
+ *      etc.).
+ *
+ * ring-pages
+ *      Values:         <uint32_t>
+ *      Default Value:  1
+ *      Maximum Value:  MAX(max-ring-pages,(0x1 << max-ring-page-order))
+ *      Notes:          2, 3
+ *
+ *      The size of the frontend allocated request ring buffer in units of
+ *      machine pages.  The value must be a power of 2.
+ *
  *------------------------- Virtual Device Properties -------------------------
  *
  * device-type
@@ -201,12 +249,25 @@
  *
  * Notes
  * -----
- * (1) Devices that support discard functionality may internally allocate
+ * (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
+ *     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.
+ *     For full interoperability, block front and backends should support
+ *     both methods of negotiating this capability.
+ * (4) Devices that support discard functionality may internally allocate
  *     space (discardable extents) in units that are larger than the
  *     exported logical block size.
- * (2) The discard-alignment parameter allows a physical device to be
+ * (5) The discard-alignment parameter allows a physical device to be
  *     partitioned into virtual devices that do not necessarily begin or
  *     end on a discardable extent boundary.
+ * (6) When there is only a single page allocated to the request ring,
+ *     'ring-ref' is used to communicate the grant reference for this
+ *     page to the backend.  When using a multi-page ring, the 'ring-ref'
+ *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
  */
 
 /*
@@ -224,20 +285,26 @@
  *  o Query virtual device               o Query backend device identification
  *    properties.                          data.
  *  o Setup OS device instance.          o Open and validate backend device.
- *                                       o Publish backend features.
+ *                                       o Publish backend features and
+ *                                         transport parameters.
  *                                                      |
  *                                                      |
  *                                                      V
  *                                      XenbusStateInitWait
  *
- * o Query backend features.
+ * o Query backend features and
+ *   transport parameters.
  * o Allocate and initialize the
  *   request ring.
+ * o Publish transport parameters
+ *   that will be in effect during
+ *   this connection.
  *              |
  *              |
  *              V
  * XenbusStateInitialised
  *
+ *                                       o Query frontend transport parameters.
  *                                       o Connect to the request ring and
  *                                         event channel.
  *                                       o Publish backend device properties.
@@ -254,20 +321,26 @@
  *              V
  * XenbusStateConnected
  *
- * Note: Drivers that do not support any optional features can skip certain
- *       states in the state machine:
+ * Note: Drivers that do not support any optional features, or the negotiation
+ *       of transport parameters, can skip certain states in the state machine:
  *
  *       o A frontend may transition to XenbusStateInitialised without
- *         waiting for the backend to enter XenbusStateInitWait.
+ *         waiting for the backend to enter XenbusStateInitWait.  In this
+ *         case, default transport parameters are in effect and any
+ *         transport parameters published by the frontend must contain
+ *         their default values.
  *
  *       o A backend may transition to XenbusStateInitialised, bypassing
  *         XenbusStateInitWait, without waiting for the frontend to first
- *         enter the XenbusStateInitialised state.
+ *         enter the XenbusStateInitialised state.  In this case, default
+ *         transport parameters are in effect and any transport parameters
+ *         published by the backend must contain their default values.
  *
- *       Drivers that support optional features must tolerate these additional
- *       state transition paths.  In general this means performing the work of
- *       any skipped state transition, if it has not already been performed,
- *       in addition to the work associated with entry into the current state.
+ *       Drivers that support optional features and/or transport parameter
+ *       negotiation must tolerate these additional state transition paths.
+ *       In general this means performing the work of any skipped state
+ *       transition, if it has not already been performed, in addition to the
+ *       work associated with entry into the current state.
  */
 
 /*

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


 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.