diff options
| -rw-r--r-- | content.tex | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/content.tex b/content.tex index 2d032a7..7e46b7d 100644 --- a/content.tex +++ b/content.tex @@ -626,6 +626,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}. @@ -3248,6 +3259,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 @@ -3948,6 +3968,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. @@ -4271,6 +4299,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} @@ -4444,6 +4480,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 @@ -4661,6 +4706,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 |