[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [virtio-comment] [PATCH v8 3/8] transport-mmio: Rename QueueNum register
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.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]