Re: [PATCH v2 2/3] docs: Clarify structured reads vs. block size constraints

[Richard W.M. Jones]

On Fri, Mar 25, 2022 at 07:41:01AM -0500, Eric Blake wrote:
> The text for structured reads mentioned a mandatory split of certain
> large reads, without also mentioning that large reads are generally
> not possible when block constraints are in play.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  doc/proto.md | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/doc/proto.md b/doc/proto.md
> index bfebb5a..8a817d2 100644
> --- a/doc/proto.md
> +++ b/doc/proto.md
> @@ -1911,13 +1911,14 @@ The following request types exist:
>      chunks that describe data outside the offset and length of the
>      request, but MAY send the content chunks in any order (the client
>      MUST reassemble content chunks into the correct order), and MAY
> -    send additional content chunks even after reporting an error chunk.
> -    Note that a request for more than 2^32 - 8 bytes MUST be split
> -    into at least two chunks, so as not to overflow the length field
> -    of a reply while still allowing space for the offset of each
> -    chunk.  When no error is detected, the server MUST send enough
> -    data chunks to cover the entire region described by the offset and
> -    length of the client's request.
> +    send additional content chunks even after reporting an error
> +    chunk.  Note that a request for more than 2^32 - 8 bytes (if
> +    permitted by block size constraints) MUST be split into at least

The actual change is just the "(if ... constraints)" subclause.
The rest is formatting.

> +    two chunks, so as not to overflow the length field of a reply
> +    while still allowing space for the offset of each chunk.  When no
> +    error is detected, the server MUST send enough data chunks to
> +    cover the entire region described by the offset and length of the
> +    client's request.
> 
>      To minimize traffic, the server MAY use a content or error chunk
>      as the final chunk by setting the `NBD_REPLY_FLAG_DONE` flag, but

ACK

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://libguestfs.org