From patchwork Tue Mar 29 03:56:35 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Blake X-Patchwork-Id: 8682101 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 10580C0553 for ; Tue, 29 Mar 2016 03:59:00 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 223C7201E4 for ; Tue, 29 Mar 2016 03:58:59 +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 5305B201DD for ; Tue, 29 Mar 2016 03:58:58 +0000 (UTC) Received: from localhost ([::1]:44315 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akknx-0008NF-Cr for patchwork-qemu-devel@patchwork.kernel.org; Mon, 28 Mar 2016 23:58:57 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52892) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akkno-0008N2-Qo for qemu-devel@nongnu.org; Mon, 28 Mar 2016 23:58:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1akknj-0007lP-P4 for qemu-devel@nongnu.org; Mon, 28 Mar 2016 23:58:48 -0400 Received: from resqmta-po-03v.sys.comcast.net ([96.114.154.162]:60868) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akknj-0007l8-JF for qemu-devel@nongnu.org; Mon, 28 Mar 2016 23:58:43 -0400 Received: from resomta-po-11v.sys.comcast.net ([96.114.154.235]) by comcast with SMTP id kkllayUq9BbvAkkllaOPgd; Tue, 29 Mar 2016 03:56:41 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; s=q20140121; t=1459223801; bh=gJNetqTvaZvOZ9hUApSH8jonJvu0pgtm585aKW8gPDc=; h=Received:Received:From:To:Subject:Date:Message-Id; b=W/6CLcg5Rlda1OvGXZCzfyl2lYWTsAkM+agB62Er07vIlebZ+8aIZw1uHCZGxfSye wSohnMGp02qGb07sIAkU8a+31wea2e3hEMI1+i4UIree3qhPfEWxHYz4L65VR+hS3o SOMvu5NWItijUCkbf/31U6OvfNqaXqcXPuSIbQ/16d8KmecUOwhu0djAncnyvc1jwL d7qpAw8F9p7Hg9n06277i3PNHHTxwakvI0r4GgjdvrtAPqVpJt19etXHs1615pSAYK PGnBy6ycgKAk8yJCqC4Vjqf2lQeEnC4qlg8x7my+67rReIp4428kjKc7oPVYDV+d79 Yf+6zUiIf+MEA== Received: from red.redhat.com ([24.10.254.122]) by resomta-po-11v.sys.comcast.net with comcast id bfwd1s0032fD5rL01fwgKX; Tue, 29 Mar 2016 03:56:40 +0000 From: Eric Blake To: nbd-general@lists.sourceforge.net Date: Mon, 28 Mar 2016 21:56:35 -0600 Message-Id: <1459223796-28474-1-git-send-email-eblake@redhat.com> X-Mailer: git-send-email 2.5.5 In-Reply-To: <1459173555-4890-1-git-send-email-eblake@redhat.com> References: <1459173555-4890-1-git-send-email-eblake@redhat.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 96.114.154.162 Cc: w@uter.be, qemu-devel@nongnu.org Subject: [Qemu-devel] [PATCH 2/1] doc: More details on flag negotiation 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 Add documentation that makes it clear that the server may add flags that the client does not recognize, but that the client may ignore those flags because the server will not change behavior without agreement; meanwhile, the client must not set flags the server does not recognize (since there is no second round of server reply, the only sane course of action is for the server to disconnect). Also, give a forward reference to the effect of negotiating NO_ZEROES on the server's reply to NBD_OPT_EXPORT_NAME, and call out the fact that none of the server's global flags should be used during oldstyle negotiation since a client has no chance to respond with the corresponding client flag. Signed-off-by: Eric Blake --- doc/proto.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/proto.md b/doc/proto.md index d0102e0..44579fc 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -103,8 +103,10 @@ C: 32 bits, flags This completes the initial phase of negotiation; the client and server now both know they understand the first version of the newstyle -handshake, with no options. What follows is a repeating group of -options. In non-fixed newstyle only one option can be set +handshake, with no options. The client SHOULD ignore any global flags +it does not recognize, while the server MUST close the connection if +it does not recognize the client's flags. What follows is a repeating +group of options. In non-fixed newstyle only one option can be set (`NBD_OPT_EXPORT_NAME`), and it is not optional. At this point, we move on to option haggling, during which point the @@ -126,7 +128,8 @@ about the used export: S: 64 bits, size of the export in bytes (unsigned) S: 16 bits, export flags -S: 124 bytes, zeroes (reserved) +S: 124 bytes, zeroes (reserved) (unless `NBD_FLAG_C_NO_ZEROES` was + negotiated by the client) If the server is unwilling to allow the export, it should close the connection. @@ -229,6 +232,10 @@ the first magic number. `NBD_FLAG_C_NO_ZEROES` in the client flags field, the server MUST NOT send the 124 bytes of zero at the end of the negotiation. +The server MUST NOT set any other flags, and SHOULD NOT change behaviour +unless the client responds with a corresponding flag. The server MUST +NOT set any of these flags during oldstyle negotiation. + ##### Export flags This field of 16 bits is sent by the server after option haggling, or @@ -259,6 +266,10 @@ receiving the global flags from the server. set `NBD_FLAG_NO_ZEROES`. If set, the server MUST NOT send the 124 bytes of zeroes at the end of the negotiation. +Clients SHOULD NOT set any other flags; the server MUST drop the +connection if the client sets an unknown flag, or a flag that does +not match something advertised by the server. + #### Option types These values are used in the "option" field during the option haggling