virtio — archive

[PATCH] used ring: define the meaning and requirements of the len field.

From: Rusty Russell <[email protected]>
To: [email protected]
Date: Tue, 07 Apr 2015 01:25:00 -0000

"Michael S. Tsirkin" <[email protected]> writes: > On Fri, Mar 20, 2015 at 11:48:55AM +1030, Rusty Russell wrote: >> +\devicenormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} >> + >> +The device MUST set \field{len} prior to updating the used \field{idx}. >> + >> +The device MUST write at least \field{len} bytes to descriptor, >> +beginning at the first device-writable buffer, >> +prior to updating the used \field{idx}. >> + >> +The device MAY write more than \field{len} bytes to descriptor. >> + >> +\begin{note} >> +There are potential error cases where a device might not know what >> +parts of the buffers have been written. This is why \field{len} is >> +permitted to be an underestimate: that's preferable to the driver believing >> +that uninitialized memory has been overwritten when it has not. >> +\end{note} >> + >> +\drivernormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} >> + >> +The driver MUST NOT make assumptions about data in device-writable buffers >> +beyond the first \field{len} bytes, and SHOULD ignore this data. >> + >> \subsection{Virtqueue Notification Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} >> >> The device can suppress notifications in a manner analogous to the way > > We know legacy devices don't follow this, so we also need some text in > the legacy sections to document the differences. Indeed, but it was specific to block devices. It may be worth noting that older block devices would set erroneously set a length corresponding to the entire buffer length, and thus legacy drivers SHOULD rely on the status byte and ignore used.len? Cheers, Rusty.