[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [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 <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. +\begin{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. +\begin{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. +\begin{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. +\begin{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. +\begin{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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]