summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorrusty <rusty@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2013-12-02 12:30:30 +0000
committerrusty <rusty@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2013-12-02 12:30:30 +0000
commitf37b614cd3760036d9302f1e9bf985ec19892586 (patch)
tree5034948252499faac9c93793906a878d0f0b18b1
parent6c27c890461a8184b9684649158793cb669f655b (diff)
Terminology: Device and driver, not host and guest.
We've mixed both together, whereas from a spec-reader point of view, "driver" and "device" is probably clearer. CCW part incorporated: Switch the parts of the virtio-ccw specification that did not already to device/driver instead of guest/host. For more general discussions, host/guest is kept (like when talking about guest<->host notifications in general). This should make things more consistent. Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Rusty Russell <rusty@au1.ibm.com> git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@145 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652
-rw-r--r--content.tex264
-rw-r--r--introduction.tex2
-rw-r--r--virtio-ring.h6
3 files changed, 136 insertions, 136 deletions
diff --git a/content.tex b/content.tex
index 37c8257..a911383 100644
--- a/content.tex
+++ b/content.tex
@@ -15,7 +15,7 @@ To reinforce this the examples use typenames like "le16" instead of "uint16_t".
\section{Device Status Field}\label{sec:Basic Facilities of a Virtio Device / Device Status Field}
-The Device Status field is updated by the guest to indicate its
+The Device Status field is updated by the guest/driver to indicate its
progress. This provides a simple low-level diagnostic: it's most
useful to imagine them hooked up to traffic lights on the console
indicating the status of each device.
@@ -45,14 +45,14 @@ This field is 0 upon reset, otherwise at least one bit should be set:
\section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature Bits}
Each virtio device lists all the features it understands. During
-device initialization, the guest reads this and tells the device the
+device initialization, the driver reads this and tells the device the
subset that it understands. The only way to renegotiate is to reset
the device.
This allows for forwards and backwards compatibility: if the device is
-enhanced with a new feature bit, older guests will not write that
+enhanced with a new feature bit, older drivers will not write that
feature bit back to the device and it can go into backwards
-compatibility mode. Similarly, if a guest is enhanced with a feature
+compatibility mode. Similarly, if a driver is enhanced with a feature
that the device doesn't support, it see the new feature is not offered
and can go into backwards compatibility mode (or, for poor
implementations, set the FAILED Device Status bit).
@@ -71,7 +71,7 @@ Device ID 1) indicates that the device supports checksumming of
packets.
In particular, new fields in the device configuration space are
-indicated by offering a feature bit, so the guest can check
+indicated by offering a feature bit, so the driver can check
before accessing that part of the configuration space.
\subsection{Legacy Interface: A Note on transitions from earlier drafts}\label{sec:Basic Facilities of a Virtio Device / Feature Bits / Legacy Interface: A Note on transitions from earlier drafts}
@@ -315,7 +315,7 @@ VIRTIO_F_ANY_LAYOUT feature is accepted.
\subsection{The Virtqueue Descriptor Table}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
-The descriptor table refers to the buffers the guest is using for
+The descriptor table refers to the buffers the driver is using for
the device. The addresses are physical addresses, and the buffers
can be chained via the next field. Each descriptor describes a
buffer which is read-only or write-only, but a chain of
@@ -389,7 +389,7 @@ The available ring refers to what descriptor chains we are offering the
device: each entry refers to the head of a descriptor chain. The “flags” field
is currently 0 or 1: 1 indicating that we do not need an interrupt
when the device consumes a descriptor chain from the available
-ring. Alternatively, the guest can ask the device to delay interrupts
+ring. Alternatively, the driver can ask the device to delay interrupts
until an entry with an index specified by the “used_event” field is
written in the used ring (equivalently, until the idx field in the
used ring will reach the value used_event + 1). The method employed by
@@ -414,13 +414,13 @@ entry (modulo the queue size). This starts at 0, and increases.
The used ring is where the device returns buffers once it is done
with them. The flags field can be used by the device to hint that
-no notification is necessary when the guest adds to the available
+no notification is necessary when the driver adds to the available
ring. Alternatively, the “avail_event” field can be used by the
device to hint that no notification is necessary until an entry
with an index specified by the “avail_event” is written in the
available ring (equivalently, until the idx field in the
available ring will reach the value avail_event + 1). The method
-employed by the device is controlled by the guest through the
+employed by the device is controlled by the driver through the
VIRTIO_RING_F_EVENT_IDX feature bit (
see \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}).
\footnote{These fields are kept here because this is the only part of the
@@ -429,9 +429,9 @@ virtqueue written by the device
Each entry in the ring is a pair: the head entry of the
descriptor chain describing the buffer (this matches an entry
-placed in the available ring by the guest earlier), and the total
+placed in the available ring by the driver earlier), and the total
of bytes written into the buffer. The latter is extremely useful
-for guests using untrusted buffers: if you do not know exactly
+for drivers using untrusted buffers: if you do not know exactly
how much has been written by the device, you usually have to zero
the buffer to ensure no data leakage occurs.
@@ -493,7 +493,7 @@ how to communicate with the specific device.
8. The DRIVER_OK status bit is set. At this point the device is
"live".
-If any of these steps go irrecoverably wrong, the guest should
+If any of these steps go irrecoverably wrong, the driver should
set the FAILED status bit to indicate that it has given up on the
device (it can reset the device later to restart if desired).
@@ -682,11 +682,11 @@ buffer:
(u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx)
\end{lstlisting}
-For each ring, guest should then disable interrupts by writing
+For each ring, the driver should then disable interrupts by writing
VRING_AVAIL_F_NO_INTERRUPT flag in avail structure, if required.
It can then process used ring entries finally enabling interrupts
by clearing the VRING_AVAIL_F_NO_INTERRUPT flag or updating the
-EVENT_IDX field in the available structure. The guest should then
+EVENT_IDX field in the available structure. The driver should then
execute a memory barrier, and then recheck the ring empty
condition. This is necessary to handle the case where after the
last check and before enabling interrupts, an interrupt has been
@@ -736,7 +736,7 @@ Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through
The Subsystem Device ID indicates which virtio device is
supported by the device. The Subsystem Vendor ID should reflect
the PCI Vendor ID of the environment (it's currently only used
-for informational purposes by the guest).
+for informational purposes by the driver).
All Drivers must match devices with any Revision ID, this
is to allow devices to be versioned without breaking drivers.
@@ -776,8 +776,8 @@ Common configuration structure layout is documented below:
/* About the whole device. */
le32 device_feature_select; /* read-write */
le32 device_feature; /* read-only */
- le32 guest_feature_select; /* read-write */
- le32 guest_feature; /* read-write */
+ le32 driver_feature_select; /* read-write */
+ le32 driver_feature; /* read-write */
le16 msix_config; /* read-write */
le16 num_queues; /* read-only */
u8 device_status; /* read-write */
@@ -804,22 +804,22 @@ device_feature_select
device_feature
- Used by Device to report Feature Bits to Driver.
+ Used by device to report Feature Bits to driver.
Device Feature Bits selected by device_feature_select.
-guest_feature_select
+driver_feature_select
- Selects which Feature Bits does guest_feature field refer to.
+ Selects which Feature Bits does driver_feature field refer to.
Value 0x0 selects Feature Bits 0 to 31
Value 0x1 selects Feature Bits 32 to 63
- When set to any other value, reads from guest_feature
- return 0, writing 0 into guest_feature has no effect, and
- writing any other value into guest_feature is an error.
+ When set to any other value, reads from driver_feature
+ return 0, writing 0 into driver_feature has no effect, and
+ writing any other value into driver_feature is an error.
-guest_feature
+driver_feature
- Used by Driver to acknowledge Feature Bits to Device.
- Guest Feature Bits selected by guest_feature_select.
+ Used by driver to acknowledge Feature Bits to device.
+ Driver Feature Bits selected by driver_feature_select.
msix_config
@@ -858,7 +858,7 @@ queue_msix_vector
queue_enable
- Used to selectively prevent host from executing requests from this virtqueue.
+ Used to selectively prevent device from executing requests from this virtqueue.
1 - enabled; 0 - disabled
queue_notify_off
@@ -918,7 +918,7 @@ When used through the legacy interface, the virtio header looks as follows:
\hline
Read / Write & R & R+W & R+W & R & R+W & R+W & R+W & R \\
\hline
- Purpose & Device Features bits 0:31 & Guest Features bits 0:31 &
+ Purpose & Device Features bits 0:31 & Driver Features bits 0:31 &
Queue Size & Queue Select & Queue Notify & Queue Address &
Device Status & ISR \newline Status \\
\hline
@@ -1269,11 +1269,11 @@ If an interrupt is necessary:
ii. If Queue Vector field value is NO_VECTOR, no interrupt
message is requested for this event.
-The guest interrupt handler should:
+The driver interrupt handler should:
1. If MSI-X capability is disabled: read the ISR Status field,
which will reset it to zero. If the lower bit is zero, the
- interrupt was not for this device. Otherwise, the guest driver
+ interrupt was not for this device. Otherwise, the driver
should look through the used rings of each virtqueue for the
device, to see if any progress has been made by the device
which requires servicing.
@@ -1353,39 +1353,39 @@ configuration space. The following list presents their layout:
* 0x00c | R | VendorID
Virtio Subsystem Vendor ID.
-* 0x010 | R | HostFeatures
+* 0x010 | R | DeviceFeatures
Flags representing features the device supports.
Reading from this register returns 32 consecutive flag bits,
first bit depending on the last value written to the
- HostFeaturesSel register. Access to this register returns
- bits HostFeaturesSel*32 to (HostFeaturesSel*32)+31, eg.
- feature bits 0 to 31 if HostFeaturesSel is set to 0 and
- features bits 32 to 63 if HostFeaturesSel is set to 1.
+ DeviceFeaturesSel register. Access to this register returns
+ bits DeviceFeaturesSel*32 to (DeviceFeaturesSel*32)+31, eg.
+ feature bits 0 to 31 if DeviceFeaturesSel is set to 0 and
+ features bits 32 to 63 if DeviceFeaturesSel is set to 1.
Also see \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}~\nameref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
-* 0x014 | W | HostFeaturesSel
- Device (Host) features word selection.
+* 0x014 | W | DeviceFeaturesSel
+ Device (host) features word selection.
Writing to this register selects a set of 32 device feature bits
- accessible by reading from the HostFeatures register. Device driver
- must write a value to the HostFeaturesSel register before
- reading from the HostFeatures register.
+ accessible by reading from the DeviceFeatures register. Device driver
+ must write a value to the DeviceFeaturesSel register before
+ reading from the DeviceFeatures register.
-* 0x020 | W | GuestFeatures
+* 0x020 | W | DriverFeatures
Flags representing device features understood and activated by
the driver.
Writing to this register sets 32 consecutive flag bits, first
- bit depending on the last value written to the GuestFeaturesSel
- register. Access to this register sets bits GuestFeaturesSel*32
- to (GuestFeaturesSel*32)+31, eg. feature bits 0 to 31 if
- GuestFeaturesSel is set to 0 and features bits 32 to 63 if
- GuestFeaturesSel is set to 1. Also see \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}~\nameref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
-
-* 0x024 | W | GuestFeaturesSel
- Activated (Guest) features word selection.
+ bit depending on the last value written to the DriverFeaturesSel
+ register. Access to this register sets bits DriverFeaturesSel*32
+ to (DriverFeaturesSel*32)+31, eg. feature bits 0 to 31 if
+ DriverFeaturesSel is set to 0 and features bits 32 to 63 if
+ DriverFeaturesSel is set to 1. Also see \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}~\nameref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
+
+* 0x024 | W | DriverFeaturesSel
+ Activated (guest) features word selection.
Writing to this register selects a set of 32 activated feature
- bits accessible by writing to the GuestFeatures register.
- Device driver must write a value to the GuestFeaturesSel
- register before writing to the GuestFeatures register.
+ bits accessible by writing to the DriverFeatures register.
+ Device driver must write a value to the DriverFeaturesSel
+ register before writing to the DriverFeatures register.
* 0x030 | W | QueueSel
Virtual queue index (first queue is 0).
@@ -1397,7 +1397,7 @@ configuration space. The following list presents their layout:
* 0x034 | R | QueueNumMax
Maximum virtual queue size.
Reading from the register returns the maximum size of the queue
- the Host is ready to process or zero (0x0) if the queue is not
+ the device is ready to process or zero (0x0) if the queue is not
available. This applies to the queue selected by writing to
QueueSel and is allowed only when QueueReady is set to zero
(0x0), so when the queue is not in use.
@@ -1406,24 +1406,24 @@ configuration space. The following list presents their layout:
Virtual queue size.
Queue size is the number of elements in the queue, therefore size
of the Descriptor Table and both Available and Used rings.
- Writing to this register notifies the Host what size of the
- queue the Guest will use. This applies to the queue selected by
+ 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 QueueSel and is allowed only when QueueReady is set
to zero (0x0), so when the queue is not in use.
* 0x03c | RW | QueueReady
Virtual queue ready bit.
- Writing one (0x1) to this register notifies the Host that the
+ Writing one (0x1) to this register notifies the device that the
virtual queue is ready to be used. Reading from this register
returns the last value written to it. Both read and write
accesses apply to the queue selected by writing to QueueSel.
- When the Guest wants to stop using the queue it must write
+ When the Driver wants to stop using the queue it must write
zero (0x0) to this register and read the value back to
ensure synchronisation.
* 0x050 | W | QueueNotify
Queue notifier.
- Writing a queue index to this register notifies the Host that
+ Writing a queue index to this register notifies the device that
there are new buffers to process in the queue.
* 0x60 | R | InterruptStatus
@@ -1433,7 +1433,7 @@ configuration space. The following list presents their layout:
corresponding bit is set, ie. equals one (1).
– Bit 0 | Used Ring Update
- This interrupt is asserted when the Host has updated the Used
+ This interrupt is asserted when the device has updated the Used
Ring in at least one of the active virtual queues.
– Bit 1 | Configuration change
@@ -1442,7 +1442,7 @@ configuration space. The following list presents their layout:
* 0x064 | W | InterruptACK
Interrupt acknowledge.
- Writing to this register notifies the Host that the Guest
+ Writing to this register notifies the device that the Driver
finished handling interrupts. Set bits in the value clear
the corresponding bits of the InterruptStatus register.
@@ -1451,7 +1451,7 @@ configuration space. The following list presents their layout:
Reading from this register returns the current device status
flags.
Writing non-zero values to this register sets the status flags,
- indicating the Guest progress. Writing zero (0x0) to this
+ indicating the OS/driver progress. Writing zero (0x0) to this
register triggers a device reset, including clearing all
bits in the InterruptStatus register and ready bits in the
QueueReady register for all queues in the device.
@@ -1462,7 +1462,7 @@ configuration space. The following list presents their layout:
Virtual queue's Descriptor Table 64 bit long physical address.
Writing to these two registers (lower 32 bits of the address
to QueueDescLow, higher 32 bits to QueueDescHigh) notifies
- the host about location of the Descriptor Table of the queue
+ the device about location of the Descriptor Table of the queue
selected by writing to the QueueSel register. It is allowed
only when QueueReady is set to zero (0x0), so when the queue
is not in use.
@@ -1472,7 +1472,7 @@ configuration space. The following list presents their layout:
Virtual queue's Available Ring 64 bit long physical address.
Writing to these two registers (lower 32 bits of the address
to QueueAvailLow, higher 32 bits to QueueAvailHigh) notifies
- the host about location of the Available Ring of the queue
+ the device about location of the Available Ring of the queue
selected by writing to the QueueSel register. It is allowed
only when QueueReady is set to zero (0x0), so when the queue
is not in use.
@@ -1482,7 +1482,7 @@ configuration space. The following list presents their layout:
Virtual queue's Used Ring 64 bit long physical address.
Writing to these two registers (lower 32 bits of the address
to QueueUsedLow, higher 32 bits to QueueUsedHigh) notifies
- the host about location of the Used Ring of the queue
+ the device about location of the Used Ring of the queue
selected by writing to the QueueSel register. It is allowed
only when QueueReady is set to zero (0x0), so when the queue
is not in use.
@@ -1511,7 +1511,7 @@ can cause undefined behavior.
\subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}
-The guest must start the device initialization by reading and
+The driver must start the device initialization by reading and
checking values from the MagicValue and the Version registers.
If both values are valid, it must read the DeviceID register
and if its value is zero (0x0) must abort initialization and
@@ -1536,9 +1536,9 @@ p. \ref{sec:General Initialization And Device Operation / Device Initialization}
is physically contiguous. It is recommended to align the
Used Ring to an optimal boundary (usually page size).
Size of the allocated queue may be smaller than or equal to
- the maximum size returned by the Host.
+ the maximum size returned by the device.
-5. Notify the Host about the queue size by writing the size to
+5. Notify the device about the queue size by writing the size to
the QueueNum register.
6. Write physical addresses of the queue's Descriptor Table,
@@ -1602,9 +1602,9 @@ nor behaviour:
* 0x028 | W | GuestPageSize
Guest page size.
- Device driver must write the guest page size in bytes to the
+ The driver must write the guest page size in bytes to the
register during initialization, before any queues are used.
- This value must be a power of 2 and is used by the Host to
+ This value must be a power of 2 and is used by the device to
calculate the Guest address of the first queue page
(see QueuePFN).
@@ -1617,7 +1617,7 @@ nor behaviour:
* 0x034 | R | QueueNumMax
Maximum virtual queue size.
Reading from the register returns the maximum size of the queue
- the Host is ready to process or zero (0x0) if the queue is not
+ the device is ready to process or zero (0x0) if the queue is not
available. This applies to the queue selected by writing to the
QueueSel and is allowed only when the QueuePFN is set to zero
(0x0), so when the queue is not actively used.
@@ -1626,24 +1626,24 @@ nor behaviour:
Virtual queue size.
Queue size is the number of elements in the queue, therefore size
of the descriptor table and both available and used rings.
- Writing to this register notifies the Host what size of the
- queue the Guest will use. This applies to the queue selected by
+ 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 the QueueSel register.
* 0x03c | W | QueueAlign
Used Ring alignment in the virtual queue.
- Writing to this register notifies the Host about alignment
+ Writing to this register notifies the device about alignment
boundary of the Used Ring in bytes. This value must be a power
of 2 and applies to the queue selected by writing to the QueueSel
register.
* 0x040 | RW | QueuePFN
Guest physical page number of the virtual queue.
- Writing to this register notifies the host about location of the
+ Writing to this register notifies the device about location of the
virtual queue 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 Guest stops using the
+ (0x00000000) and is illegal. When the Driver stops using the
queue it must write zero (0x0) to this register.
Reading from this register returns the currently used page
number of the queue, therefore a value other than zero (0x0)
@@ -1662,7 +1662,7 @@ nor behaviour:
Reading from this register returns the current device status
flags.
Writing non-zero values to this register sets the status flags,
- indicating the Guest progress. Writing zero (0x0) to this
+ indicating the OS/driver progress. Writing zero (0x0) to this
register triggers a device reset. This should include
setting QueuePFN to zero (0x0) for all queues in the device.
Also see \ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.
@@ -1692,12 +1692,12 @@ The virtual queue is configured as follows:
4. Allocate and zero the queue pages in contiguous virtual
memory, aligning the Used Ring to an optimal boundary (usually
page size). Size of the allocated queue may be smaller than or
- equal to the maximum size returned by the Host.
+ equal to the maximum size returned by the device.
-5. Notify the Host about the queue size by writing the size to
+5. Notify the device about the queue size by writing the size to
the QueueNum register.
-6. Notify the Host about the used alignment by writing its value
+6. Notify the device about the used alignment by writing its value
in bytes to the QueueAlign register.
7. Write the physical number of the first page of the queue to
@@ -1875,7 +1875,7 @@ implies that the device must reject any command not valid for revision
\subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}
-CCW_CMD_READ_VQ_CONF is issued by the guest to obtain information
+CCW_CMD_READ_VQ_CONF is issued by the driver to obtain information
about a queue. It uses the following structure for communicating:
\begin{lstlisting}
@@ -1888,8 +1888,8 @@ about a queue. It uses the following structure for communicating:
The requested number of buffers for queue index is returned in
max_num.
-Afterwards, CCW_CMD_SET_VQ is issued by the guest to inform the
-host about the location used for its queue. The transmitted
+Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the
+device about the location used for its queue. The transmitted
structure is
\begin{lstlisting}
@@ -1950,7 +1950,7 @@ The calculation for total size is as follows:
\subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information}
-The guest can change the status of a device via the
+The driver can change the status of a device via the
CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status
value.
@@ -1974,11 +1974,11 @@ features are the 32 bits of features currently accessed, while
index describes which of the feature bit values is to be
accessed.
-The guest may obtain the host's device feature set via the
-CCW_CMD_READ_FEAT command. The host stores the features at index
+The guest may obtain the device's device feature set via the
+CCW_CMD_READ_FEAT command. The device stores the features at index
to features.
-For communicating its device features to the host, the guest may
+For communicating its supported features to the device, the driver may
use the CCW_CMD_WRITE_FEAT command, denoting a features/index
combination.
@@ -1987,16 +1987,16 @@ combination.
The device's configuration space is located in host memory. It is
the same size as the standard PCI configuration space.
-To obtain information from the configuration space, the guest may
-use CCW_CMD_READ_CONF, specifying the guest memory for the host
+To obtain information from the configuration space, the driver may
+use CCW_CMD_READ_CONF, specifying the guest memory for the device
to write to.
-For changing configuration information, the guest may use
-CCW_CMD_WRITE_CONF, specifying the guest memory for the host to
+For changing configuration information, the driver may use
+CCW_CMD_WRITE_CONF, specifying the guest memory for the device to
read from.
In both cases, the complete configuration space is transmitted. This
-allows the guest to compare the new configuration space with the old
+allows the driver to compare the new configuration space with the old
version, and keep a generation count internally whenever it changes.
\subsubsection{Setting Up Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators}
@@ -2018,7 +2018,7 @@ Indicators for notification via classic I/O interrupts are contained
in a 64 bit value per virtio-ccw proxy device.
To communicate the location of the indicator bits for host->guest
-notification, the guest uses the CCW_CMD_SET_IND command,
+notification, the driver uses the CCW_CMD_SET_IND command,
pointing to a location containing the guest address of the
indicators in a 64 bit value.
@@ -2094,12 +2094,12 @@ If the driver used the CCW_CMD_SET_IND command to set up queue
indicators, the device will use classic I/O interrupts for
host->guest notification about virtqueue activity.
-For notifying the guest of virtqueue buffers, the host sets the
+For notifying the driver of virtqueue buffers, the device sets the
corresponding bit in the guest-provided indicators. If an
-interrupt is not already pending for the subchannel, the host
+interrupt is not already pending for the subchannel, the device
generates an unsolicited I/O interrupt.
-If the host wants to notify the guest about configuration
+If the device wants to notify the driver about configuration
changes, it sets bit 0 in the configuration indicators and
generates an unsolicited I/O interrupt, if needed. This also
applies if adapter I/O interrupts are used for queue notifications.
@@ -2110,7 +2110,7 @@ If the driver used the CCW_CMD_SET_IND_ADAPTER command to set up
queue indicators, the device will use adapter I/O interrupts for
host->guest notification about virtqueue activity.
-For notifying the guest of virtqueue buffers, the host sets the
+For notifying the driver of virtqueue buffers, the device sets the
bit in the guest-provided indicator area at the corresponding offset.
The guest-provided summary indicator is also set. An adapter I/O
interrupt for the corresponding interruption subclass is generated.
@@ -2126,7 +2126,7 @@ host->guest notification will always be done via classic I/O interrupts.
\subsubsection{Guest->Host Notification}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
-For notifying the host of virtqueue buffers, the guest
+For notifying the device of virtqueue buffers, the driver
unfortunately can't use a channel command (the asynchronous
characteristics of channel I/O interact badly with the host block
I/O backend). Instead, it uses a diagnose 0x500 call with subcode
@@ -2163,7 +2163,7 @@ used.
\subsubsection{Resetting Devices}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices}
-In order to reset a device, a guest may send the
+In order to reset a device, a driver may send the
CCW_CMD_VDEV_RESET command.
@@ -2236,20 +2236,20 @@ features.
VIRTIO_NET_F_CSUM (0) Device handles packets with partial checksum
- VIRTIO_NET_F_GUEST_CSUM (1) Guest handles packets with partial checksum
+ VIRTIO_NET_F_GUEST_CSUM (1) Driver handles packets with partial checksum
VIRTIO_NET_F_CTRL_GUEST_OFFLOADS (2) Control channel offloads
reconfiguration support.
VIRTIO_NET_F_MAC (5) Device has given MAC address.
- VIRTIO_NET_F_GUEST_TSO4 (7) Guest can receive TSOv4.
+ VIRTIO_NET_F_GUEST_TSO4 (7) Driver can receive TSOv4.
- VIRTIO_NET_F_GUEST_TSO6 (8) Guest can receive TSOv6.
+ VIRTIO_NET_F_GUEST_TSO6 (8) Driver can receive TSOv6.
- VIRTIO_NET_F_GUEST_ECN (9) Guest can receive TSO with ECN.
+ VIRTIO_NET_F_GUEST_ECN (9) Driver can receive TSO with ECN.
- VIRTIO_NET_F_GUEST_UFO (10) Guest can receive UFO.
+ VIRTIO_NET_F_GUEST_UFO (10) Driver can receive UFO.
VIRTIO_NET_F_HOST_TSO4 (11) Device can receive TSOv4.
@@ -2259,7 +2259,7 @@ features.
VIRTIO_NET_F_HOST_UFO (14) Device can receive UFO.
- VIRTIO_NET_F_MRG_RXBUF (15) Guest can merge receive buffers.
+ VIRTIO_NET_F_MRG_RXBUF (15) Driver can merge receive buffers.
VIRTIO_NET_F_STATUS (16) Configuration status field is
available.
@@ -2270,7 +2270,7 @@ features.
VIRTIO_NET_F_CTRL_VLAN (19) Control channel VLAN filtering.
- VIRTIO_NET_F_GUEST_ANNOUNCE(21) Guest can send gratuitous
+ VIRTIO_NET_F_GUEST_ANNOUNCE(21) Driver can send gratuitous
packets.
\subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
@@ -2311,7 +2311,7 @@ native endian of the guest rather than (necessarily) little-endian.
2. If the VIRTIO_NET_F_MAC feature bit is set, the configuration
space “mac” entry indicates the “physical” address of the the
network card, otherwise a private MAC address should be
- assigned. All guests are expected to negotiate this feature if
+ assigned. All drivers are expected to negotiate this feature if
it is set.
3. If the VIRTIO_NET_F_CTRL_VQ feature bit is negotiated,
@@ -2474,7 +2474,7 @@ fully populated as possible: if it runs out, network performance
will suffer.
If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6 or
-VIRTIO_NET_F_GUEST_UFO features are used, the Guest will need to
+VIRTIO_NET_F_GUEST_UFO features are used, the Driver will need to
accept packets of up to 65550 bytes long (the maximum size of a
TCP or UDP packet, plus the 14 byte ethernet header), otherwise
1514. bytes. So unless VIRTIO_NET_F_MRG_RXBUF is negotiated, every
@@ -2618,7 +2618,7 @@ native endian of the guest rather than (necessarily) little-endian.
\paragraph{Gratuitous Packet Sending}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Gratuitous Packet Sending}
If the driver negotiates the VIRTIO_NET_F_GUEST_ANNOUNCE (depends
-on VIRTIO_NET_F_CTRL_VQ), it can ask the guest to send gratuitous
+on VIRTIO_NET_F_CTRL_VQ), it can ask the driver to send gratuitous
packets; this is usually done after the guest has been physically
migrated, and needs to announce its presence on the new network
links. (As hypervisor does not have the knowledge of guest
@@ -2630,7 +2630,7 @@ the guest in this way).
#define VIRTIO_NET_CTRL_ANNOUNCE_ACK 0
\end{lstlisting}
-The Guest needs to check VIRTIO_NET_S_ANNOUNCE bit in status
+The Driver needs to check VIRTIO_NET_S_ANNOUNCE bit in status
field when it notices the changes of device configuration. The
command VIRTIO_NET_CTRL_ANNOUNCE_ACK is used to indicate that
driver has recevied the notification and device would clear the
@@ -2717,7 +2717,7 @@ device except where noted.
alignment.
\subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
- VIRTIO_BLK_F_BARRIER (0) Host supports request barriers.
+ VIRTIO_BLK_F_BARRIER (0) Device supports request barriers.
VIRTIO_BLK_F_SCSI (7) Device supports scsi packet commands.
@@ -2799,7 +2799,7 @@ negotiating VIRTIO_BLK_F_FLUSH: the cache will be in writeback mode
after reset if and only if VIRTIO_BLK_F_FLUSH is negotiated.
Some older legacy devices did not operate in writethrough mode even
-after a guest announced lack of support for VIRTIO_BLK_F_FLUSH.
+after a driver announced lack of support for VIRTIO_BLK_F_FLUSH.
\subsection{Device Operation}\label{sec:Device Types / Block Device / Device Operation}
@@ -2835,8 +2835,8 @@ the read or write is to occur. This field is unused and set to 0
for scsi packet commands and for flush commands.
The final status byte is written by the device: either
-VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for host or guest
-error or VIRTIO_BLK_S_UNSUPP for a request unsupported by host:
+VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for device or driver
+error or VIRTIO_BLK_S_UNSUPP for a request unsupported by device:
\begin{lstlisting}
#define VIRTIO_BLK_S_OK 0
@@ -2941,9 +2941,9 @@ of input and output virtqueues. Moreover, a device has a pair of
control IO virtqueues. The control virtqueues are used to
communicate information between the device and the driver about
ports being opened and closed on either side of the connection,
-indication from the host about whether a particular port is a
+indication from the device about whether a particular port is a
console port, adding new ports, port hot-plug/unplug, etc., and
-indication from the guest about whether a port or a device was
+indication from the driver about whether a port or a device was
successfully added, port open/close, etc.. For data IO, one or
more empty buffers are placed in the receive queue for incoming
data and outgoing characters are placed in the transmit queue.
@@ -2999,11 +2999,11 @@ native endian of the guest rather than (necessarily) little-endian.
case, the control virtqueues are enabled and according to the
max_nr_ports configuration-space value, the appropriate number
of virtqueues are created. A control message indicating the
- driver is ready is sent to the host. The host can then send
+ driver is ready is sent to the device. The device can then send
control messages for adding new ports to the device. After
creating and initializing each port, a
- VIRTIO_CONSOLE_PORT_READY control message is sent to the host
- for that port so the host can let us know of any additional
+ VIRTIO_CONSOLE_PORT_READY control message is sent to the device
+ for that port so the device can let us know of any additional
configuration options set for that port.
3. The receiveq for each port is populated with one or more
@@ -3031,14 +3031,14 @@ when a port is closed or hot-unplugged.
be read from the configuration fields.
4. If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT
- feature, active ports are announced by the host using the
+ feature, active ports are announced by the device using the
VIRTIO_CONSOLE_PORT_ADD control message. The same message is
used for port hot-plug as well.
-5. If the host specified a port `name', a sysfs attribute is
+5. If the device specified a port `name', a sysfs attribute is
created with the name filled in, so that udev rules can be
written that can create a symlink from the port's name to the
- char device for port discovery by applications in the guest.
+ char device for port discovery by applications in the driver.
6. Changes to ports' state are effected by control messages.
Appropriate action is taken on the port indicated in the
@@ -3099,7 +3099,7 @@ by random data by the device.
The virtio memory balloon device is a primitive device for
managing guest memory: the device asks for a certain amount of
-memory, and the guest supplies it (or withdraws it, if the device
+memory, and the driver supplies it (or withdraws it, if the device
has more than it asks for). This allows the guest to adapt to
changes in allowance of underlying physical memory. If the
feature is negotiated, the device can also be used to communicate
@@ -3144,7 +3144,7 @@ that legacy device fields are guest endian.
(a) Identify the stats virtqueue.
(b) Add one empty buffer to the stats virtqueue and notify the
- host.
+ device.
Device operation begins immediately.
@@ -3297,7 +3297,7 @@ targets that receive and process the requests.
\subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout}
All fields of this configuration are always available. sense_size
- and cdb_size are writable by the guest.
+ and cdb_size are writable by the driver.
\begin{lstlisting}
struct virtio_scsi_config {
@@ -3322,10 +3322,10 @@ targets that receive and process the requests.
command. A bidirectional command can include seg_max input
segments and seg_max output segments.
- max_sectors is a hint to the guest about the maximum transfer
+ max_sectors is a hint to the driver about the maximum transfer
size it should use.
- cmd_per_lun is a hint to the guest about the maximum number of
+ cmd_per_lun is a hint to the driver about the maximum number of
linked commands it should send to one LUN. The actual value
to be used is the minimum of cmd_per_lun and the virtqueue
size.
@@ -3481,7 +3481,7 @@ following:
(severed link).
VIRTIO_SCSI_S_TARGET_FAILURE if the target is suffering a
- failure and the guest should not retry on other paths.
+ failure and the driver should not retry on other paths.
VIRTIO_SCSI_S_NEXUS_FAILURE if the nexus is suffering a failure
but retrying on other paths might yield a different result.
@@ -3489,7 +3489,7 @@ following:
VIRTIO_SCSI_S_BUSY if the request failed but retrying on the
same path should work.
- VIRTIO_SCSI_S_FAILURE for other host or guest error. In
+ VIRTIO_SCSI_S_FAILURE for other host or driver error. In
particular, if neither dataout nor datain is empty, and the
VIRTIO_SCSI_F_INOUT feature has not been negotiated, the
request will be immediately returned with a response equal to
@@ -3741,8 +3741,8 @@ contents of the event field. The following events are defined:
should ask the initiator to rescan the target, in order to
detect the case when an entire target has appeared or
disappeared. These two events will never be reported unless the
- VIRTIO_SCSI_F_HOTPLUG feature was negotiated between the host
- and the guest.
+ VIRTIO_SCSI_F_HOTPLUG feature was negotiated between the device
+ and the driver.
Events will also be reported via sense codes (this obviously
does not apply to newly appeared buses or targets, since the
@@ -3821,7 +3821,7 @@ Currently there are four device-independent feature bits defined:
and the avail_event fields. If set, it indicates that the
device should ignore the flags field in the available ring
structure. Instead, the used_event field in this structure is
- used by guest to suppress device interrupts. Further, the
+ used by driver to suppress device interrupts. Further, the
driver should ignore the flags field in the used ring
structure. Instead, the avail_event field in this structure is
used by the device to suppress notifications. If unset, the
@@ -3910,7 +3910,7 @@ reducing interrupt sharing between devices and queues within the
device, and handling interrupts from multiple CPUs. However, some
systems impose a limit (which might be as low as 256) on the
total number of MSI-X vectors that can be allocated to all
-devices. Devices and/or device drivers should take this into
+devices. Devices and/or drivers should take this into
account, limiting the number of vectors used unless the device is
expected to cause a high volume of interrupts. Devices can
control the number of vectors used by limiting the MSI-X Table
diff --git a/introduction.tex b/introduction.tex
index 241caee..60846b9 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -14,7 +14,7 @@ inter-guest communication) requires copying.
Efficient: Virtio devices consist of rings of descriptors
for input and output, which are neatly separated to avoid cache
- effects from both guest and device writing to the same cache
+ effects from both driver and device writing to the same cache
lines.
Standard: Virtio makes no assumptions about the environment in which
diff --git a/virtio-ring.h b/virtio-ring.h
index 7506a97..6d1e2dd 100644
--- a/virtio-ring.h
+++ b/virtio-ring.h
@@ -41,11 +41,11 @@
/* This means the buffer contains a list of buffer descriptors. */
#define VRING_DESC_F_INDIRECT 4
-/* The Host uses this in used->flags to advise the Guest: don't kick me
+/* The device uses this in used->flags to advise the driver: don't kick me
* when you add a buffer. It's unreliable, so it's simply an
- * optimization. Guest will still kick if it's out of buffers. */
+ * optimization. */
#define VRING_USED_F_NO_NOTIFY 1
-/* The Guest uses this in avail->flags to advise the Host: don't
+/* The driver uses this in avail->flags to advise the device: don't
* interrupt me when you consume a buffer. It's unreliable, so it's
* simply an optimization. */
#define VRING_AVAIL_F_NO_INTERRUPT 1