Date: Wed, 29 Feb 2012 17:47:01 +0000 (UTC) From: "Justin T. Gibbs" <gibbs@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r232308 - head/sys/xen/interface/io Message-ID: <201202291747.q1THl1ls037743@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gibbs Date: Wed Feb 29 17:47:01 2012 New Revision: 232308 URL: http://svn.freebsd.org/changeset/base/232308 Log: blkif interface comment cleanups. No functional changes sys/xen/interface/io/blkif.h: o Insert space in "Red Hat". 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". o Clarify the text for "max-requests" in the backend section. Modified: head/sys/xen/interface/io/blkif.h Modified: head/sys/xen/interface/io/blkif.h ============================================================================== --- head/sys/xen/interface/io/blkif.h Wed Feb 29 16:16:36 2012 (r232307) +++ head/sys/xen/interface/io/blkif.h Wed Feb 29 17:47:01 2012 (r232308) @@ -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. @@ -67,6 +67,9 @@ * XenStore nodes in sections marked "PRIVATE" are solely for use by the * driver side whose XenBus tree contains them. * + * XenStore nodes marked "DEPRECATED" in their notes section should only be + * used to provide interoperability with legacy implementations. + * * See the XenBus state transition diagram below for details on when XenBus * nodes must be published and when they can be queried. * @@ -85,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" @@ -137,7 +140,7 @@ * max-ring-pages * Values: <uint32_t> * Default Value: 1 - * Notes: 2, 3 + * Notes: DEPRECATED, 2, 3 * * The maximum supported size of the request ring buffer in units of * machine pages. The value must be a power of 2. @@ -146,8 +149,8 @@ * Default Value: BLKIF_MAX_RING_REQUESTS(PAGE_SIZE) * Maximum Value: BLKIF_MAX_RING_REQUESTS(PAGE_SIZE * max-ring-pages) * - * The maximum number of concurrent, logical requests that will be - * issued by the backend. + * The maximum number of concurrent, logical requests supported by + * the backend. * * Note: A logical request may span multiple ring entries. * @@ -170,7 +173,7 @@ * *------------------------- Backend Device Properties ------------------------- * - * discard-aligment + * discard-alignment * Values: <uint32_t> * Default Value: 0 * Notes: 4, 5 @@ -203,7 +206,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> @@ -234,8 +238,8 @@ * Values: <uint32_t> * Notes: 6 * - * For a frontend providing a multi-page ring, a "num-ring-pages" sized - * list of nodes, each containing a Xen grant reference granting + * For a frontend providing a multi-page ring, a "number of 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. * @@ -260,7 +264,7 @@ * Values: <uint32_t> * Default Value: 1 * Maximum Value: MAX(max-ring-pages,(0x1 << max-ring-page-order)) - * Notes: 2, 3 + * Notes: DEPRECATED, 2, 3 * * The size of the frontend allocated request ring buffer in units of * machine pages. The value must be a power of 2. @@ -311,11 +315,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. @@ -437,7 +441,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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201202291747.q1THl1ls037743>