virtio — archive

[Michael S. Tsirkin]

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: +egin{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} + +egin{note} +Note that previous versions of this spec used different names for +these parts (following ef{sec:Basic Facilities of a Virtio Device / Split Virtqueues}): +egin{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 ef{sec:Basic Facilities of a Virtio Device / Split Virtqueues}~ ameref{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 ef{sec:Basic Facilities of a Virtio Device / Virtqueues}. + The driver writes the physical address of Descriptor Area here. See section ef{sec:Basic Facilities of a Virtio Device / Virtqueues}. -item[field{queue_avail}] - The driver writes the physical address of Available Ring here. See section ef{sec:Basic Facilities of a Virtio Device / Virtqueues}. +item[field{queue_driver}] + The driver writes the physical address of Driver Area here. See section ef{sec:Basic Facilities of a Virtio Device / Virtqueues}. -item[field{queue_used}] - The driver writes the physical address of Used Ring here. See section ef{sec:Basic Facilities of a Virtio Device / Virtqueues}. +item[field{queue_device}] + The driver writes the physical address of Device Area here. See section ef{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. ef{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~ ameref{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: egin{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: egin{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