many hypervisors implemented len field incorrectly. Document existing bugs in the legacy sections. VIRTIO-141 Signed-off-by: Rusty Russell <
rusty@rustcorp.com.au> Cc: Paolo Bonzini <
pbonzini@redhat.com> Signed-off-by: Michael S. Tsirkin <
mst@redhat.com> --- 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