[PATCH v4] used ring: specify legacy behaviour for len field

many hypervisors implemented len field incorrectly. Document existing bugs in the legacy sections.  VIRTIO-141  Signed-off-by: Rusty Russell <>
Cc: Paolo Bonzini <> Signed-off-by: Michael S. Tsirkin <> ---  changes from v3 	dropped an unrelated typo fix. created VIRTIO-142 for 	that.  changes from v2
dropped normative statements from generic section
added non-normative text suggesting len is unreliable
updated all devices.
content.tex
55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++  1 file changed, 55 insertions(+)  diff --git a/content.tex b/content.tex index 748c78d..d21d4bc 100644 --- a/content.tex +++ b/content.tex @@ -614,6 +614,17 @@ the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were  identical.  end{note}
+subsubsection{Legacy Interface: The Virtqueue Used +Ring}label{sec:Basic Facilities of a Virtio Device / Virtqueues +/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used +Ring} + +Historically, many drivers ignored the field{len} value, as a +result, many devices set field{len} incorrectly.  Thus, when +using the legacy interface, it is generally a good idea to ignore +the field{len} value in used ring entries if possible.  Specific +known issues are listed per device type. +  devicenormative{subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
The device MUST set field{len} prior to updating the used field{idx}. @@ -3236,6 +3247,15 @@ The legacy driver only presented field{num_buffers} in the struct virtio_net_hd  when VIRTIO_NET_F_MRG_RXBUF was not negotiated; without that feature the  structure was 2 bytes shorter.
+When using the legacy interface, the driver SHOULD ignore the +field{len} value in used ring entries for the transmit queues +and the controlq queue. +egin{note} +Historically, some devices put +the total descriptor length there, even though no data was +actually written. +end{note} +  subsubsection{Packet Transmission}label{sec:Device Types / Network Device / Device Operation / Packet Transmission}
Transmitting a single packet is simple, but varies depending on @@ -3936,6 +3956,14 @@ MUST format the fields in struct virtio_blk_req  according to the native endian of the guest rather than  (necessarily when not using the legacy interface) little-endian.
+When using the legacy interface, transitional drivers +SHOULD ignore the field{len} value in used ring entries. +egin{note} +Historically, some devices put the total descriptor length, +or the total length of device-writable buffers there, +even when only the status byte was actually written. +end{note} +  The field{reserved} field was previously called field{ioprio}.  field{ioprio}  is a hint about the relative priorities of requests to the device:  higher numbers indicate more important requests. @@ -4259,6 +4287,14 @@ MUST format the fields in struct virtio_console_control  according to the native endian of the guest rather than  (necessarily when not using the legacy interface) little-endian.
+When using the legacy interface, the driver SHOULD ignore the +field{len} value in used ring entries for the transmit queues +and the control transmitq. +egin{note} +Historically, some devices put the total descriptor length there, +even though no data was actually written. +end{note} +  subsubsection{Legacy Interface: Framing Requirements}label{sec:Device  Types / Console Device / Legacy Interface: Framing Requirements}
@@ -4432,6 +4468,15 @@ before using the pages.  The driver MUST update field{actual} after changing the number  of pages in the balloon.
+paragraph{Legacy Interface: Device Operation}label{sec:Device +Types / Memory Balloon Device / Device Operation / Legacy +Interface: Device Operation} +When using the legacy interface, the driver SHOULD ignore the field{len} value in used ring entries. +egin{note} +Historically, some devices put the total descriptor length there, +even though no data was actually written. +end{note} +  subsubsection{Memory Statistics}label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
The stats virtqueue is atypical because communication is driven @@ -4649,6 +4694,16 @@ RESET.}.  Device operation consists of operating request queues, the control  queue and the event queue.
+paragraph{Legacy Interface: Device Operation}label{sec:Device +Types / SCSI Host Device / Device Operation / Legacy +Interface: Device Operation} +When using the legacy interface, the driver SHOULD ignore the field{len} value in used ring entries. +egin{note} +Historically, devices put the total descriptor length, +or the total length of device-writable buffers there, +even when only part of the buffers were actually written. +end{note} +  subsubsection{Device Operation: Request Queues}label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
The driver queues requests to an arbitrary request queue, and

--
MST