[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH 3/3] Specify requirements more clearly.
The spec language is mostly written with a view to driver authors, and
contains assumptions, eg:
The Device Status field is updated by the OS and driver...
But the spec is for both device and driver authors. It should specify
exactly what is to be done, and by whom, eg:
The driver MUST update the Device Status field...
1) Change from passive to active (eg "foo must be reset" => "driver
must reset foo").
2) Upcase SHOULD, MUST etc. There are probably more that I missed.
3) Make the following requirements explicit:
- The driver must not clear device status bits.
- Make bad on looped descriptors explicit.
- Driver must not set VRING_DESC_F_INDIRECT unless negotiated feature.
- Available/used ring sections rewritten to be more explicit that driver
must not set VRING_AVAIL_F_NO_INTERRUPT.
- Following device initialization sequence is a MUST.
- Driver must not continue initialization if it sets FAILED.
- "memory barriers" are now a MUST, though the weasel-word "suitable"
was added.
- Driver MUST notify device.
4) Misc changes:
- Use "device offers" / "driver accepts" language for feature negotiation.
- config space always uses little-endian, remove 'generally'.
- "descriptor chain" term used everywhere.
- Extraneous "+" deleted.
- Remove "Unless explicitly specified otherwise" from PCI spec endian
sentence.
- Refer to notify_off_multiplier in queue_notify_off discussion.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
---
virtio-v1.0-wd01-part1-specification.txt | 321 ++++++++++++++++++-------------
1 file changed, 182 insertions(+), 139 deletions(-)
diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index 52adf24..4e479c8 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -111,10 +111,11 @@ To reinforce this the examples use typenames like "le16" instead of "uint16_t".
2.1.1. Device Status Field
-------------------------
-The Device Status field is updated by the OS and 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.
+The driver MUST update the Device Status field in the order below 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. The driver MUST NOT
+clear a device status bit.
This field is 0 upon reset, otherwise at least one bit should be set:
@@ -135,24 +136,31 @@ This field is 0 upon reset, otherwise at least one bit should be set:
FAILED (128) Indicates that something went wrong in the guest OS,
and it has given up on the device. This could be an internal
error, or the driver didn't like the device for some reason, or
- even a fatal error during device operation. The device must be
- reset before attempting to re-initialize.
+ even a fatal error during device operation. The driver MUST
+ reset the device before attempting to re-initialize.
2.1.2. Feature Bits
------------------
-Each virtio device lists all the features it understands. During
+Each virtio device offers all the features it understands. During
device initialization, the driver reads this and tells the device the
-subset that it understands. The only way to renegotiate is to reset
+subset that it accepts. 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 drivers will not write that
-feature bit back to the device and it can go into backwards
+feature bit back to the device and it SHOULD go into backwards
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).
+and SHOULD go into backwards compatibility mode (or, for poor
+implementations it MAY set the FAILED Device Status bit).
+
+The driver MUST NOT accept a feature which the device did not offer,
+and MUST NOT accept a feature which requires another feature which was
+not accepted.
+
+The device MUST NOT offer a feature which requires another feature
+which was not offered.
Feature bits are allocated as follows:
@@ -168,8 +176,9 @@ 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 driver can check
-before accessing that part of the configuration space.
+indicated by offering a feature bit, so the driver MUST check that the
+feature is offered before accessing that part of the configuration
+space.
2.1.2.1 Legacy Interface: A Note on transitions from earlier drafts
--------------------------------------
@@ -224,7 +233,7 @@ Interface' in the section title.
-------------------------
Configuration space is generally used for rarely-changing or
-initialization-time parameters. Drivers must not assume reads from
+initialization-time parameters. Drivers MUST NOT assume reads from
fields greater than 32 bits wide are atomic, nor or reads from
multiple fields.
@@ -233,7 +242,7 @@ space, which must change whenever there is a possibility that two
accesses to the configuration space can see different versions of that
space.
-Thus drivers should read configuration space fields like so:
+Thus drivers SHOULD read configuration space fields like so:
u32 before, after;
do {
@@ -242,21 +251,21 @@ Thus drivers should read configuration space fields like so:
after = get_config_generation(device);
} while (after != before);
-Note that configuration space generally uses the little-endian format
+Note that configuration space uses the little-endian format
for multi-byte fields.
Note that future versions of this specification will likely
extend the configuration space for devices by adding extra fields
at the tail end of some structures in configuration space.
-To allow forward compatibility with such extensions, drivers must
-not limit structure size and configuration space size. Instead,
-drivers should only check that configuration space is *large enough* to
+To allow forward compatibility with such extensions, drivers MUST
+NOT limit structure size and configuration space size. Instead,
+drivers SHOULD only check that configuration space is *large enough* to
contain the fields required for device operation.
For example, if the specification states that configuration
space 'includes a single 8-bit field' drivers should understand this to mean that
-the configuration space can also include an arbitrary amount of
+the configuration space might also include an arbitrary amount of
tail padding, and accept any configuration space size equal to or
greater than the specified 8-bit size.
@@ -309,8 +318,8 @@ virtqueue are summarized in the following table:
+------------+-----------------------------------------+
The Alignment column gives the miminum alignment: for each part
-of the virtqueue, the physical address of the first byte of it
-must be a multiple of the specified alignment value.
+of the virtqueue, the physical address of the first byte
+MUST be a multiple of the specified alignment value.
The Size column gives the total number of bytes required for each
part of the virtqueue.
@@ -325,7 +334,7 @@ When the driver wants to send a buffer to the device, it fills in
a slot in the descriptor table (or chains several together), and
writes the descriptor index into the available ring. It then
notifies the device. When the device has finished a buffer, it
-writes the descriptor into the used ring, and sends an interrupt.
+writes the descriptor index into the used ring, and sends an interrupt.
2.1.4.1. Legacy Interfaces: A Note on Virtqueue Layout
@@ -378,7 +387,8 @@ It is assumed that the host is already aware of the guest endian.
2.1.4.2. Message Framing
-----------------------
-The message framing (the particular layout of descriptors) is
+The device MUST NOT make assumptions about the particular arrangement
+of descriptors: the message framing is
independent of the contents of the buffers. For example, a network
transmit buffer consists of a 12 byte header followed by the network
packet. This could be most simply placed in the descriptor table as a
@@ -421,7 +431,8 @@ device type. Most common is to begin the data with a header
(containing little-endian fields) for the device to read, and postfix
it with a status tailer for the device to write.
-No descriptor chain may be more than 2^32 bytes long in total.
+Drivers MUST NOT add a descriptor chain over than 2^32 bytes long in total;
+this implies that loops in the descriptor chain are forbidden!
struct vring_desc {
/* Address (guest-physical). */
@@ -448,14 +459,18 @@ for this virtqueue.
------------------------------
Some devices benefit by concurrently dispatching a large number
-of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature can be
-used to allow this (see "2.6. Reserved Feature Bits"). To increase
-ring capacity it is possible to store a table of indirect
+of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature allows this (see "2.6. Reserved Feature Bits"). To increase
+ring capacity the driver can store a table of indirect
descriptors anywhere in memory, and insert a descriptor in main
virtqueue (with flags&VRING_DESC_F_INDIRECT on) that refers to memory buffer
containing this indirect descriptor table; fields addr and len
refer to the indirect table address and length in bytes,
-respectively. The indirect table layout structure looks like this
+respectively.
+
+The driver MUST NOT set the VRING_DESC_F_INDIRECT flag unless the
+VIRTIO_RING_F_INDIRECT_DESC feature was negotiated.
+
+The indirect table layout structure looks like this
(len is the length of the descriptor that refers to this table,
which is a variable, so this code won't compile):
@@ -470,29 +485,13 @@ chained by next field. An indirect descriptor without next field
(with flags&VRING_DESC_F_NEXT off) signals the end of the descriptor.
An
indirect descriptor can not refer to another indirect descriptor
-table (flags&VRING_DESC_F_INDIRECT must be off). A single indirect descriptor
+table (flags&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor
table can include both read-only and write-only descriptors;
-write-only flag (flags&VRING_DESC_F_WRITE) in the descriptor that refers to it
-is ignored.
+the device MUST ignore the write-only flag (flags&VRING_DESC_F_WRITE) in the descriptor that refers to it.
2.1.4.4. The Virtqueue Available Ring
------------------------------------
-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 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
-the device is controlled by the VIRTIO_RING_F_EVENT_IDX feature bit
-(see "2.6. Reserved Feature Bits"). This interrupt suppression is
-merely an optimization; it may not suppress interrupts entirely.
-
-The “idx” field indicates where we would put the next descriptor
-entry (modulo the queue size). This starts at 0, and increases.
-
struct vring_avail {
#define VRING_AVAIL_F_NO_INTERRUPT 1
le16 flags;
@@ -501,28 +500,40 @@ entry (modulo the queue size). This starts at 0, and increases.
le16 used_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
};
+The available ring refers to what descriptor chains the driver is offering the
+device: each ring entry refers to the head of a descriptor chain. It is only
+written by the driver and read by the device.
+
+The “idx” field indicates where we would put the next descriptor
+entry in the ring (modulo the queue size). This starts at 0, and increases.
+
+If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the
+“flags” field offers a crude interrupt control mechanism. The driver
+MUST set this to 0 or 1: 1 indicates that the device SHOULD NOT send
+an interrupt when it consumes a descriptor chain from the available
+ring. The device MUST ignore the used_event value in this case.
+
+Otherwise, if the VIRTIO_RING_F_EVENT_IDX feature bit is negotiated,
+the driver MUST set the "flags" field to 0, and use the “used_event”
+field in the used ring instead. 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 driver MUST handle spurious interrupts: either form of interrupt
+suppression is merely an optimization; it may not suppress interrupts
+entirely.
+
2.1.4.5. The Virtqueue Used Ring
-------------------------------
-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 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 driver through the
-VIRTIO_RING_F_EVENT_IDX feature bit (see "2.6. Reserved
-Feature Bits").[7]
-
-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 driver earlier), and the total
-of bytes written into the buffer. The latter is extremely useful
-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.
+ struct vring_used {
+ #define VRING_USED_F_NO_NOTIFY 1
+ le16 flags;
+ le16 idx;
+ struct vring_used_elem ring[ /* Queue Size */];
+ le16 avail_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
+ };
/* le32 is used here for ids for padding reasons. */
struct vring_used_elem {
@@ -532,13 +543,35 @@ the buffer to ensure no data leakage occurs.
le32 len;
};
- struct vring_used {
- #define VRING_USED_F_NO_NOTIFY 1
- le16 flags;
- le16 idx;
- struct vring_used_elem ring[ /* Queue Size */];
- le16 avail_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
- };
+The used ring is where the device returns buffers once it is done with
+them: it is only written to by the device, and read by the driver.
+
+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
+of bytes written into the buffer. The latter is extremely useful
+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.
+
+If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the
+“flags” field offers a crude interrupt control mechanism. The driver
+MUST initialize this to 0, the device MUST set this to 0 or 1: 1
+indicates that the driver SHOULD NOT send an notification when it adds
+a descriptor chain to the available ring. The driver MUST ignore the
+used_event value in this case.
+
+Otherwise, if the VIRTIO_RING_F_EVENT_IDX feature bit is negotiated,
+the device MUST leave the "flags" field at 0, and use the
+“avail_event” field in the used ring instead. The device can ask the
+driver to delay notifications until an entry with an index specified
+by the “avail_event” field is written in the available ring (equivalently,
+until the idx field in the used ring will reach the value avail_event +
+1).
+
+The device MUST handle spurious notification: either form of
+notification suppression is merely an optimization; it may not
+suppress them entirely.
2.1.4.6. Helpers for Operating Virtqueues
----------------------------------------
@@ -561,36 +594,40 @@ how to communicate with the specific device.
2.2.1. Device Initialization
---------------------------
+The driver MUST follow this sequence to initialize a device:
+
1. Reset the device.
-2. The ACKNOWLEDGE status bit is set: we have noticed the device.
+2. Set the ACKNOWLEDGE status bit: we have noticed the device.
-3. The DRIVER status bit is set: we know how to drive the device.
+3. Set the DRIVER status bit: we know how to drive the device.
-4. Device feature bits are read, and the the subset of feature bits
- understood by the OS and driver is written to the device.
+4. Read device feature bits, and write the subset of feature bits
+ understood by the OS and driver to the device.
-5. The FEATURES_OK status bit is set.
+5. Set the FEATURES_OK status bit. The driver MUST not accept
+ new feature bits after this step.
-6. The status byte is re-read to ensure the FEATURES_OK bit is still
+6. Re-read the status byte to ensure the FEATURES_OK bit is still
set: otherwise, the device does not support our subset of features
and the device is unusable.
-7. Device-specific setup, including discovery of virtqueues for the
+7. Perform device-specific setup, including discovery of virtqueues for the
device, optional per-bus setup, reading and possibly writing the
device's virtio configuration space, and population of virtqueues.
-8. The DRIVER_OK status bit is set. At this point the device is
+8. Set the DRIVER_OK status bit. At this point the device is
"live".
-If any of these steps go irrecoverably wrong, the driver 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).
+device (it can reset the device later to restart if desired). The
+driver MUST not continue initialization in that case.
-The device must not consume buffers before DRIVER_OK, and the driver
-must not notify the device before it sets DRIVER_OK.
+The device MUST NOT consume buffers before DRIVER_OK, and the driver
+MUST NOT notify the device before it sets DRIVER_OK.
-Devices should support all valid combinations of features, but we know
+Devices SHOULD support all valid combinations of features, but we know
that implementations may well make assuptions that they will only be
used by fully-optimized drivers. The resetting of the FEATURES_OK flag
provides a semi-graceful failure mode for this case.
@@ -625,29 +662,29 @@ they are used.
2.2.2.1. Supplying Buffers to The Device
---------------------------------------
-Actual transfer of buffers from the guest OS to the device
-operates as follows:
+The driver offers buffers to one of the device's virtqueues as follows:
-1. Place the buffer(s) into free descriptor(s).
+1. The driver places the buffer into free descriptor(s) in the
+ descriptor table, chaining as necessary (see 2.1.4.3.).
-2. Place the id of the buffer in the next ring entry of the
- available ring.
+2. The driver places the index of the head of the descriptor chain
+ into the next ring entry of the available ring.
-3. The steps (1) and (2) may be performed repeatedly if batching
+3. Steps (1) and (2) may be performed repeatedly if batching
is possible.
-4. A memory barrier should be executed to ensure the device sees
+4. The driver MUST perform suitable a memory barrier to ensure the device sees
the updated descriptor table and available ring before the next
step.
-5. The available “idx” field should be increased by the number of
- entries added to the available ring.
+5. The available “idx” field is increased by the number of
+ descriptor chain heads added to the available ring.
-6. A memory barrier should be executed to ensure that we update
- the idx field before checking for notification suppression.
+6. The driver MUST perform a suitable memory barrier to ensure that it updates
+ the "idx" field before checking for notification suppression.
-7. If notifications are not suppressed, the device should be
- notified of the new buffers.
+7. If notifications are not suppressed, the driver MUST notify the device
+ of the new available buffers.
Note that the above code does not take precautions against the
available ring buffer wrapping around: this is not possible since
@@ -666,7 +703,8 @@ Here is a description of each stage in more detail.
A buffer consists of zero or more read-only physically-contiguous
elements followed by zero or more physically-contiguous
write-only elements (it must have at least one element). This
-algorithm maps it into the descriptor table:
+algorithm maps it into the descriptor table to form a descriptor
+chain:
for each buffer element, b:
@@ -694,7 +732,7 @@ free descriptors before beginning the mappings.
-------------------------------------
The head of the buffer we mapped is the first d in the algorithm
-above. A naive implementation would do the following (with the
+above (the descriptor chain head). A naive implementation would do the following (with the
appropriate conversion to-and-from little-endian assumed):
avail->ring[avail->idx % qsz] = head;
@@ -724,7 +762,7 @@ The index field always increments, and we let it wrap naturally at
The actual method of device notification is bus-specific, but generally
it can be expensive. So the device can suppress such notifications if it
-doesn't need them. We have to be careful to expose the new index
+doesn't need them. The driver has to be careful to expose the new index
value before checking if notifications are suppressed: it's OK to notify
gratuitously, but not to omit a required notification. So again,
we use a memory barrier here before reading the flags or the
@@ -822,11 +860,11 @@ Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through
0x103F inclusive is a virtio device[3].
The Subsystem Device ID indicates which virtio device is
-supported by the device. The Subsystem Vendor ID should reflect
+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 driver).
-All Drivers must match devices with any Revision ID, this
+All drivers MUST match devices with any Revision ID, this
is to allow devices to be versioned without breaking drivers.
2.3.1.1.1 Legacy Interfaces: A Note on PCI Device Discovery
@@ -846,7 +884,7 @@ To configure the device,
use I/O and/or memory regions and/or PCI configuration space of the PCI device.
These contain the virtio header registers, the notification register, the
ISR status register and device specific registers, as specified by Virtio
-+ Structure PCI Capabilities
+Structure PCI Capabilities.
There may be different widths of accesses to the I/O region; the
“natural” access method for each field must be
@@ -856,7 +894,7 @@ PCI Device Configuration Layout includes the common configuration,
ISR, notification and device specific configuration
structures.
-Unless explicitly specified otherwise, all multi-byte fields are little-endian.
+All multi-byte fields are little-endian.
2.3.1.2.1. Common configuration structure layout
-------------------------
@@ -886,87 +924,92 @@ struct virtio_pci_common_cfg {
device_feature_select
- Selects which Feature Bits does device_feature field refer to.
+ The driver uses this to select which Feature Bits the device_feature field shows.
Value 0x0 selects Feature Bits 0 to 31
Value 0x1 selects Feature Bits 32 to 63
- All other values cause reads from device_feature to return 0.
+ The device MUST present 0 on device_feature for any other value.
device_feature
- Used by device to report Feature Bits to Driver.
- device Feature Bits selected by device_feature_select.
+ The device uses this to report Feature Bits to the driver.
+ Device Feature Bits selected by device_feature_select.
driver_feature_select
- Selects which Feature Bits does driver_feature field refer to.
+ The driver uses this to select which Feature Bits the driver_feature field shows.
Value 0x0 selects Feature Bits 0 to 31
Value 0x1 selects Feature Bits 32 to 63
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.
+ return 0, writing 0 into driver_feature has no effect. The driver
+ MUST not write any other value into driver_feature (a corollary of
+ the rule that the driver can only write a subset of device features).
driver_feature
- Used by Driver to acknowledge Feature Bits to device.
+ The driver writes this to accept feature bits offered by the deevice.
Driver Feature Bits selected by driver_feature_select.
msix_config
- Configuration Vector for MSI-X.
+ The driver sets the Configuration Vector for MSI-X.
num_queues
- Specifies the maximum number of virtqueues supported by device.
+ The device specifies the maximum number of virtqueues supported here.
device_status
- Device Status field. Writing 0 into this field resets the
- device.
+ The driver writes the Device Status here. Writing 0 into this
+ field resets the device.
config_generation
- Configuration atomicity value. Changes every time the
+ Configuration atomicity value. The device changes this every time the
configuration noticeably changes. This means the device may
only change the value after a configuration read operation,
- but it must change if there is any risk of a device seeing an
+ but MUST change it if there is any risk of a driver seeing an
inconsistent configuration state.
queue_select
- Queue Select. Selects which virtqueue do other fields refer to.
+ Queue Select. The driver selects which virtqueue the following
+ fields refer to.
queue_size
Queue Size. On reset, specifies the maximum queue size supported by
the hypervisor. This can be modified by driver to reduce memory requirements.
- Set to 0 if this virtqueue is unused.
+ The device MUST set this to 0 if this virtqueue is unavailable.
queue_msix_vector
- Queue Vector for MSI-X.
+ The driver uses this to specify the Queue Vector for MSI-X.
queue_enable
- Used to selectively prevent device from executing requests from this virtqueue.
+ The driver uses this to selectively prevent the device from executing requests from this virtqueue.
1 - enabled; 0 - disabled
+ The driver MUST configure the other virtqueue fields before enabling
+ the virtqueue.
+
queue_notify_off
- Used to calculate the offset from start of Notification structure at
+ The driver reads this to calculate the offset from start of Notification structure at
which this virtqueue is located.
Note: this is *not* an offset in bytes. See notify_off_multiplier below.
queue_desc
- Physical address of Descriptor Table.
+ The driver writes the physical address of Descriptor Table here.
queue_avail
- Physical address of Available Ring.
+ The driver writes the physical address of Available Ring here.
queue_used
- Physical address of Used Ring.
+ The driver writes the physical address of Used Ring here.
2.3.1.2.2. ISR status structure layout
-------------------------
@@ -977,7 +1020,7 @@ ISR status structure includes a single 8-bit ISR status field.
Notification structure is always a multiple of 2 bytes in size.
It includes 2-byte Queue Notify fields for each virtqueue of
the device. Note that multiple virtqueues can use the same
-Queue Notify field, if necessary.
+Queue Notify field, if necessary: see notify_off_multiplier below.
2.3.1.2.4. Device specific structure
-------------------------
@@ -1140,14 +1183,14 @@ cfg_type
/* PCI configuration access */
#define VIRTIO_PCI_CAP_PCI_CFG 5
- Any other value - reserved for future use. Drivers must
+ Any other value - reserved for future use. Drivers MUST
ignore any vendor-specific capability structure which has
a reserved cfg_type value.
More than one capability can identify the same structure - this makes it
possible for the device to expose multiple interfaces to drivers. The order of
the capabilities in the capability list specifies the order of preference
- suggested by the device; drivers should use the first interface that they can
+ suggested by the device; drivers SHOULD use the first interface that they can
support. For example, on some hypervisors, notifications using IO accesses are
faster than memory accesses. In this case, hypervisor can expose two
capabilities with cfg_type set to VIRTIO_PCI_CAP_NOTIFY_CFG:
@@ -1162,7 +1205,7 @@ bar
The BAR is permitted to be either 32-bit or 64-bit, it can map Memory Space
or I/O Space.
- Any other value - reserved for future use. Drivers must
+ Any other value is reserved for future use. Drivers MUST
ignore any vendor-specific capability structure which has
a reserved bar value.
@@ -1173,7 +1216,7 @@ offset
length
indicates the length of the structure.
This size might include padding, or fields unused by the driver.
- Drivers are also recommended to only map part of configuration structure
+ Drivers SHOULD only map part of configuration structure
large enough for device operation.
For example, a future device might present a large structure size of several
MBytes.
@@ -1283,13 +1326,13 @@ or NO_VECTOR if unmapped. All queue and configuration change
events are unmapped by default.
Note that mapping an event to vector might require allocating
-internal device resources, and might fail. Devices report such
+internal device resources, and might fail. Devices MUST report such
failures by returning the NO_VECTOR value when the relevant
Vector field is read. After mapping an event to vector, the
-driver must verify success by reading the Vector field value: on
+driver MUST verify success by reading the Vector field value: on
success, the previously written value is returned, and on
failure, NO_VECTOR is returned. If a mapping failure is detected,
-the driver can retry mapping with fewervectors, or disable MSI-X.
+the driver can retry mapping with fewer vectors, or disable MSI-X.
2.3.1.3.1.2. Virtqueue Configuration
-----------------------------------
@@ -1299,13 +1342,13 @@ transport (for example, the simplest network device has two), the driver
needs to configure them as part of the device-specific
configuration.
-This is done as follows, for each virtqueue a device has:
+The driver does this as follows, for each virtqueue a device has:
1. Write the virtqueue index (first queue is 0) to the Queue
Select field.
-2. Read the virtqueue size from the Queue Size field, which is
- always a power of 2. This controls how big the virtqueue is
+2. Read the virtqueue size from the Queue Size field, which MUST
+ be a power of 2. This controls how big the virtqueue is
(see "2.1.4. Virtqueues"). If this field is 0, the virtqueue does not exist.
3. Optionally, select a smaller virtqueue size and write it in the Queue Size
--
1.8.3.2
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]