summaryrefslogtreecommitdiff
path: root/virtio-v1.0-wd01-part1-specification.txt
diff options
context:
space:
mode:
authorcornelia.huck <cornelia.huck@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2013-11-05 17:47:51 +0000
committercornelia.huck <cornelia.huck@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2013-11-05 17:47:51 +0000
commit1f0f785a64c139dad63ecb00336a6a953f32732d (patch)
tree7d82a91fcc53f1b4b03dd648123aec2e3032493e /virtio-v1.0-wd01-part1-specification.txt
parent55dc7138aca24a83722f0e950631e9f2ee807cb1 (diff)
virtio-ccw: introduce revisions
Provide a new ccw that allows devices and drivers to operate on selected revision levels. VIRTIO-42 Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@86 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652
Diffstat (limited to 'virtio-v1.0-wd01-part1-specification.txt')
-rw-r--r--virtio-v1.0-wd01-part1-specification.txt93
1 files changed, 83 insertions, 10 deletions
diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index c2052ec..33ee771 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -1766,6 +1766,7 @@ virtio:
#define CCW_CMD_WRITE_CONF 0x21
#define CCW_CMD_WRITE_STATUS 0x31
#define CCW_CMD_READ_VQ_CONF 0x32
+#define CCW_CMD_SET_VIRTIO_REV 0x83
The virtio-ccw device acts like a normal channel device, as specified
in [S390 PoP] and [S390 Common I/O]. In particular:
@@ -1789,7 +1790,79 @@ in [S390 PoP] and [S390 Common I/O]. In particular:
virtio-ccw uses several channel commands to set up a device.
-2.3.3.2.1. Configuring a Virtqueue
+2.3.3.2.1. Setting the Virtio Revision
+--------------------------------------
+
+CCW_CMD_SET_VIRTIO_REV is issued by the driver to set the revision of
+the virtio-ccw transport it intends to drive the device with. It uses the
+following communication structure:
+
+struct virtio_rev_info {
+ __u16 revision;
+ __u16 length;
+ __u8 data[];
+};
+
+revision contains the desired revision id, length the length of the
+data portion and data revision-dependent additional desired options.
+
+The following values are supported:
+
+------------------------------------------------------------------
+| revision | length | data | remarks |
+|----------|--------|-----------|--------------------------------|
+| 0 | 0 | <empty> | legacy interface; transitional |
+| | | | devices only |
+|----------|--------|-----------|--------------------------------|
+| 1 | 0 | <empty> | Virtio 1.0 |
+|----------|--------|-----------|--------------------------------|
+| 2-n | | | reserved for later revisions |
+------------------------------------------------------------------
+
+Note that a change in the virtio standard does not neccessarily
+correspond to a change in the virtio-ccw revision.
+
+A device must post a unit check with command reject for any revision
+it does not support. For any invalid combination of revision, length
+and data, it must post a unit check with command reject as well. A
+non-transitional device must reject revision id 0.
+
+A driver should start with trying to set the highest revision it
+supports and continue with lower revisions if it gets a command reject.
+
+A driver must not issue any other virtio-ccw specific channel commands
+prior to setting the revision.
+
+A device must answer with command reject to any virtio-ccw specific
+channel command that is not contained in the revision selected by the
+driver.
+
+After a revision has been successfully selected by the driver, it
+must not attempt to select a different revision. A device must answer
+to any such attempt with a command reject.
+
+A device must treat the revision as unset from the time the associated
+subchannel has been enabled until a revision has been successfully set
+by the driver. This implies that revisions are not persistent across
+disabling and enabling of the associated subchannel.
+
+2.3.3.2.1.1. Legacy Interfaces: A Note on Setting the Virtio Revision
+---------------------------------------------------------------------
+
+A legacy device will not support the CCW_CMD_SET_VIRTIO_REV and answer
+with a command reject. A non-transitional driver must stop trying to
+operate this device in that case. A transitional driver must operate
+the device as if it had been able to set revision 0.
+
+A legacy driver will not issue the CCW_CMD_SET_VIRTIO_REV prior to
+issueing other virtio-ccw specific channel commands. A non-transitional
+device therefore must answer any such attempts with a command reject.
+A transitional device must assume in this case that the driver is a
+legacy driver and continue as if the driver selected revision 0. This
+implies that the device must reject any command not valid for revision
+0, including a subsequent CCW_CMD_SET_VIRTIO_REV.
+
+2.3.3.2.2. Configuring a Virtqueue
----------------------------------
CCW_CMD_READ_VQ_CONF is issued by the guest to obtain information
@@ -1837,7 +1910,7 @@ struct vq_info_block_legacy {
queue contains the guest address for queue index, num the number of buffers
and align the alignment.
-100.3.3.2.1. Virtqueue Layout
+100.3.3.2.2. Virtqueue Layout
------------------------------
The virtqueue is physically contiguous, with padded added to make the
@@ -1857,14 +1930,14 @@ The calculation for total size is as follows:
+ ALIGN(sizeof(u16)*3 + sizeof(struct vring_used_elem)*num);
}
-2.3.3.2.2. Communicating Status Information
+2.3.3.2.3. Communicating Status Information
-------------------------------------------
The guest can change the status of a device via the
CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status
value.
-2.3.3.2.3. Handling Device Features
+2.3.3.2.4. Handling Device Features
-----------------------------------
Feature bits are arranged in an array of 32 bit values, making
@@ -1891,7 +1964,7 @@ For communicating its device features to the host, the guest may
use the CCW_CMD_WRITE_FEAT command, denoting a features/index
combination.
-2.3.3.2.4. Device Configuration
+2.3.3.2.5. Device Configuration
-------------------------------
The device's configuration space is located in host memory. It is
@@ -1909,7 +1982,7 @@ In both cases, the complete configuration space is transmitted. This
allows the guest to compare the new configuration space with the old
version, and keep a generation count internally whenever it changes.
-2.3.3.2.5. Setting Up Indicators
+2.3.3.2.6. Setting Up Indicators
--------------------------------
In order to set up the indicator bits for host->guest notification,
@@ -1923,7 +1996,7 @@ traditional I/O interrupts is provided, regardless of whether
traditional or adapter I/O interrupts are used for virtqueue
notifications.
-2.3.3.2.5.1. Setting Up Classic Queue Indicators
+2.3.3.2.6.1. Setting Up Classic Queue Indicators
------------------------------------------------
Indicators for notification via classic I/O interrupts are contained
@@ -1938,7 +2011,7 @@ If the driver has already set up two-staged queue indicators via the
CCW_CMD_SET_IND_ADAPTER command, the device MUST post a unit check
with command reject to any subsequent CCW_CMD_SET_IND command.
-2.3.3.2.5.2. Setting Up Configuration Change Indicators
+2.3.3.2.6.2. Setting Up Configuration Change Indicators
-------------------------------------------------------
Indicators for configuration change host->guest notification are
@@ -1949,7 +2022,7 @@ configuration change host->guest notification, the driver issues the
CCW_CMD_SET_CONF_IND command, pointing to a location containing the
guest address of the indicators in a 64 bit value.
-2.3.3.2.5.3. Setting Up Two-Stage Queue Indicators
+2.3.3.2.6.3. Setting Up Two-Stage Queue Indicators
--------------------------------------------------
Indicators for notification via adapter I/O interrupts consist of
@@ -1983,7 +2056,7 @@ If the driver has already set up classic queue indicators via the
CCW_CMD_SET_IND command, the device MUST post a unit check with
command reject to any subsequent CCW_CMD_SET_IND_ADAPTER command.
-2.3.3.2.5.4. Legacy Interfaces: A Note on Setting Up Indicators
+2.3.3.2.6.4. Legacy Interfaces: A Note on Setting Up Indicators
---------------------------------------------------------------
Legacy devices will only support classic queue indicators; they will