spec: Add NBD_OPT_EXTENDED_HEADERSexthdr-v1
commitdcce1bfe5fbee44399ae058e435ee6cc80b00e7e
authorEric Blake <eblake@redhat.com>
Wed, 10 Nov 2021 20:43:00 +0000 (10 14:43 -0600)
committerEric Blake <eblake@redhat.com>
Fri, 3 Dec 2021 23:03:27 +0000 (3 17:03 -0600)
treed9cb4fc8fd55d27fea2e4a71ad118bc10dac3fb5
parent8062af19ad78c6751624dfa838e1cf9e361d9542
spec: Add NBD_OPT_EXTENDED_HEADERS

Add a new negotiation feature where the client and server agree to use
larger packet headers on every packet sent during transmission phase.
This has two purposes: first, it makes it possible to perform
operations like trim, write zeroes, and block status on more than 2^32
bytes in a single command; this in turn requires that some structured
replies from the server also be extended to match.  The wording chosen
here is careful to permit a server to use either flavor in its reply
(that is, a request less than 32-bits can trigger an extended reply,
and conversely a request larger than 32-bits can trigger a compact
reply).

Second, when structured replies are active, clients have to deal with
the difference between 16- and 20-byte headers of simple
vs. structured replies, which impacts performance if the client must
perform multiple syscalls to first read the magic before knowing how
many additional bytes to read.  In extended header mode, all headers
are the same width, so the client can read a full header before
deciding whether the header describes a simple or structured reply.
Similarly, by having extended mode use a power-of-2 sizing, it becomes
easier to manipulate headers within a single cache line, even if it
requires padding bytes sent over the wire.  However, note that this
change only affects the headers; as data payloads can still be
unaligned (for example, a client performing 1-byte reads or writes),
we would need to negotiate yet another extension if we wanted to
ensure that all NBD transmission packets started on an 8-byte boundary
after option haggling has completed.

This spec addition was done in parallel with a proof of concept
implementation in qemu (server and client) and libnbd (client), and I
also have plans to implement it in nbdkit (server).

Signed-off-by: Eric Blake <eblake@redhat.com>
doc/proto.md