virtio — archive

[Cornelia Huck <mst@redhat.com>]

On Wed, 10 Jan 2018 17:05:40 +0200 "Michael S. Tsirkin" <mst@redhat.com> wrote: > Replace descriptor table/available ring/used ring > with descriptor area/driver area/device area > in all transports. > > Document what's in which area for each format. > > Signed-off-by: Michael S. Tsirkin <mst@redhat.com> > --- > > Cornelia, this is more or less what you suggested, isn't it? > > > content.tex | 61 +++++++++++++++++++++++++++++++++++++ -------------------- > packed-ring.tex | 6 +++--- > split-ring.tex | 6 +++--- > 3 files changed, 46 insertions(+), 27 deletions(-) > > diff --git a/content.tex b/content.tex > index f93c9ca..37b50c3 100644 > --- a/content.tex > +++ b/content.tex > @@ -254,6 +254,24 @@ they have been made available. These devices can offer the > VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge > might allow optimizations or simplify driver code. > > +Each virtqueue can consist of up to 3 parts: > +\begin{itemize} > +\item Descriptor Area - used for describing buffers > +\item Driver Area - extra data supplied by driver to the device > +\item Device Area - extra data supplied by device to driver > +\end{itemize} > + > +\begin{note} > +Note that previous versions of this spec used different names for > +these parts (following \ref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}): > +\begin{itemize} > +\item Descriptor Table - for the Descriptor Area > +\item Available Ring - fir the Driver Area s/fir/for/ > +\item Used Ring - for the Device Area > +\end{itemize} > + > +\end{note} > + > Two formats are supported: Split Virtqueues (see \ref{sec:Basic > Facilities of a Virtio Device / Split > Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / > @@ -683,8 +701,8 @@ struct virtio_pci_common_cfg { > le16 queue_enable; /* read-write */ > le16 queue_notify_off; /* read-only for driver */ > le64 queue_desc; /* read-write */ > - le64 queue_avail; /* read-write */ > - le64 queue_used; /* read-write */ > + le64 queue_driver; /* read-write */ > + le64 queue_device; /* read-write */ > }; > \end{lstlisting} > > @@ -744,13 +762,13 @@ struct virtio_pci_common_cfg { > \end{note} > > \item[\field{queue_desc}] > - The driver writes the physical address of Descriptor Table here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > + The driver writes the physical address of Descriptor Area here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > > -\item[\field{queue_avail}] > - The driver writes the physical address of Available Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > +\item[\field{queue_driver}] > + The driver writes the physical address of Driver Area here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > > -\item[\field{queue_used}] > - The driver writes the physical address of Used Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > +\item[\field{queue_device}] > + The driver writes the physical address of Device Area here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. > \end{description} > > \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} > @@ -1512,24 +1530,24 @@ All register values are organized as Little Endian. > See also p. \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}. > } > \hline > - \mmiodreg{QueueDescLow}{QueueDescHigh}{Virtual queue's Descriptor Table 64 bit long physical address}{0x080}{0x084}{W}{% > + \mmiodreg{QueueDescLow}{QueueDescHigh}{Virtual queue's Descriptor Area 64 bit long physical address}{0x080}{0x084}{W}{% > Writing to these two registers (lower 32 bits of the address > to \field{QueueDescLow}, higher 32 bits to \field{QueueDescHigh}) notifies > - the device about location of the Descriptor Table of the queue > + the device about location of the Descriptor Area of the queue > selected by writing to \field{QueueSel} register. > } > \hline > - \mmiodreg{QueueAvailLow}{QueueAvailHigh}{Virtual queue's Available Ring 64 bit long physical address}{0x090}{0x094}{W}{% > + \mmiodreg{QueueDriverLow}{QueueDriverHigh}{Virtual queue's Driver Area 64 bit long physical address}{0x090}{0x094}{W}{% > Writing to these two registers (lower 32 bits of the address > to \field{QueueAvailLow}, higher 32 bits to \field{QueueAvailHigh}) notifies > - the device about location of the Available Ring of the queue > + the device about location of the Driver Area of the queue > selected by writing to \field{QueueSel}. > } > \hline > - \mmiodreg{QueueUsedLow}{QueueUsedHigh}{Virtual queue's Used Ring 64 bit long physical address}{0x0a0}{0x0a4}{W}{% > + \mmiodreg{QueueDeviceLow}{QueueDeviceHigh}{Virtual queue's Device Area 64 bit long physical address}{0x0a0}{0x0a4}{W}{% > Writing to these two registers (lower 32 bits of the address > to \field{QueueUsedLow}, higher 32 bits to \field{QueueUsedHigh}) notifies > - the device about location of the Used Ring of the queue > + the device about location of the Device Area of the queue > selected by writing to \field{QueueSel}. > } > \hline > @@ -1647,11 +1665,11 @@ The driver will typically initialize the virtual queue in the following way: > \item Notify the device about the queue size by writing the size to > \field{QueueNum}. > > -\item Write physical addresses of the queue's Descriptor Table, > - Available Ring and Used Ring to (respectively) the > +\item Write physical addresses of the queue's Descriptor Area, > + Driver Area and Device Area to (respectively) the > \field{QueueDescLow}/\field{QueueDescHigh}, > - \field{QueueAvailLow}/\field{QueueAvailHigh} and > - \field{QueueUsedLow}/\field{QueueUsedHigh} register pairs. > + \field{QueueDriverLow}/\field{QueueDriverHigh} and > + \field{QueueDeviceLow}/\field{QueueDeviceHigh} register pairs. > > \item Write 0x1 to \field{QueueReady}. > \end{enumerate} > @@ -2041,13 +2059,14 @@ struct vq_info_block { > be32 res0; > be16 index; > be16 num; > - be64 avail; > - be64 used; > + be64 driver; > + be64 device; > }; > \end{lstlisting} > > -\field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table, > -available ring and used ring for queue \field{index}, respectively. The actual > +\field{desc}, \field{driver} and \field{device} contain the guest > +addresses for the descriptor area, > +available area and used area for queue \field{index}, respectively. The actual > virtqueue size (number of allocated buffers) is transmitted in \field{num}. > > \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue} > diff --git a/packed-ring.tex b/packed-ring.tex > index a2cf8ec..eb6136a 100644 > --- a/packed-ring.tex > +++ b/packed-ring.tex > @@ -15,9 +15,9 @@ allocated by driver. > Each packed virtqueue consists of three parts: > > \begin{itemize} > -\item Descriptor Ring > -\item Device Event Suppression > -\item Driver Event Suppression > +\item Descriptor Ring - occupies the Descriptor Area > +\item Device Event Suppression - occupies the Driver Area > +\item Driver Event Suppression - occupies the Device Area > \end{itemize} > > Where Descriptor Ring in turn consists of descriptors, > diff --git a/split-ring.tex b/split-ring.tex > index 2770289..f976e45 100644 > --- a/split-ring.tex > +++ b/split-ring.tex > @@ -15,9 +15,9 @@ of the queue. > Each virtqueue consists of three parts: > > \begin{itemize} > -\item Descriptor Table > -\item Available Ring > -\item Used Ring > +\item Descriptor Table - occupies the Descriptor Area > +\item Available Ring - occupies the Driver Area > +\item Used Ring - occupies the Device Area > \end{itemize} > > where each part is physically-contiguous in guest memory, Looks good to me.