From patchwork Fri Apr 1 19:39:37 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Blake X-Patchwork-Id: 8727311 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 7C5C5C0553 for ; Fri, 1 Apr 2016 19:42:06 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 19D14203AB for ; Fri, 1 Apr 2016 19:42:05 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id C23FB203A1 for ; Fri, 1 Apr 2016 19:42:03 +0000 (UTC) Received: from localhost ([::1]:46101 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1am4xG-0001cu-3R for patchwork-qemu-devel@patchwork.kernel.org; Fri, 01 Apr 2016 15:42:02 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55509) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1am4x7-0001cl-Di for qemu-devel@nongnu.org; Fri, 01 Apr 2016 15:41:55 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1am4x4-0004Ox-5n for qemu-devel@nongnu.org; Fri, 01 Apr 2016 15:41:53 -0400 Received: from resqmta-po-07v.sys.comcast.net ([96.114.154.166]:34849) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1am4x3-0004Ok-TF for qemu-devel@nongnu.org; Fri, 01 Apr 2016 15:41:50 -0400 Received: from resomta-po-18v.sys.comcast.net ([96.114.154.242]) by comcast with SMTP id m4uxaxv3Npyiom4v6atD00; Fri, 01 Apr 2016 19:39:48 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; s=q20140121; t=1459539588; bh=juXprga0XEeHyDDUQHIiIMQ+Kj/wmXIMOlu0F/ezwgs=; h=Received:Received:From:To:Subject:Date:Message-Id; b=JeHr9JT6H0//do4Qw2EfSYiDi2qy5DSIqeNzVYUbCIGWZVCG558NhHdSQ4LlIg72u XO89YC/rJTqTBqU9lgi8HiLwI09ayDU+AqLw31wdkmQvtK3Z6/3ergMsgyY2qlIxwT F5IAkxyywzKBNkTTFJ0LwgsTWAE9HRMxFgqJbRq/DLi4GoaouWE08ptIQloOcckod6 aBZ3G+D6BuCbf7XrRulocara9Kcx4Btrsi0WlcyZaFV/co0RIWMRtNpixPQyim3HW9 i1PvZpNjlaGC+n61N46zze9Uzu42uUm7FJxSNnF5PI9Ur+drtXtXAfIogMmrxqT2uX 3eoY8MDrwTviQ== Received: from red.redhat.com ([24.10.254.122]) by resomta-po-18v.sys.comcast.net with comcast id d7ff1s00R2fD5rL017fnbF; Fri, 01 Apr 2016 19:39:48 +0000 From: Eric Blake To: nbd-general@lists.sourceforge.net Date: Fri, 1 Apr 2016 13:39:37 -0600 Message-Id: <1459539577-5647-1-git-send-email-eblake@redhat.com> X-Mailer: git-send-email 2.5.5 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 96.114.154.166 Cc: w@uter.be, qemu-devel@nongnu.org, alex@alex.org.uk Subject: [Qemu-devel] [PATCH] doc: Cleanups to structured reads X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI, T_DKIM_INVALID, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP A couple of typos, odd formatting, and missing words made it into the structured read spec, and several potential ambiguous situations were worth rewording for clarity. Signed-off-by: Eric Blake Signed-off-by: Alex Bligh Reviewed-by: Alex Bligh --- doc/proto.md | 112 +++++++++++++++++++++++++++++++---------------------------- 1 file changed, 59 insertions(+), 53 deletions(-) diff --git a/doc/proto.md b/doc/proto.md index 8c83382..758a661 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -243,7 +243,7 @@ S: (*length* bytes of data if the request is of type `NBD_CMD_READ`) #### Structured reply chunk message This reply type MUST NOT be used except as documented by the -experimental `STRUCTURED_READ` extension; see below. +experimental `STRUCTURED_REPLY` extension; see below. ## Values @@ -410,8 +410,8 @@ during option haggling in the fixed newstyle negotiation. versions of nbd-server may send along some details about the export. Therefore, unless explicitly documented otherwise by a particular client request, this field is defined to be UTF-8 - encoded data suitable for direct display to a human being; a - client SHOULD NOT assume that the data is NUL-terminated. + encoded data suitable for direct display to a human being; with + no embedded or terminating NUL characters. The experimental `SELECT` extension (see below) is a client request where the extra data has a definition other than a @@ -420,8 +420,7 @@ during option haggling in the fixed newstyle negotiation. There are a number of error reply types, all of which are denoted by having bit 31 set. All error replies MAY have some data set, in which case that data is an error message in UTF-8 encoding suitable for -display to the user, although the client MUST NOT assume that a -terminating NUL is present. +display to the user, with no embedded or terminating NUL characters. * `NBD_REP_ERR_UNSUP` (2^31 + 1) @@ -501,8 +500,8 @@ The following request types exist: extension was negotiated. If structured replies were not negotiated, the server MUST reply - with a simple reply header, followed immediately by len bytes of - data, read from offset bytes into the file, unless an error + with a simple reply header, followed immediately by *length* bytes + of data, read from *offset* bytes into the file, unless an error condition has occurred. If an error occurs, the server SHOULD set the appropriate error @@ -798,18 +797,23 @@ error, and alters the reply to the `NBD_CMD_READ` request. structured replies are negotiated, the server MUST use a structured reply for any response with a payload, and MUST NOT use a simple reply for `NBD_CMD_READ` (even for the case of an early - `EINVAL` due to bad flags). + `EINVAL` due to bad flags), but MAY use either a simple reply or a + structured reply to all other requests. The server SHOULD prefer + sending errors via a structured reply, as the error can then be + accompanied by a UTF-8 text payload to present to a human user. A structured reply MAY occupy multiple structured chunk messages (all with the same value for "handle"), and the `NBD_REPLY_FLAG_DONE` reply flag is used to identify the final - chunk. Relative ordering of the chunks MAY be important; - individual commands will document constraints on whether multiple - chunks may be rearranged; however, it is always safe to interleave - chunks of the reply to one request with messages related to other - requests. A server SHOULD try to minimize the number of chunks - sent in a reply, but MUST NOT send the final chunk if there is - still a possibility of detecting an error. A structured reply is + chunk. Unless further documented by individual requests below, + the chunks MAY be sent in any order, except that the chunk with + the flag `NBD_REPLY_FLAG_DONE` MUST be sent last. Even when a + command documents further constraints between chunks of one reply, + it is always safe to interleave chunks of that reply with messages + related to other requests. A server SHOULD try to minimize the + number of chunks sent in a reply, but MUST NOT mark a chunk as + final if there is still a possibility of detecting an error before + transmission of that chunk completes. A structured reply is considered successful only if it did not contain any error chunks, although the client MAY be able to determine partial success based on the chunks received. @@ -851,7 +855,7 @@ error, and alters the reply to the `NBD_CMD_READ` request. Some chunk types can additionally be categorized by role, such as *error chunks* or *content chunks*. Each type determines how to interpret the "length" bytes of payload. If the client receives - an unknown or unexpected type, it SHOULD close the connection. + an unknown or unexpected type, it MUST close the connection. - `NBD_REPLY_TYPE_NONE` (0) @@ -874,7 +878,8 @@ error, and alters the reply to the `NBD_CMD_READ` request. 32 bits: error (MUST be nonzero) *length - 4* bytes: (optional UTF-8 encoded data suitable for - direct display to a human being, not NUL terminated) + direct display to a human being, with no embedded or + terminating NUL characters) - `NBD_REPLY_TYPE_ERROR_OFFSET` (2) @@ -895,7 +900,8 @@ error, and alters the reply to the `NBD_CMD_READ` request. 32 bits: error (MUST be nonzero) 64 bits: offset (unsigned) *length - 12* bytes: (optional UTF-8 encoded data suitable for - direct display to a human being, not NUL terminated) + direct display to a human being, with no embedded or + terminating NUL characters) - `NBD_REPLY_TYPE_OFFSET_DATA` (3) @@ -957,11 +963,8 @@ error, and alters the reply to the `NBD_CMD_READ` request. The server MUST set this transmission flag to 1 if the `NBD_CMD_READ` request supports the `NBD_CMD_FLAG_DF` flag, and MUST leave this flag clear if structured replies have not been - negotiated. Clients MUST NOT rely on the state of this flag prior - the final flags value reported by `NBD_OPT_EXPORT_NAME` or - experimental `NBD_OPT_GO`. Additionally, clients MUST NOT set the - `NBD_CMD_FLAG_DF` request flag unless this transmission flag is - set. + negotiated. Clients MUST NOT set the `NBD_CMD_FLAG_DF` request + flag unless this transmission flag is set. * `NBD_CMD_FLAG_DF` @@ -1000,47 +1003,50 @@ error, and alters the reply to the `NBD_CMD_READ` request. overhead, the server SHOULD use chunks with lengths and offsets as an integer multiple of 512 bytes, where possible (the first and last chunk of an unaligned read being the most obvious places for - an exception). The server MUST NOT content chunks that overlap - with any earlier content or error chunk, and MUST NOT send chunks - that describe data outside the offset and length of the request, - but MAY send the chunks in any order (the client MUST reassemble - content chunks into the correct order), and MAY send additional - data 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. + an exception). The server MUST NOT send content chunks that + overlap with any earlier content or error chunk, and MUST NOT send + 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. 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 MUST NOT do so for a content chunk if it would still be possible to detect an error while transmitting the chunk. The - `NBD_REPLY_TYPE_DONE` chunk is always acceptable as the final + `NBD_REPLY_TYPE_NONE` chunk is always acceptable as the final chunk. If an error is detected, the server MUST still complete the - transmission of any current chunk (it SHOULD use padding bytes of - zero for any remaining data portion of a chunk with type - `NBD_REPLY_TYPE_OFFSET_DATA`), but MAY omit further content + transmission of any current chunk (it MUST use padding bytes which + SHOULD be zero, for any remaining data portion of a chunk with + type `NBD_REPLY_TYPE_OFFSET_DATA`), but MAY omit further content chunks. The server MUST include an error chunk as one of the subsequent chunks, but MAY defer the error reporting behind other queued chunks. An error chunk of type `NBD_REPLY_TYPE_ERROR` implies that the client MAY NOT make any assumptions about - validity of data chunks, and if used, SHOULD be the only error - chunk in the reply. On the other hand, an error chunk of type + validity of data chunks (whether sent before or after the error + chunk), and if used, SHOULD be the only error chunk in the reply. + On the other hand, an error chunk of type `NBD_REPLY_TYPE_ERROR_OFFSET` gives fine-grained information about - which earlier data chunk(s) encountered a failure, and MAY also be - sent in lieu of a data chunk; as such, a server MAY still usefully - follow it with further non-overlapping content chunks or with - error offsets for other content chunks. Generally, a server - SHOULD NOT mix errors with offsets with a generic error. As long - as all errors are accompanied by offsets, the client MAY assume - that any data chunks with no subsequent error offset are valid, - that chunks with an overlapping error offset errors are valid up - until the reported offset, and that portions of the read that do - not have a corresponding content chunk are not valid. + which earlier data chunk(s) encountered a failure; as such, a + server MAY still usefully follow it with further non-overlapping + content chunks or with error offsets for other content chunks. + The server MAY send an error chunk with no corresponding content + chunk, but MUST ensure that the content chunk is sent first if a + content and error chunk cover the same offset. Generally, a + server SHOULD NOT mix errors with offsets with a generic error. + As long as all errors are accompanied by offsets, the client MAY + assume that any data chunks with no subsequent error offset are + valid, that chunks with an overlapping error offset errors are + valid up until the reported offset, and that portions of the read + that do not have a corresponding content chunk are not valid. A client MAY close the connection if it detects that the server has sent invalid chunks (such as overlapping data, or not enough @@ -1056,8 +1062,8 @@ error, and alters the reply to the `NBD_CMD_READ` request. A server MAY reject a client's request with the error `EOVERFLOW` if the length is too large to send without fragmentation, in which case it MUST NOT send a content chunk; however, the server MUST - NOT use this error if the client's requested length does not - exceed 65,536 bytes. + support unfragmented reads in which the client's request length + does not exceed 65,536 bytes. ## About this file