[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH RFC] content: generalize transport ring part naming
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
+\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,
--
MST
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]