* [virtio] [PATCH RFC] content: generalize transport ring part naming
@ 2018-01-10 15:05 Michael S. Tsirkin
2018-01-10 15:50 ` Cornelia Huck
0 siblings, 1 reply; 2+ messages in thread
From: Michael S. Tsirkin @ 2018-01-10 15:05 UTC (permalink / raw)
To: virtio, virtio-dev
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
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [virtio] [PATCH RFC] content: generalize transport ring part naming
2018-01-10 15:05 [virtio] [PATCH RFC] content: generalize transport ring part naming Michael S. Tsirkin
@ 2018-01-10 15:50 ` Cornelia Huck
0 siblings, 0 replies; 2+ messages in thread
From: Cornelia Huck @ 2018-01-10 15:50 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
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.
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2018-01-10 15:50 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-01-10 15:05 [virtio] [PATCH RFC] content: generalize transport ring part naming Michael S. Tsirkin
2018-01-10 15:50 ` Cornelia Huck
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox