[PULL 15/18] block: Improve comments in BlockLimits

[Kevin Wolf <kwolf@redhat.com>]

Patches to expose the limits in QAPI have made clear that the existing
documentation of BlockLimits could be improved: The meaning of
min_mem_alignment and opt_mem_alignment could be clearer, and talking
about better alignment values isn't helpful when we only detect these
values and never choose them.

Make the changes in the BlockLimits documentation now, so that the
patches exposing the fields in QAPI can use descriptions consistent with
it.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Message-ID: <20251024123041.51254-2-kwolf@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 include/block/block_int-common.h | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/include/block/block_int-common.h b/include/block/block_int-common.h
index c55b35da8e..f2a4e863fc 100644
--- a/include/block/block_int-common.h
+++ b/include/block/block_int-common.h
@@ -817,10 +817,10 @@ typedef struct BlockLimits {
     int64_t max_pdiscard;
 
     /*
-     * Optimal alignment for discard requests in bytes. A power of 2
-     * is best but not mandatory.  Must be a multiple of
-     * bl.request_alignment, and must be less than max_pdiscard if
-     * that is set. May be 0 if bl.request_alignment is good enough
+     * Optimal alignment for discard requests in bytes. Note that this doesn't
+     * have to be a power of two. Must be a multiple of bl.request_alignment,
+     * and must be less than max_pdiscard if that is set. May be 0 if
+     * bl.request_alignment is good enough.
      */
     uint32_t pdiscard_alignment;
 
@@ -831,11 +831,10 @@ typedef struct BlockLimits {
     int64_t max_pwrite_zeroes;
 
     /*
-     * Optimal alignment for write zeroes requests in bytes. A power
-     * of 2 is best but not mandatory.  Must be a multiple of
-     * bl.request_alignment, and must be less than max_pwrite_zeroes
-     * if that is set. May be 0 if bl.request_alignment is good
-     * enough
+     * Optimal alignment for write zeroes requests in bytes. Note that this
+     * doesn't have to be a power of two. Must be a multiple of
+     * bl.request_alignment, and must be less than max_pwrite_zeroes if that is
+     * set. May be 0 if bl.request_alignment is good enough.
      */
     uint32_t pwrite_zeroes_alignment;
 
@@ -863,18 +862,23 @@ typedef struct BlockLimits {
     uint64_t max_hw_transfer;
 
     /*
-     * Maximal number of scatter/gather elements allowed by the hardware.
+     * Maximum number of scatter/gather elements allowed by the hardware.
      * Applies whenever transfers to the device bypass the kernel I/O
      * scheduler, for example with SG_IO.  If larger than max_iov
      * or if zero, blk_get_max_hw_iov will fall back to max_iov.
      */
     int max_hw_iov;
 
-
-    /* memory alignment, in bytes so that no bounce buffer is needed */
+    /*
+     * Minimal required memory alignment in bytes for zero-copy I/O to succeed.
+     * For unaligned requests, a bounce buffer will be used.
+     */
     size_t min_mem_alignment;
 
-    /* memory alignment, in bytes, for bounce buffer */
+    /*
+     * Optimal memory alignment in bytes. This is the alignment used for any
+     * buffer allocations QEMU performs internally.
+     */
     size_t opt_mem_alignment;
 
     /* maximum number of iovec elements */
-- 
2.51.0