[PATCH 1/3] 2.3.3 Add virtio-ccw spec.

[Cornelia Huck <cornelia.huck@de.ibm.com>]

Ported from draft commit cdbad68fd1ccb8b99b3853836e2b38e0bf74361b.

Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>
---
 virtio-v1.0-wd01-part1-specification.txt |  172 ++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index 0531125..f7543a1 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -1063,6 +1063,178 @@ InterruptACK register.
 This is indicated by bit 1 in the InterruptStatus register, as
 documented in the register description.
 
+2.3.3. Virtio over channel I/O
+------------------------------
+
+S/390 based virtual machines support neither PCI nor MMIO, so a
+different transport is needed there.
+
+The old s390-virtio mechanism used a special page mapped above
+the guest's memory and several diagnose calls (hypercalls); it
+does have some drawbacks, however, like a rather limited number
+of devices and very restricted hotplug support. Moreover, device
+discovery and operation differ from other environments on the
+S/390 platform.
+
+virtio-ccw uses the standard channel I/O based mechanism used for
+the majority of devices on S/390. A virtual channel device with a
+special control unit type acts as proxy to the virtio device
+(similar to the way virtio-pci uses a PCI device) and
+configuration and operation of the virtio device is accomplished
+(mostly) via channel commands. This means virtio devices are
+discoverable via standard operating system algorithms, and adding
+virtio support is mainly a question of supporting a new control
+unit type.
+
+2.3.3.1. Basic Concepts
+-----------------------
+
+As a proxy device, virtio-ccw uses a channel-attached I/O control
+unit with a special control unit type (0x3832) and a control unit
+model corresponding to the attached virtio device's subsystem
+device ID, accessed via a virtual I/O subchannel and a virtual
+channel path of type 0x32. This proxy device is discoverable via
+normal channel subsystem device discovery (usually a STORE
+SUBCHANNEL loop) and answers to the basic channel commands, most
+importantly SENSE ID.
+
+In addition to the basic channel commands, virtio-ccw defines a
+set of channel commands related to configuration and operation of
+virtio:
+
+#define CCW_CMD_SET_VQ 0x13
+#define CCW_CMD_VDEV_RESET 0x33
+#define CCW_CMD_SET_IND 0x43
+#define CCW_CMD_READ_FEAT 0x12
+#define CCW_CMD_WRITE_FEAT 0x11
+#define CCW_CMD_READ_CONF 0x22
+#define CCW_CMD_WRITE_CONF 0x21
+#define CCW_CMD_WRITE_STATUS 0x31
+#define CCW_CMD_READ_VQ_CONF 0x32
+
+2.3.3.2. Device Initialization
+------------------------------
+
+virtio-ccw uses several channel commands to set up a device.
+
+2.3.3.2.1. Configuring a Virtqueue
+----------------------------------
+
+CCW_CMD_READ_VQ_CONF is issued by the guest to obtain information
+about a queue. It uses the following structure for communicating:
+
+struct vq_config_block {
+	__u16 index;
+	__u16 max_num;
+} __attribute__ ((packed));
+
+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
+structure is
+
+struct vq_info_block {
+	__u64 queue;
+	__u32 align;
+	__u16 index;
+	__u16 num;
+} __attribute__ ((packed));
+
+queue contains the guest address for queue index. The actual
+number of allocated buffers is transmitted in num and their
+alignment in align.
+
+2.3.3.2.2. 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
+-----------------------------------
+
+Feature bits are arranged in an array of 32 bit values, making
+for a total of 8192 feature bits.
+
+The CCW commands dealing with features use the following
+communication block:
+
+struct virtio_feature_desc {
+	__u32 features;
+	__u8 index;
+} __attribute__ ((packed));
+
+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
+to features.
+
+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
+-------------------------------
+
+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 write to.
+
+For changing configuration information, the guest may use
+CCW_CMD_WRITE_CONF, specifying the guest memory for the host to
+read from.
+
+In both cases, the complete configuration space is transmitted.
+
+2.3.3.2.5. Setting Up Indicators
+--------------------------------
+
+To communicate the location of the indicator bits for host->guest
+notification, the guest uses the CCW_CMD_SET_IND command which
+sends the guest address of the indicators in a 64 bit value.
+
+2.3.3.3. Device Operation
+-------------------------
+
+2.3.3.3.1. Host->Guest Notification
+-----------------------------------
+
+For notifying the guest of virtqueue buffers, the host sets the
+corresponding bit in the guest-provided indicators. If an
+interrupt is not already pending for the subchannel, the host
+generates an unsolicited I/O interrupt.
+
+2.3.3.3.2. Guest->Host Notification
+-----------------------------------
+
+For notifying the host of virtqueue buffers, the guest
+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
+3 specifying the queue.
+
+2.3.3.3.3. Early printk for Virtio Consoles
+-------------------------------------------
+
+For the early printk mechanism, diagnose 0x500 with subcode 0 is
+used.
+
+2.3.3.3.4. Resetting Devices
+----------------------------
+
+In order to reset a device, a guest may send the
+CCW_CMD_VDEV_RESET command.
+
+
 2.4. Device Types
 ================
 
-- 
1.7.9.5