From: David Edmondson <david.edmondson@oracle.com>
To: Parav Pandit <parav@nvidia.com>,
mst@redhat.com, virtio-dev@lists.oasis-open.org,
pasic@linux.ibm.com, cohuck@redhat.com
Cc: sgarzare@redhat.com, virtio-comment@lists.oasis-open.org,
shahafs@nvidia.com, Parav Pandit <parav@nvidia.com>,
Jiri Pirko <jiri@nvidia.com>
Subject: Re: [virtio-comment] [PATCH v8 3/8] transport-mmio: Rename QueueNum register
Date: Tue, 28 Mar 2023 15:01:35 +0100 [thread overview]
Message-ID: <m24jq5c6v4.fsf@oracle.com> (raw)
In-Reply-To: <20230327235936.414196-4-parav@nvidia.com>
Parav Pandit <parav@nvidia.com> writes:
> 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.
Use \field for the old name (and in other places).
> + \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/
--
I didn't get a lot in class, but I know it don't come in a shot glass.
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-28 14:01 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-27 23:59 [virtio-comment] [PATCH v8 0/8] Rename queue index to queue number Parav Pandit
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 1/8] content: Add vq number text Parav Pandit
2023-03-28 13:56 ` [virtio-comment] Re: [virtio-dev] " David Edmondson
2023-03-28 14:00 ` Parav Pandit
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 2/8] transport-pci: Refer to the vq by its number Parav Pandit
2023-03-28 13:58 ` [virtio-comment] Re: [virtio-dev] " David Edmondson
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 3/8] transport-mmio: Rename QueueNum register Parav Pandit
2023-03-28 14:01 ` David Edmondson [this message]
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 4/8] transport-mmio: Refer to the vq by its number Parav Pandit
2023-03-28 14:05 ` David Edmondson
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 5/8] transport-ccw: Rename queue depth/size to other transports Parav Pandit
2023-03-28 14:07 ` David Edmondson
2023-03-28 15:04 ` Parav Pandit
2023-03-28 16:16 ` David Edmondson
2023-03-28 16:18 ` Parav Pandit
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 6/8] transport-ccw: Refer to the vq by its number Parav Pandit
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 7/8] virtio-net: Avoid duplicate receive queue example Parav Pandit
2023-03-27 23:59 ` [virtio-comment] [PATCH v8 8/8] virtio-net: Describe RSS using rss rq id Parav Pandit
2023-03-28 14:13 ` [virtio-comment] Re: [virtio-dev] " David Edmondson
2023-03-28 13:53 ` [virtio-comment] Re: [virtio-dev] [PATCH v8 0/8] Rename queue index to queue number David Edmondson
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=m24jq5c6v4.fsf@oracle.com \
--to=david.edmondson@oracle.com \
--cc=cohuck@redhat.com \
--cc=jiri@nvidia.com \
--cc=mst@redhat.com \
--cc=parav@nvidia.com \
--cc=pasic@linux.ibm.com \
--cc=sgarzare@redhat.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: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).