diff options
| -rw-r--r-- | virtio-v1.0-wd01-part1-specification.txt | 93 |
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 |