Skip to content

Commit

Permalink
transport-mmio: Replace virtual queue with virtqueue
Browse files Browse the repository at this point in the history 
Basic facilities define the virtqueue construct for device <-> driver
communication.

PCI transport and individual devices description also refers to it as
virtqueue.

MMIO refers to it as 'virtual queue'.

Align MMIO transport description to call such object a virtqueue.

Fixes: #168
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
  • Loading branch information
@paravmellanox @mstsirkin
paravmellanox authored and mstsirkin committed May 19, 2023
1 parent f9ff777 commit 74460ef
Showing 1 changed file with 25 additions and 25 deletions.
50 changes: 25 additions & 25 deletions transport-mmio.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,15 +108,15 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
bits accessible by writing to \field{DriverFeatures}.
}
\hline
\mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{%
Writing to this register selects the virtual queue that the
\mmioreg{QueueSel}{Virtqueue index}{0x030}{W}{%
Writing to this register selects the virtqueue that the
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.
}
\hline
\mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
\mmioreg{QueueSizeMax}{Maximum virtqueue 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
Expand All @@ -126,7 +126,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
\end{note}
}
\hline
\mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{%
\mmioreg{QueueSize}{Virtqueue 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
Expand All @@ -136,9 +136,9 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
\end{note}
}
\hline
\mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{%
\mmioreg{QueueReady}{Virtqueue ready bit}{0x044}{RW}{%
Writing one (0x1) to this register notifies the device that it can
execute requests from this virtual queue. Reading from this register
execute requests from this virtqueue. Reading from this register
returns the last value written to it. Both read and write
accesses apply to the queue selected by writing to \field{QueueSel}.
}
Expand Down Expand Up @@ -166,7 +166,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
\begin{description}
\item[Used Buffer Notification] - bit 0 - the interrupt was asserted
because the device has used a buffer
in at least one of the active virtual queues.
in at least one of the active virtqueues.
\item [Configuration Change Notification] - bit 1 - the interrupt was
asserted because the configuration of the device has changed.
\end{description}
Expand All @@ -187,21 +187,21 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
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 Area 64 bit long physical address}{0x080}{0x084}{W}{%
\mmiodreg{QueueDescLow}{QueueDescHigh}{Virtqueue'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 Area of the queue
selected by writing to \field{QueueSel} register.
}
\hline
\mmiodreg{QueueDriverLow}{QueueDriverHigh}{Virtual queue's Driver Area 64 bit long physical address}{0x090}{0x094}{W}{%
\mmiodreg{QueueDriverLow}{QueueDriverHigh}{Virtqueue's Driver Area 64 bit long physical address}{0x090}{0x094}{W}{%
Writing to these two registers (lower 32 bits of the address
to \field{QueueDriverLow}, higher 32 bits to \field{QueueDriverHigh}) notifies
the device about location of the Driver Area of the queue
selected by writing to \field{QueueSel}.
}
\hline
\mmiodreg{QueueDeviceLow}{QueueDeviceHigh}{Virtual queue's Device Area 64 bit long physical address}{0x0a0}{0x0a4}{W}{%
\mmiodreg{QueueDeviceLow}{QueueDeviceHigh}{Virtqueue's Device Area 64 bit long physical address}{0x0a0}{0x0a4}{W}{%
Writing to these two registers (lower 32 bits of the address
to \field{QueueDeviceLow}, higher 32 bits to \field{QueueDeviceHigh}) notifies
the device about location of the Device Area of the queue
Expand Down Expand Up @@ -235,7 +235,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
0xffffffffffffffff.
}
\hline
\mmioreg{QueueReset}{Virtual queue reset bit}{0x0c0}{RW}{%
\mmioreg{QueueReset}{Virtqueue reset bit}{0x0c0}{RW}{%
If VIRTIO_F_RING_RESET has been negotiated, writing one (0x1) to this
register selectively resets the queue. Both read and write accesses
apply to the queue selected by writing to \field{QueueSel}.
Expand Down Expand Up @@ -274,7 +274,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
The device MUST change value returned in \field{ConfigGeneration} if there is any risk of a
driver seeing an inconsistent configuration state.

The device MUST NOT access virtual queue contents when \field{QueueReady} is zero (0x0).
The device MUST NOT access virtqueue contents when \field{QueueReady} is zero (0x0).

If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
\field{QueueReset} on reset.
Expand Down Expand Up @@ -359,7 +359,7 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti

\subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Virtqueue Configuration}

The driver will typically initialize the virtual queue in the following way:
The driver will typically initialize the virtqueue in the following way:

\begin{enumerate}
\item Select the queue by writing its index to \field{QueueSel}.
Expand Down Expand Up @@ -422,7 +422,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M

The legacy MMIO transport used page-based addressing, resulting
in a slightly different control register layout, the device
initialization and the virtual queue configuration procedure.
initialization and the virtqueue configuration procedure.

Table \ref{tab:Virtio Transport Options / Virtio Over MMIO / MMIO Device Legacy Register Layout}
presents control registers layout, omitting
Expand Down Expand Up @@ -468,14 +468,14 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
(see QueuePFN).
}
\hline
\mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{%
Writing to this register selects the virtual queue that the
\mmioreg{QueueSel}{Virtqueue index}{0x030}{W}{%
Writing to this register selects the virtqueue that the
following operations on the \field{QueueSizeMax},
\field{QueueSize}, \field{QueueAlign}
and \field{QueuePFN} registers apply to.
}
\hline
\mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
\mmioreg{QueueSizeMax}{Maximum virtqueue 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
Expand All @@ -486,7 +486,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
\end{note}
}
\hline
\mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{%
\mmioreg{QueueSize}{Virtqueue 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
Expand All @@ -496,15 +496,15 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
\end{note}
}
\hline
\mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{%
\mmioreg{QueueAlign}{Used Ring alignment in the virtqueue}{0x03c}{W}{%
Writing to this register notifies the device about alignment
boundary of the Used Ring in bytes. This value should be a power
of 2 and applies to the queue selected by writing to \field{QueueSel}.
}
\hline
\mmioreg{QueuePFN}{Guest physical page number of the virtual queue}{0x040}{RW}{%
\mmioreg{QueuePFN}{Guest physical page number of the virtqueue}{0x040}{RW}{%
Writing to this register notifies the device about location of the
virtual queue in the Guest's physical address space. This value
virtqueue in the Guest's physical address space. This value
is the index number of a page starting with the queue
Descriptor Table. Value zero (0x0) means physical address zero
(0x00000000) and is illegal. When the driver stops using the
Expand Down Expand Up @@ -536,15 +536,15 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
\hline
\end{longtable}

The virtual queue page size is defined by writing to \field{GuestPageSize},
The virtqueue page size is defined by writing to \field{GuestPageSize},
as written by the guest. The driver does this before the
virtual queues are configured.
virtqueues are configured.

The virtual queue layout follows
The virtqueue layout follows
p. \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout},
with the alignment defined in \field{QueueAlign}.

The virtual queue is configured as follows:
The virtqueue is configured as follows:
\begin{enumerate}
\item Select the queue by writing its index to \field{QueueSel}.

Expand Down

0 comments on commit 74460ef

Please sign in to comment.