@@ -237,12 +237,16 @@
* sector-size
* Values: <uint32_t>
*
- * The logical block size, in bytes, of the underlying storage. This
- * must be a power of two with a minimum value of 512.
+ * The logical block size, in bytes, of the underlying storage. This must
+ * be a power of two with a minimum value of 512. The sector size should
+ * only be used for request segment length and alignment.
*
- * NOTE: Because of implementation bugs in some frontends this must be
- * set to 512, unless the frontend advertizes a non-zero value
- * in its "feature-large-sector-size" xenbus node. (See below).
+ * When exposing a device that uses a logical sector size of 4096, the
+ * only difference xenstore wise will be that 'sector-size' (and possibly
+ * 'physical-sector-size' if supported by the backend) will be 4096, but
+ * the 'sectors' node will still be calculated using 512 byte units. The
+ * sector base units in the ring requests fields will all be 512 byte
+ * based despite the logical sector size exposed in 'sector-size'.
*
* physical-sector-size
* Values: <uint32_t>
@@ -254,9 +258,9 @@
* sectors
* Values: <uint64_t>
*
- * The size of the backend device, expressed in units of "sector-size".
- * The product of "sector-size" and "sectors" must also be an integer
- * multiple of "physical-sector-size", if that node is present.
+ * The size of the backend device, expressed in units of 512b. The
+ * product of "sectors" * 512 must also be an integer multiple of
+ * "physical-sector-size", if that node is present.
*
*****************************************************************************
* Frontend XenBus Nodes
@@ -338,6 +342,7 @@
* feature-large-sector-size
* Values: 0/1 (boolean)
* Default Value: 0
+ * Notes: DEPRECATED, 12
*
* A value of "1" indicates that the frontend will correctly supply and
* interpret all sector-based quantities in terms of the "sector-size"
@@ -411,6 +416,11 @@
*(10) The discard-secure property may be present and will be set to 1 if the
* backing device supports secure discard.
*(11) Only used by Linux and NetBSD.
+ *(12) Possibly only ever implemented by the QEMU Qdisk backend and the Windows
+ * PV block frontend. Other backends and frontends supported 'sector-size'
+ * values greater than 512 before such feature was added. Frontends should
+ * not expose this node, neither should backends make any decisions based
+ * on it being exposed by the frontend.
*/
/*
@@ -619,11 +629,14 @@
#define BLKIF_MAX_INDIRECT_PAGES_PER_REQUEST 8
/*
- * NB. 'first_sect' and 'last_sect' in blkif_request_segment, as well as
- * 'sector_number' in blkif_request, blkif_request_discard and
- * blkif_request_indirect are sector-based quantities. See the description
- * of the "feature-large-sector-size" frontend xenbus node above for
- * more information.
+ * NB. 'first_sect' and 'last_sect' in blkif_request_segment are all in units
+ * of 512 bytes, despite the 'sector-size' xenstore node possibly having a
+ * value greater than 512.
+ *
+ * The value in 'first_sect' and 'last_sect' fields must be setup so that the
+ * resulting segment offset and size is aligned to the logical sector size
+ * reported by the 'sector-size' xenstore node, see 'Backend Device Properties'
+ * section.
*/
struct blkif_request_segment {
grant_ref_t gref; /* reference to I/O buffer frame */
@@ -634,6 +647,10 @@ struct blkif_request_segment {
/*
* Starting ring element for any I/O request.
+ *
+ * The 'sector_number' field is in units of 512b, despite the value of the
+ * 'sector-size' xenstore node. Note however that the offset in
+ * 'sector_number' must be aligned to 'sector-size'.
*/
struct blkif_request {
uint8_t operation; /* BLKIF_OP_??? */
@@ -648,6 +665,10 @@ typedef struct blkif_request blkif_request_t;
/*
* Cast to this structure when blkif_request.operation == BLKIF_OP_DISCARD
* sizeof(struct blkif_request_discard) <= sizeof(struct blkif_request)
+ *
+ * The 'sector_number' field is in units of 512b, despite the value of the
+ * 'sector-size' xenstore node. Note however that the offset in
+ * 'sector_number' must be aligned to 'sector-size'.
*/
struct blkif_request_discard {
uint8_t operation; /* BLKIF_OP_DISCARD */
@@ -660,6 +681,11 @@ struct blkif_request_discard {
};
typedef struct blkif_request_discard blkif_request_discard_t;
+/*
+ * The 'sector_number' field is in units of 512b, despite the value of the
+ * 'sector-size' xenstore node. Note however that the offset in
+ * 'sector_number' must be aligned to 'sector-size'.
+ */
struct blkif_request_indirect {
uint8_t operation; /* BLKIF_OP_INDIRECT */
uint8_t indirect_op; /* BLKIF_OP_{READ/WRITE} */
Signed-off-by: Anthony PERARD <anthony.perard@vates.tech> --- include/hw/xen/interface/io/blkif.h | 52 +++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 13 deletions(-)