From patchwork Tue Aug 7 14:52:58 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Cornelia Huck X-Patchwork-Id: 1286191 Return-Path: X-Original-To: patchwork-kvm@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork2.kernel.org (Postfix) with ESMTP id C3E52DF280 for ; Tue, 7 Aug 2012 14:53:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755408Ab2HGOxi (ORCPT ); Tue, 7 Aug 2012 10:53:38 -0400 Received: from e06smtp13.uk.ibm.com ([195.75.94.109]:36954 "EHLO e06smtp13.uk.ibm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755373Ab2HGOxe (ORCPT ); Tue, 7 Aug 2012 10:53:34 -0400 Received: from /spool/local by e06smtp13.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Tue, 7 Aug 2012 15:53:33 +0100 Received: from d06nrmr1806.portsmouth.uk.ibm.com (9.149.39.193) by e06smtp13.uk.ibm.com (192.168.101.143) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Tue, 7 Aug 2012 15:53:05 +0100 Received: from d06av06.portsmouth.uk.ibm.com (d06av06.portsmouth.uk.ibm.com [9.149.37.217]) by d06nrmr1806.portsmouth.uk.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id q77Er4ue2691264; Tue, 7 Aug 2012 15:53:04 +0100 Received: from d06av06.portsmouth.uk.ibm.com (loopback [127.0.0.1]) by d06av06.portsmouth.uk.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id q77EqxK5021036; Tue, 7 Aug 2012 08:53:00 -0600 Received: from BR9GNB5Z.boeblingen.de.ibm.com (dyn-9-152-224-192.boeblingen.de.ibm.com [9.152.224.192]) by d06av06.portsmouth.uk.ibm.com (8.14.4/8.13.1/NCO v10.0 AVin) with ESMTP id q77EqxgK021005; Tue, 7 Aug 2012 08:52:59 -0600 From: Cornelia Huck To: KVM , linux-s390 , qemu-devel Cc: Avi Kivity , Marcelo Tosatti , Anthony Liguori , Rusty Russell , Christian Borntraeger , Carsten Otte , Alexander Graf , Heiko Carstens , Martin Schwidefsky , Sebastian Ott Subject: [PATCH] virtio-spec: Add virtio-ccw spec. Date: Tue, 7 Aug 2012 16:52:58 +0200 Message-Id: <1344351178-18972-2-git-send-email-cornelia.huck@de.ibm.com> X-Mailer: git-send-email 1.7.5.4 In-Reply-To: <1344351178-18972-1-git-send-email-cornelia.huck@de.ibm.com> References: <1344351178-18972-1-git-send-email-cornelia.huck@de.ibm.com> x-cbid: 12080714-2966-0000-0000-000004EF91D0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org Add specifications for the new s390 specific virtio-ccw transport. Signed-off-by: Cornelia Huck --- virtio-spec.lyx | 433 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 433 insertions(+), 0 deletions(-) diff --git a/virtio-spec.lyx b/virtio-spec.lyx index 7a073f4..5223380 100644 --- a/virtio-spec.lyx +++ b/virtio-spec.lyx @@ -57,6 +57,7 @@ \html_css_as_file 0 \html_be_strict false \author -608949062 "Rusty Russell,,," +\author -385801441 "Cornelia Huck" cornelia.huck@de.ibm.com \author 1531152142 "Paolo Bonzini,,," \end_header @@ -9350,6 +9351,438 @@ tatus register description is asserted. After the interrupt is handled, the driver must acknowledge it by writing a bit mask corresponding to the serviced interrupt to the InterruptACK register. +\change_inserted -385801441 1343732742 + +\end_layout + +\begin_layout Chapter* + +\change_inserted -385801441 1343732726 +Appendix Y: virtio-ccw +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +S/390 based virtual machines support neither PCI nor MMIO, so a different + transport is needed there. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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. +\end_layout + +\begin_layout Subsection* + +\change_inserted -385801441 1343732726 +Basic Concepts +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732817 +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 discorver +y (usually a STORE SUBCHANNEL loop) and answers to the basic channel commands, + most importantly SENSE ID. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +In addition to the basic channel commands, virtio-ccw defines a set of channel + commands related to configuration and operation of virtio: +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 +\begin_inset listings +inline false +status open + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_SET_VQ 0x13 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_VDEV_RESET 0x33 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_SET_IND 0x43 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_READ_FEAT 0x12 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_WRITE_FEAT 0x11 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_READ_CONF 0x22 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_WRITE_CONF 0x21 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_WRITE_STATUS 0x31 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +#define CCW_CMD_READ_VQ_CONF 0x32 +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection* + +\change_inserted -385801441 1343732726 +Device Initialization +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +virtio-ccw uses several channel commands to set up a device. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Configuring a Virtqueue +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +CCW_CMD_READ_VQ_CONF is issued by the guest to obtain information about + a queue. + It uses the following structure for communicating: +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 +\begin_inset listings +inline false +status open + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +struct vq_config_block { +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + + uint16_t index; +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + + uint16_t num; +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +} __attribute__ ((packed)); +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +The number of buffers for queue +\family typewriter +index +\family default + is returned in +\family typewriter +num +\family default +. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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 +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 +\begin_inset listings +inline false +status open + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +struct vq_info_block { +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + + uint64_t queue; +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + + uint16_t num; +\end_layout + +\begin_layout LyX-Code + +\change_inserted -385801441 1343732726 + +} __attribute__ ((packed)); +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 + +\family typewriter +queue +\family default + contains the guest address for queue +\family typewriter +num +\family default +. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Communicating Status Information +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +The guest can change the status of a device via the CCW_CMD_WRITE_STATUS + command, which transmits an 8 bit status value. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Handling Device Features +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +Features are a 32 bit value. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +The guest may obtain the host's device feature set via the CCW_CMD_READ_FEAT + command, which provides a guest address for the host to store the features + to. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +For communicating its device features to the host, the guest may use the + CCW_CMD_WRITE_FEAT command pointing to a guest address where the guest + features can be obtained. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Device Configuration +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +The device's configuration space is located in host memory. + It is the same size as the standard PCI configuration space. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +To obtain information from the configuration space, the guest may use CCW_CMD_RE +AD_CONF, specifying the guest memory for the host to write to. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +For changing configuration information, the guest may use CCW_CMD_WRITE_CONF, + specifying the guest memory for the host to read from. +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +In both cases, the complete configuration space is transmitted. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Setting Up Indicators +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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. +\end_layout + +\begin_layout Subsection* + +\change_inserted -385801441 1343732726 +Device Operation +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Host->Guest Notification +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Guest->Host Notification +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +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. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Early printk for Virtio Consoles +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +For the early printk mechanism, diagnose 0x500 with subcode 0 is used. +\end_layout + +\begin_layout Subsubsection* + +\change_inserted -385801441 1343732726 +Resetting Devices +\end_layout + +\begin_layout Standard + +\change_inserted -385801441 1343732726 +In order to reset a device, a guest may send the CCW_CMD_VDEV_RESET command. +\change_unchanged + \end_layout \end_deeper