From 4efd3039157024ea53c927cf5c764f1fa9c5266b Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Tue, 28 Mar 2017 02:09:11 +0300 Subject: net: clarify device rules for mergeable buffers 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 Message-Id: <1490655576-12173-1-git-send-email-mst@redhat.com> Reviewed-by: Stefan Hajnoczi Signed-off-by: Cornelia Huck --- content.tex | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/content.tex b/content.tex index 51a00b2..ef28bdb 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. -- cgit v1.2.3