Re: [Xen-devel] [PATCH 2 of 4 v3] blkif.h: Provide more complete documentation of the blkif interface

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-02-20 at 18:07 +0000, Justin T. Gibbs wrote:
> o Document the XenBus nodes used in this protocol.
>   o Add a state diagram illustrating the roles and responsibilities
>     of both the front and backend during startup.
>   o Correct missed BLKIF_OP_TRIM => BLKIF_OP_DISCARD conversion in a comment.
> 
> No functional changes.
> 
> Signed-off-by: Justin T. Gibbs <justing@xxxxxxxxxxxxxxxx>

Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

I've made some very minor comments below but I think getting the basic
documentation of this stuff in as a baseline to improve and correct over
time is more important than any of them.

Thanks again for doing this -- it is really valuable!

> diff -r 28137a4e39a3 -r e79902456819 xen/include/public/io/blkif.h
> --- a/xen/include/public/io/blkif.h     Mon Feb 20 10:48:09 2012 -0700
> +++ b/xen/include/public/io/blkif.h     Mon Feb 20 10:48:09 2012 -0700
> @@ -22,6 +22,7 @@
>   * DEALINGS IN THE SOFTWARE.
>   *
>   * Copyright (c) 2003-2004, Keir Fraser
> + * Copyright (c) 2012, Spectra Logic Corporation
>   */
> 
>  #ifndef __XEN_PUBLIC_IO_BLKIF_H__
> @@ -48,32 +49,253 @@
>  #define blkif_sector_t uint64_t
> 
>  /*
> + * Feature and Parameter Negotiation
> + * =================================
> + * The two halves of a Xen block driver utilize nodes within the XenStore to
> + * communicate capabilities and to negotiate operating parameters.  This
> + * section enumerates these nodes which reside in the respective front and
> + * backend portions of the XenStore, following the XenBus convention.
> + *
> + * 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.

                    formatted

> + *
> + * Any specified default value is in effect if the corresponding XenBus node
> + * is not present in the XenStore.
> + *
> + * XenStore nodes in sections marked "PRIVATE" are solely for use by the
> + * driver side whose XenBus tree contains them.
> + *
> + * See the XenBus state transition diagram below for details on when XenBus
> + * nodes must be published and when they can be queried.
> + *
> + 
> *****************************************************************************
> + *                            Backend XenBus Nodes
> + 
> *****************************************************************************
> + *
> + *------------------ Backend Device Identification (PRIVATE) 
> ------------------
> + *
> + * mode
> + *      Values:         "r" (read only), "w" (writable)
> + *
> + *      The read or write access permissions to the backing store to be
> + *      granted to the frontend.
> + *
> + * 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.)

The syntax and semantics of params is defined by the particular backend,
rather than being "free formatted" as such. I think it would be worth
saying that explicitly.

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel