From: Parav Pandit <parav@nvidia.com> To: <mst@redhat.com>, <virtio-dev@lists.oasis-open.org>, <pasic@linux.ibm.com>, <cohuck@redhat.com> Cc: <virtio-comment@lists.oasis-open.org>, <shahafs@nvidia.com>, Parav Pandit <parav@nvidia.com>, Jiri Pirko <jiri@nvidia.com> Subject: [virtio-dev] [PATCH v6 3/8] transport-mmio: Rename QueueNum register Date: Fri, 24 Mar 2023 04:04:27 +0300 [thread overview] Message-ID: <20230324010432.280330-4-parav@nvidia.com> (raw) In-Reply-To: <20230324010432.280330-1-parav@nvidia.com> Currently specification uses virtqueue index and number interchangeably to refer to the virtqueue. It is better to always refer to it the virtqueue in consistent manner. Two registers QueueNumMax and QueueNum actually reflects the queue size or queue depth indicating max and actual number of entries in the queue. These are further named differently between pci and mmio transport. PCI transport indicates queue size as queue_size. To bring consistency between pci and mmio transport, and to avoid confusion between number and index, rename the QueueNumMax and QueueNum registers to QueueSizeMax and QueueSize respectively. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/163 Reviewed-by: Jiri Pirko <jiri@nvidia.com> Signed-off-by: Parav Pandit <parav@nvidia.com> --- changelog: v0->v1: - replaced references of QueueNumMax to QueueSizeMax - replaced references of QueueNum to QueueSize - added note for renamed fields old name suggested by @Michael Tsirkin --- transport-mmio.tex | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/transport-mmio.tex b/transport-mmio.tex index f884a2c..3047633 100644 --- a/transport-mmio.tex +++ b/transport-mmio.tex @@ -110,24 +110,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, + following operations on \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index number of the first queue is zero (0x0). } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size (number of elements) of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% @@ -308,11 +315,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi Before writing to the \field{DriverFeatures} register, the driver MUST write a value to the \field{DriverFeaturesSel} register. -The driver MUST write a value to \field{QueueNum} which is less than -or equal to the value presented by the device in \field{QueueNumMax}. +The driver MUST write a value to \field{QueueSize} which is less than +or equal to the value presented by the device in \field{QueueSizeMax}. When \field{QueueReady} is not zero, the driver MUST NOT access -\field{QueueNum}, \field{QueueDescLow}, \field{QueueDescHigh}, +\field{QueueSize}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh}. To stop using the queue the driver MUST write zero (0x0) to this @@ -363,14 +370,14 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir and expect a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue memory, making sure the memory is physically contiguous. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Write physical addresses of the queue's Descriptor Area, Driver Area and Device Area to (respectively) the @@ -465,25 +472,32 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on the \field{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} + following operations on the \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index number of the first queue is zero (0x0). . } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel} and is allowed only when \field{QueuePFN} is set to zero (0x0), so when the queue is not actively used. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{% @@ -543,16 +557,16 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M expecting a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue pages in contiguous virtual memory, aligning the Used Ring to an optimal boundary (usually page size). The driver should choose a queue size smaller than or - equal to \field{QueueNumMax}. + equal to \field{QueueSizeMax}. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Notify the device about the used alignment by writing its value in bytes to \field{QueueAlign}. -- 2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
WARNING: multiple messages have this Message-ID (diff)
From: Parav Pandit <parav@nvidia.com> To: <mst@redhat.com>, <virtio-dev@lists.oasis-open.org>, <pasic@linux.ibm.com>, <cohuck@redhat.com> Cc: <virtio-comment@lists.oasis-open.org>, <shahafs@nvidia.com>, Parav Pandit <parav@nvidia.com>, Jiri Pirko <jiri@nvidia.com> Subject: [virtio-comment] [PATCH v6 3/8] transport-mmio: Rename QueueNum register Date: Fri, 24 Mar 2023 04:04:27 +0300 [thread overview] Message-ID: <20230324010432.280330-4-parav@nvidia.com> (raw) In-Reply-To: <20230324010432.280330-1-parav@nvidia.com> Currently specification uses virtqueue index and number interchangeably to refer to the virtqueue. It is better to always refer to it the virtqueue in consistent manner. Two registers QueueNumMax and QueueNum actually reflects the queue size or queue depth indicating max and actual number of entries in the queue. These are further named differently between pci and mmio transport. PCI transport indicates queue size as queue_size. To bring consistency between pci and mmio transport, and to avoid confusion between number and index, rename the QueueNumMax and QueueNum registers to QueueSizeMax and QueueSize respectively. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/163 Reviewed-by: Jiri Pirko <jiri@nvidia.com> Signed-off-by: Parav Pandit <parav@nvidia.com> --- changelog: v0->v1: - replaced references of QueueNumMax to QueueSizeMax - replaced references of QueueNum to QueueSize - added note for renamed fields old name suggested by @Michael Tsirkin --- transport-mmio.tex | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/transport-mmio.tex b/transport-mmio.tex index f884a2c..3047633 100644 --- a/transport-mmio.tex +++ b/transport-mmio.tex @@ -110,24 +110,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, + following operations on \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index number of the first queue is zero (0x0). } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size (number of elements) of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% @@ -308,11 +315,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi Before writing to the \field{DriverFeatures} register, the driver MUST write a value to the \field{DriverFeaturesSel} register. -The driver MUST write a value to \field{QueueNum} which is less than -or equal to the value presented by the device in \field{QueueNumMax}. +The driver MUST write a value to \field{QueueSize} which is less than +or equal to the value presented by the device in \field{QueueSizeMax}. When \field{QueueReady} is not zero, the driver MUST NOT access -\field{QueueNum}, \field{QueueDescLow}, \field{QueueDescHigh}, +\field{QueueSize}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh}. To stop using the queue the driver MUST write zero (0x0) to this @@ -363,14 +370,14 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir and expect a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue memory, making sure the memory is physically contiguous. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Write physical addresses of the queue's Descriptor Area, Driver Area and Device Area to (respectively) the @@ -465,25 +472,32 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on the \field{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} + following operations on the \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index number of the first queue is zero (0x0). . } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel} and is allowed only when \field{QueuePFN} is set to zero (0x0), so when the queue is not actively used. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{% @@ -543,16 +557,16 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M expecting a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue pages in contiguous virtual memory, aligning the Used Ring to an optimal boundary (usually page size). The driver should choose a queue size smaller than or - equal to \field{QueueNumMax}. + equal to \field{QueueSizeMax}. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Notify the device about the used alignment by writing its value in bytes to \field{QueueAlign}. -- 2.26.2 This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: virtio-comment-subscribe@lists.oasis-open.org Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org List help: virtio-comment-help@lists.oasis-open.org List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
next prev parent reply other threads:[~2023-03-24 1:05 UTC|newest] Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top 2023-03-24 1:04 [virtio-dev] [PATCH v6 0/8] Rename queue index to queue number Parav Pandit 2023-03-24 1:04 ` [virtio-comment] " Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 1/8] content: Add vq number text Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 2/8] transport-pci: Refer to the vq by its number Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit 2023-03-24 1:04 ` Parav Pandit [this message] 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 3/8] transport-mmio: Rename QueueNum register Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 4/8] transport-mmio: Refer to the vq by its number Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit 2023-03-27 10:03 ` [virtio-dev] Re: [virtio-comment] " Stefano Garzarella 2023-03-27 10:03 ` Stefano Garzarella 2023-03-27 13:41 ` [virtio-dev] " Parav Pandit 2023-03-27 13:41 ` Parav Pandit 2023-03-27 13:58 ` [virtio-dev] " Stefano Garzarella 2023-03-27 13:58 ` Stefano Garzarella 2023-03-27 14:14 ` [virtio-dev] " Parav Pandit 2023-03-27 14:14 ` Parav Pandit 2023-03-24 1:04 ` [virtio-dev] [PATCH v6 5/8] transport-ccw: Rename queue depth/size to other transports Parav Pandit 2023-03-24 1:04 ` [virtio-comment] " Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 6/8] transport-ccw: Refer to the vq by its number Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 7/8] virtio-net: Avoid duplicate receive queue example Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit 2023-03-24 1:04 ` [virtio-comment] [PATCH v6 8/8] virtio-net: Describe RSS using rss rq id Parav Pandit 2023-03-24 1:04 ` [virtio-dev] " Parav Pandit
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20230324010432.280330-4-parav@nvidia.com \ --to=parav@nvidia.com \ --cc=cohuck@redhat.com \ --cc=jiri@nvidia.com \ --cc=mst@redhat.com \ --cc=pasic@linux.ibm.com \ --cc=shahafs@nvidia.com \ --cc=virtio-comment@lists.oasis-open.org \ --cc=virtio-dev@lists.oasis-open.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.