[PATCH] net: clarify device rules for mergeable buffers

["Michael S. Tsirkin" <mst@redhat.com>]

The idea behind mergeable buffers was to simply use them in a way
similar to a chain of descriptors.  Unfortunately the current text does
not say so - apparently nothing says device can't spread a packet over
as many buffers as it likes - but this didn't prevent drivers from
relying on buffers being used as a chain of descriptors, completely -
and blindly accessing it without checking the length at least for the
packet header.

Let's just make the spec match this reality - if devices ever want more
flexibility, we can add a feature bit.

Further, correct all misuses of a "descriptor" to "buffer" as that
is the entity that is being merged.

VIRTIO-160

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/content.tex b/content.tex
index a67610f..edd4d6a 100644
--- a/content.tex
+++ b/content.tex
@@ -3561,10 +3561,13 @@ Processing incoming packets involves:
   this packet is spread over (including this one): this will
   always be 1 if VIRTIO_NET_F_MRG_RXBUF was not negotiated.
   This allows receipt of large packets without having to allocate large
-  buffers. In this case, there will be at least \field{num_buffers} in
-  the used ring, and the device chains them together to form a
-  single packet. The other buffers will not begin with a struct
-  virtio_net_hdr.
+  buffers: a packet that does not fit in a single buffer can flow
+  over to the next buffer, and so on. In this case, there will be
+  at least \field{num_buffers} in the used ring, and the device
+  chains them together to form a single packet in a way similar to
+  how it would store it in a single buffer spread over multiple
+  descriptors.
+  The other buffers will not begin with a struct virtio_net_hdr.
 
 \item If
   \field{num_buffers} is one, then the entire packet will be
@@ -3605,10 +3608,15 @@ If VIRTIO_NET_F_MRG_RXBUF has not been negotiated, the device MUST set
 \field{num_buffers} to 1.
 
 If VIRTIO_NET_F_MRG_RXBUF has been negotiated, the device MUST set
-\field{num_buffers} to indicate the number of descriptors
+\field{num_buffers} to indicate the number of buffers
 the packet (including the header) is spread over.
 
-The device MUST use all descriptors used by a single receive
+If a receive packet is spread over multiple buffers, the device
+MUST use all buffers but the last (i.e. the first $num_buffers -
+1$ buffers) completely up to the full length of each buffer
+supplied by the driver.
+
+The device MUST use all buffers used by a single receive
 packet together, by atomically incrementing \field{idx} in the
 used ring by the \field{num_buffers} value.
 
-- 
MST