sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget&/translations/zh_CN/arch/s390/vfio-ccwmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/zh_TW/arch/s390/vfio-ccwmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/it_IT/arch/s390/vfio-ccwmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ja_JP/arch/s390/vfio-ccwmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ko_KR/arch/s390/vfio-ccwmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/sp_SP/arch/s390/vfio-ccwmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h"vfio-ccw: the basic infrastructureh]h"vfio-ccw: the basic infrastructure}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhh@/var/lib/git/docbuild/linux/Documentation/arch/s390/vfio-ccw.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hHere we describe the vfio support for I/O subchannel devices for Linux/s390. Motivation for vfio-ccw is to passthrough subchannels to a virtual machine, while vfio is the means.h]hHere we describe the vfio support for I/O subchannel devices for Linux/s390. Motivation for vfio-ccw is to passthrough subchannels to a virtual machine, while vfio is the means.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hDifferent than other hardware architectures, s390 has defined a unified I/O access method, which is so called Channel I/O. It has its own access patterns:h]hDifferent than other hardware architectures, s390 has defined a unified I/O access method, which is so called Channel I/O. It has its own access patterns:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh bullet_list)}(hhh](h list_item)}(h@Channel programs run asynchronously on a separate (co)processor.h]h)}(hhh]h@Channel programs run asynchronously on a separate (co)processor.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hThe channel subsystem will access any memory designated by the caller in the channel program directly, i.e. there is no iommu involved. h]h)}(hThe channel subsystem will access any memory designated by the caller in the channel program directly, i.e. there is no iommu involved.h]hThe channel subsystem will access any memory designated by the caller in the channel program directly, i.e. there is no iommu involved.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhKhhhhubh)}(hXThus when we introduce vfio support for these devices, we realize it with a mediated device (mdev) implementation. The vfio mdev will be added to an iommu group, so as to make itself able to be managed by the vfio framework. And we add read/write callbacks for special vfio I/O regions to pass the channel programs from the mdev to its parent device (the real I/O subchannel device) to do further address translation and to perform I/O instructions.h]hXThus when we introduce vfio support for these devices, we realize it with a mediated device (mdev) implementation. The vfio mdev will be added to an iommu group, so as to make itself able to be managed by the vfio framework. And we add read/write callbacks for special vfio I/O regions to pass the channel programs from the mdev to its parent device (the real I/O subchannel device) to do further address translation and to perform I/O instructions.}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThis document does not intend to explain the s390 I/O architecture in every detail. More information/reference could be found here:h]hThis document does not intend to explain the s390 I/O architecture in every detail. More information/reference could be found here:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hVA good start to know Channel I/O in general: https://en.wikipedia.org/wiki/Channel_I/Oh]h)}(hVA good start to know Channel I/O in general: https://en.wikipedia.org/wiki/Channel_I/Oh](h-A good start to know Channel I/O in general: }(hjGhhhNhNubh reference)}(h)https://en.wikipedia.org/wiki/Channel_I/Oh]h)https://en.wikipedia.org/wiki/Channel_I/O}(hjQhhhNhNubah}(h]h ]h"]h$]h&]refurijSuh1jOhjGubeh}(h]h ]h"]h$]h&]uh1hhhhKhjCubah}(h]h ]h"]h$]h&]uh1hhj@hhhhhNubh)}(hPs390 architecture: s390 Principles of Operation manual (IBM Form. No. SA22-7832)h]h)}(hPs390 architecture: s390 Principles of Operation manual (IBM Form. No. SA22-7832)h]hPs390 architecture: s390 Principles of Operation manual (IBM Form. No. SA22-7832)}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hjlubah}(h]h ]h"]h$]h&]uh1hhj@hhhhhNubh)}(hThe existing QEMU code which implements a simple emulated channel subsystem could also be a good reference. It makes it easier to follow the flow. qemu/hw/s390x/css.c h]h)}(hThe existing QEMU code which implements a simple emulated channel subsystem could also be a good reference. It makes it easier to follow the flow. qemu/hw/s390x/css.ch]hThe existing QEMU code which implements a simple emulated channel subsystem could also be a good reference. It makes it easier to follow the flow. qemu/hw/s390x/css.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjubah}(h]h ]h"]h$]h&]uh1hhj@hhhhhNubeh}(h]h ]h"]h$]h&]j"j#uh1hhhhKhhhhubh)}(hWFor vfio mediated device framework: - Documentation/driver-api/vfio-mediated-device.rsth]hWFor vfio mediated device framework: - Documentation/driver-api/vfio-mediated-device.rst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hMotivation of vfio-ccwh]hMotivation of vfio-ccw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK,ubh)}(hXTypically, a guest virtualized via QEMU/KVM on s390 only sees paravirtualized virtio devices via the "Virtio Over Channel I/O (virtio-ccw)" transport. This makes virtio devices discoverable via standard operating system algorithms for handling channel devices.h]hXTypically, a guest virtualized via QEMU/KVM on s390 only sees paravirtualized virtio devices via the “Virtio Over Channel I/O (virtio-ccw)” transport. This makes virtio devices discoverable via standard operating system algorithms for handling channel devices.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjhhubh)}(hXcHowever this is not enough. On s390 for the majority of devices, which use the standard Channel I/O based mechanism, we also need to provide the functionality of passing through them to a QEMU virtual machine. This includes devices that don't have a virtio counterpart (e.g. tape drives) or that have specific characteristics which guests want to exploit.h]hXeHowever this is not enough. On s390 for the majority of devices, which use the standard Channel I/O based mechanism, we also need to provide the functionality of passing through them to a QEMU virtual machine. This includes devices that don’t have a virtio counterpart (e.g. tape drives) or that have specific characteristics which guests want to exploit.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubh)}(hFor passing a device to a guest, we want to use the same interface as everybody else, namely vfio. We implement this vfio support for channel devices via the vfio mediated device framework and the subchannel device driver "vfio_ccw".h]hFor passing a device to a guest, we want to use the same interface as everybody else, namely vfio. We implement this vfio support for channel devices via the vfio mediated device framework and the subchannel device driver “vfio_ccw”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hjhhubeh}(h]motivation-of-vfio-ccwah ]h"]motivation of vfio-ccwah$]h&]uh1hhhhhhhhK,ubh)}(hhh](h)}(hAccess patterns of CCW devicesh]hAccess patterns of CCW devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK@ubh)}(hXs390 architecture has implemented a so called channel subsystem, that provides a unified view of the devices physically attached to the systems. Though the s390 hardware platform knows about a huge variety of different peripheral attachments like disk devices (aka. DASDs), tapes, communication controllers, etc. They can all be accessed by a well defined access method and they are presenting I/O completion a unified way: I/O interruptions.h]hXs390 architecture has implemented a so called channel subsystem, that provides a unified view of the devices physically attached to the systems. Though the s390 hardware platform knows about a huge variety of different peripheral attachments like disk devices (aka. DASDs), tapes, communication controllers, etc. They can all be accessed by a well defined access method and they are presenting I/O completion a unified way: I/O interruptions.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjhhubh)}(hXAll I/O requires the use of channel command words (CCWs). A CCW is an instruction to a specialized I/O channel processor. A channel program is a sequence of CCWs which are executed by the I/O channel subsystem. To issue a channel program to the channel subsystem, it is required to build an operation request block (ORB), which can be used to point out the format of the CCW and other control information to the system. The operating system signals the I/O channel subsystem to begin executing the channel program with a SSCH (start sub-channel) instruction. The central processor is then free to proceed with non-I/O instructions until interrupted. The I/O completion result is received by the interrupt handler in the form of interrupt response block (IRB).h]hXAll I/O requires the use of channel command words (CCWs). A CCW is an instruction to a specialized I/O channel processor. A channel program is a sequence of CCWs which are executed by the I/O channel subsystem. To issue a channel program to the channel subsystem, it is required to build an operation request block (ORB), which can be used to point out the format of the CCW and other control information to the system. The operating system signals the I/O channel subsystem to begin executing the channel program with a SSCH (start sub-channel) instruction. The central processor is then free to proceed with non-I/O instructions until interrupted. The I/O completion result is received by the interrupt handler in the form of interrupt response block (IRB).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjhhubh)}(hBack to vfio-ccw, in short:h]hBack to vfio-ccw, in short:}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKVhjhhubh)}(hhh](h)}(hTORBs and channel programs are built in guest kernel (with guest physical addresses).h]h)}(hTORBs and channel programs are built in guest kernel (with guest physical addresses).h]hTORBs and channel programs are built in guest kernel (with guest physical addresses).}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhj9ubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhNubh)}(h8ORBs and channel programs are passed to the host kernel.h]h)}(hjSh]h8ORBs and channel programs are passed to the host kernel.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKZhjQubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhNubh)}(hHost kernel translates the guest physical addresses to real addresses and starts the I/O with issuing a privileged Channel I/O instruction (e.g SSCH).h]h)}(hHost kernel translates the guest physical addresses to real addresses and starts the I/O with issuing a privileged Channel I/O instruction (e.g SSCH).h]hHost kernel translates the guest physical addresses to real addresses and starts the I/O with issuing a privileged Channel I/O instruction (e.g SSCH).}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjhubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhNubh)}(hvaddr mappings in this operation. And they export a vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu backend for the physical devices to pin and unpin pages by demand. h]h)}(hX/The vfio_mdev driver for the mediated vfio ccw device. This is provided by the mdev framework. It is a vfio device driver for the mdev that created by vfio_ccw. It realizes a group of vfio device driver callbacks, adds itself to a vfio group, and registers itself to the mdev framework as a mdev driver. It uses a vfio iommu backend that uses the existing map and unmap ioctls, but rather than programming them into an IOMMU for a device, it simply stores the translations for use by later requests. This means that a device programmed in a VM with guest physical addresses can have the vfio kernel convert that address to process virtual address, pin the page and program the hardware with the host physical address in one step. For a mdev, the vfio iommu backend will not pin the pages during the VFIO_IOMMU_MAP_DMA ioctl. Mdev framework will only maintain a database of the iova<->vaddr mappings in this operation. And they export a vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu backend for the physical devices to pin and unpin pages by demand.h]hX/The vfio_mdev driver for the mediated vfio ccw device. This is provided by the mdev framework. It is a vfio device driver for the mdev that created by vfio_ccw. It realizes a group of vfio device driver callbacks, adds itself to a vfio group, and registers itself to the mdev framework as a mdev driver. It uses a vfio iommu backend that uses the existing map and unmap ioctls, but rather than programming them into an IOMMU for a device, it simply stores the translations for use by later requests. This means that a device programmed in a VM with guest physical addresses can have the vfio kernel convert that address to process virtual address, pin the page and program the hardware with the host physical address in one step. For a mdev, the vfio iommu backend will not pin the pages during the VFIO_IOMMU_MAP_DMA ioctl. Mdev framework will only maintain a database of the iova<->vaddr mappings in this operation. And they export a vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu backend for the physical devices to pin and unpin pages by demand.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj!ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j"j#uh1hhhhKshjhhubh)}(h%Below is a high Level block diagram::h]h$Below is a high Level block diagram:}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(hX+-------------+ | | | +---------+ | mdev_register_driver() +--------------+ | | Mdev | +<-----------------------+ | | | bus | | | vfio_mdev.ko | | | driver | +----------------------->+ |<-> VFIO user | +---------+ | probe()/remove() +--------------+ APIs | | | MDEV CORE | | MODULE | | mdev.ko | | +---------+ | mdev_register_parent() +--------------+ | |Physical | +<-----------------------+ | | | device | | | vfio_ccw.ko |<-> subchannel | |interface| +----------------------->+ | device | +---------+ | callback +--------------+ +-------------+h]hX+-------------+ | | | +---------+ | mdev_register_driver() +--------------+ | | Mdev | +<-----------------------+ | | | bus | | | vfio_mdev.ko | | | driver | +----------------------->+ |<-> VFIO user | +---------+ | probe()/remove() +--------------+ APIs | | | MDEV CORE | | MODULE | | mdev.ko | | +---------+ | mdev_register_parent() +--------------+ | |Physical | +<-----------------------+ | | | device | | | vfio_ccw.ko |<-> subchannel | |interface| +----------------------->+ | device | +---------+ | callback +--------------+ +-------------+}hjOsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jMhhhKhjhhubh)}(h'The process of how these work together.h]h'The process of how these work together.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubhenumerated_list)}(hhh](h)}(hXvfio_ccw.ko drives the physical I/O subchannel, and registers the physical device (with callbacks) to mdev framework. When vfio_ccw probing the subchannel device, it registers device pointer and callbacks to the mdev framework. Mdev related file nodes under the device node in sysfs would be created for the subchannel device, namely 'mdev_create', 'mdev_destroy' and 'mdev_supported_types'.h]h)}(hXvfio_ccw.ko drives the physical I/O subchannel, and registers the physical device (with callbacks) to mdev framework. When vfio_ccw probing the subchannel device, it registers device pointer and callbacks to the mdev framework. Mdev related file nodes under the device node in sysfs would be created for the subchannel device, namely 'mdev_create', 'mdev_destroy' and 'mdev_supported_types'.h]hXvfio_ccw.ko drives the physical I/O subchannel, and registers the physical device (with callbacks) to mdev framework. When vfio_ccw probing the subchannel device, it registers device pointer and callbacks to the mdev framework. Mdev related file nodes under the device node in sysfs would be created for the subchannel device, namely ‘mdev_create’, ‘mdev_destroy’ and ‘mdev_supported_types’.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1hhjohhhhhNubh)}(hCreate a mediated vfio ccw device. Use the 'mdev_create' sysfs file, we need to manually create one (and only one for our case) mediated device.h]h)}(hCreate a mediated vfio ccw device. Use the 'mdev_create' sysfs file, we need to manually create one (and only one for our case) mediated device.h]hCreate a mediated vfio ccw device. Use the ‘mdev_create’ sysfs file, we need to manually create one (and only one for our case) mediated device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjohhhhhNubh)}(hvfio_mdev.ko drives the mediated ccw device. vfio_mdev is also the vfio device driver. It will probe the mdev and add it to an iommu_group and a vfio_group. Then we could pass through the mdev to a guest. h]h)}(hvfio_mdev.ko drives the mediated ccw device. vfio_mdev is also the vfio device driver. It will probe the mdev and add it to an iommu_group and a vfio_group. Then we could pass through the mdev to a guest.h]hvfio_mdev.ko drives the mediated ccw device. vfio_mdev is also the vfio device driver. It will probe the mdev and add it to an iommu_group and a vfio_group. Then we could pass through the mdev to a guest.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjohhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jmhjhhhhhKubeh}(h]+physical-vfio-ccw-device-and-its-child-mdevah ]h"]+physical vfio ccw device and its child mdevah$]h&]uh1hhhhhhhhKdubh)}(hhh](h)}(hVFIO-CCW Regionsh]hVFIO-CCW Regions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(haThe vfio-ccw driver exposes MMIO regions to accept requests from and return results to userspace.h]haThe vfio-ccw driver exposes MMIO regions to accept requests from and return results to userspace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]vfio-ccw-regionsah ]h"]vfio-ccw regionsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hvfio-ccw I/O regionh]hvfio-ccw I/O region}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hAn I/O region is used to accept channel program request from user space and store I/O interrupt result for user space to retrieve. The definition of the region is::h]hAn I/O region is used to accept channel program request from user space and store I/O interrupt result for user space to retrieve. The definition of the region is:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjN)}(hXstruct ccw_io_region { #define ORB_AREA_SIZE 12 __u8 orb_area[ORB_AREA_SIZE]; #define SCSW_AREA_SIZE 12 __u8 scsw_area[SCSW_AREA_SIZE]; #define IRB_AREA_SIZE 96 __u8 irb_area[IRB_AREA_SIZE]; __u32 ret_code; } __packed;h]hXstruct ccw_io_region { #define ORB_AREA_SIZE 12 __u8 orb_area[ORB_AREA_SIZE]; #define SCSW_AREA_SIZE 12 __u8 scsw_area[SCSW_AREA_SIZE]; #define IRB_AREA_SIZE 96 __u8 irb_area[IRB_AREA_SIZE]; __u32 ret_code; } __packed;}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhjhhubh)}(h This region is always available.h]h This region is always available.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hWhile starting an I/O request, orb_area should be filled with the guest ORB, and scsw_area should be filled with the SCSW of the Virtual Subchannel.h]hWhile starting an I/O request, orb_area should be filled with the guest ORB, and scsw_area should be filled with the SCSW of the Virtual Subchannel.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hirb_area stores the I/O result.h]hirb_area stores the I/O result.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h\ret_code stores a return code for each access of the region. The following values may occur:h]h\ret_code stores a return code for each access of the region. The following values may occur:}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubhdefinition_list)}(hhh](hdefinition_list_item)}(h$``0`` The operation was successful. h](hterm)}(h``0``h]hliteral)}(hjhh]h0}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjfubah}(h]h ]h"]h$]h&]uh1jdhhhKhj`ubh definition)}(hhh]h)}(hThe operation was successful.h]hThe operation was successful.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj`ubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[ubj_)}(hq``-EOPNOTSUPP`` The ORB specified transport mode or the SCSW specified a function other than the start function. h](je)}(h``-EOPNOTSUPP``h]jk)}(hjh]h -EOPNOTSUPP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhjubj)}(hhh]h)}(h`The ORB specified transport mode or the SCSW specified a function other than the start function.h]h`The ORB specified transport mode or the SCSW specified a function other than the start function.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(h{``-EIO`` A request was issued while the device was not in a state ready to accept requests, or an internal error occurred. h](je)}(h``-EIO``h]jk)}(hjh]h-EIO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhjubj)}(hhh]h)}(hqA request was issued while the device was not in a state ready to accept requests, or an internal error occurred.h]hqA request was issued while the device was not in a state ready to accept requests, or an internal error occurred.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(hV``-EBUSY`` The subchannel was status pending or busy, or a request is already active. h](je)}(h ``-EBUSY``h]jk)}(hjh]h-EBUSY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhjubj)}(hhh]h)}(hJThe subchannel was status pending or busy, or a request is already active.h]hJThe subchannel was status pending or busy, or a request is already active.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(hH``-EAGAIN`` A request was being processed, and the caller should retry. h](je)}(h ``-EAGAIN``h]jk)}(hjLh]h-EAGAIN}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjJubah}(h]h ]h"]h$]h&]uh1jdhhhKhjFubj)}(hhh]h)}(h;A request was being processed, and the caller should retry.h]h;A request was being processed, and the caller should retry.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjaubah}(h]h ]h"]h$]h&]uh1jhjFubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(hS``-EACCES`` The channel path(s) used for the I/O were found to be not operational. h](je)}(h ``-EACCES``h]jk)}(hjh]h-EACCES}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhj~ubj)}(hhh]h)}(hFThe channel path(s) used for the I/O were found to be not operational.h]hFThe channel path(s) used for the I/O were found to be not operational.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj~ubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(h8``-ENODEV`` The device was found to be not operational. h](je)}(h ``-ENODEV``h]jk)}(hjh]h-ENODEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhjubj)}(hhh]h)}(h+The device was found to be not operational.h]h+The device was found to be not operational.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubj_)}(h\``-EINVAL`` The orb specified a chain longer than 255 ccws, or an internal error occurred. h](je)}(h ``-EINVAL``h]jk)}(hjh]h-EINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhKhjubj)}(hhh]h)}(hNThe orb specified a chain longer than 255 ccws, or an internal error occurred.h]hNThe orb specified a chain longer than 255 ccws, or an internal error occurred.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhKhj[hhubeh}(h]h ]h"]h$]h&]uh1jYhjhhhhhNubeh}(h]vfio-ccw-i-o-regionah ]h"]vfio-ccw i/o regionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hvfio-ccw cmd regionh]hvfio-ccw cmd region}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj4hhhhhKubh)}(hTThe vfio-ccw cmd region is used to accept asynchronous instructions from userspace::h]hSThe vfio-ccw cmd region is used to accept asynchronous instructions from userspace:}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj4hhubjN)}(h#define VFIO_CCW_ASYNC_CMD_HSCH (1 << 0) #define VFIO_CCW_ASYNC_CMD_CSCH (1 << 1) struct ccw_cmd_region { __u32 command; __u32 ret_code; } __packed;h]h#define VFIO_CCW_ASYNC_CMD_HSCH (1 << 0) #define VFIO_CCW_ASYNC_CMD_CSCH (1 << 1) struct ccw_cmd_region { __u32 command; __u32 ret_code; } __packed;}hjSsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhj4hhubh)}(hIThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD.h]hIThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj4hhubh)}(h@Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region.h]h@Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj4hhubh)}(hcommand specifies the command to be issued; ret_code stores a return code for each access of the region. The following values may occur:h]hcommand specifies the command to be issued; ret_code stores a return code for each access of the region. The following values may occur:}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj4hhubjZ)}(hhh](j_)}(h$``0`` The operation was successful. h](je)}(h``0``h]jk)}(hjh]h0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhM hjubj)}(hhh]h)}(hThe operation was successful.h]hThe operation was successful.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhM hjubj_)}(h8``-ENODEV`` The device was found to be not operational. h](je)}(h ``-ENODEV``h]jk)}(hjh]h-ENODEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhMhjubj)}(hhh]h)}(h+The device was found to be not operational.h]h+The device was found to be not operational.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjhhubj_)}(h>``-EINVAL`` A command other than halt or clear was specified. h](je)}(h ``-EINVAL``h]jk)}(hjh]h-EINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhMhjubj)}(hhh]h)}(h1A command other than halt or clear was specified.h]h1A command other than halt or clear was specified.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjhhubj_)}(h\``-EIO`` A request was issued while the device was not in a state ready to accept requests. h](je)}(h``-EIO``h]jk)}(hj<h]h-EIO}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj:ubah}(h]h ]h"]h$]h&]uh1jdhhhMhj6ubj)}(hhh]h)}(hRA request was issued while the device was not in a state ready to accept requests.h]hRA request was issued while the device was not in a state ready to accept requests.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjQubah}(h]h ]h"]h$]h&]uh1jhj6ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjhhubj_)}(hH``-EAGAIN`` A request was being processed, and the caller should retry. h](je)}(h ``-EAGAIN``h]jk)}(hjth]h-EAGAIN}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjrubah}(h]h ]h"]h$]h&]uh1jdhhhMhjnubj)}(hhh]h)}(h;A request was being processed, and the caller should retry.h]h;A request was being processed, and the caller should retry.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjnubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjhhubj_)}(hV``-EBUSY`` The subchannel was status pending or busy while processing a halt request. h](je)}(h ``-EBUSY``h]jk)}(hjh]h-EBUSY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]uh1jdhhhMhjubj)}(hhh]h)}(hJThe subchannel was status pending or busy while processing a halt request.h]hJThe subchannel was status pending or busy while processing a halt request.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjhhubeh}(h]h ]h"]h$]h&]uh1jYhj4hhhhhNubeh}(h]vfio-ccw-cmd-regionah ]h"]vfio-ccw cmd regionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hvfio-ccw schib regionh]hvfio-ccw schib region}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hdThe vfio-ccw schib region is used to return Subchannel-Information Block (SCHIB) data to userspace::h]hcThe vfio-ccw schib region is used to return Subchannel-Information Block (SCHIB) data to userspace:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubjN)}(histruct ccw_schib_region { #define SCHIB_AREA_SIZE 52 __u8 schib_area[SCHIB_AREA_SIZE]; } __packed;h]histruct ccw_schib_region { #define SCHIB_AREA_SIZE 52 __u8 schib_area[SCHIB_AREA_SIZE]; } __packed;}hj sbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhM#hjhhubh)}(hEThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB.h]hEThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjhhubh)}(hXReading this region triggers a STORE SUBCHANNEL to be issued to the associated hardware.h]hXReading this region triggers a STORE SUBCHANNEL to be issued to the associated hardware.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjhhubeh}(h]vfio-ccw-schib-regionah ]h"]vfio-ccw schib regionah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hvfio-ccw crw regionh]hvfio-ccw crw region}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=hhhhhM.ubh)}(hWThe vfio-ccw crw region is used to return Channel Report Word (CRW) data to userspace::h]hVThe vfio-ccw crw region is used to return Channel Report Word (CRW) data to userspace:}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hj=hhubjN)}(hGstruct ccw_crw_region { __u32 crw; __u32 pad; } __packed;h]hGstruct ccw_crw_region { __u32 crw; __u32 pad; } __packed;}hj\sbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhM3hj=hhubh)}(hCThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_CRW.h]hCThis region is exposed via region type VFIO_REGION_SUBTYPE_CCW_CRW.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hj=hhubh)}(hXReading this region returns a CRW if one that is relevant for this subchannel (e.g. one reporting changes in channel path state) is pending, or all zeroes if not. If multiple CRWs are pending (including possibly chained CRWs), reading this region again will return the next one, until no more CRWs are pending and zeroes are returned. This is similar to how STORE CHANNEL REPORT WORD works.h]hXReading this region returns a CRW if one that is relevant for this subchannel (e.g. one reporting changes in channel path state) is pending, or all zeroes if not. If multiple CRWs are pending (including possibly chained CRWs), reading this region again will return the next one, until no more CRWs are pending and zeroes are returned. This is similar to how STORE CHANNEL REPORT WORD works.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hj=hhubeh}(h]vfio-ccw-crw-regionah ]h"]vfio-ccw crw regionah$]h&]uh1hhhhhhhhM.ubh)}(hhh](h)}(hvfio-ccw operation detailsh]hvfio-ccw operation details}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMBubh)}(hlvfio-ccw follows what vfio-pci did on the s390 platform and uses vfio-iommu-type1 as the vfio iommu backend.h]hlvfio-ccw follows what vfio-pci did on the s390 platform and uses vfio-iommu-type1 as the vfio iommu backend.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhjhhubh)}(hhh](h)}(hXCCW translation APIs A group of APIs (start with `cp_`) to do CCW translation. The CCWs passed in by a user space program are organized with their guest physical memory addresses. These APIs will copy the CCWs into kernel space, and assemble a runnable kernel channel program by updating the guest physical addresses with their corresponding host physical addresses. Note that we have to use IDALs even for direct-access CCWs, as the referenced memory can be located anywhere, including above 2G. h]h)}(hXCCW translation APIs A group of APIs (start with `cp_`) to do CCW translation. The CCWs passed in by a user space program are organized with their guest physical memory addresses. These APIs will copy the CCWs into kernel space, and assemble a runnable kernel channel program by updating the guest physical addresses with their corresponding host physical addresses. Note that we have to use IDALs even for direct-access CCWs, as the referenced memory can be located anywhere, including above 2G.h](h1CCW translation APIs A group of APIs (start with }(hjhhhNhNubhtitle_reference)}(h`cp_`h]hcp_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX) to do CCW translation. The CCWs passed in by a user space program are organized with their guest physical memory addresses. These APIs will copy the CCWs into kernel space, and assemble a runnable kernel channel program by updating the guest physical addresses with their corresponding host physical addresses. Note that we have to use IDALs even for direct-access CCWs, as the referenced memory can be located anywhere, including above 2G.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXvfio_ccw device driver This driver utilizes the CCW translation APIs and introduces vfio_ccw, which is the driver for the I/O subchannel devices you want to pass through. vfio_ccw implements the following vfio ioctls:: VFIO_DEVICE_GET_INFO VFIO_DEVICE_GET_IRQ_INFO VFIO_DEVICE_GET_REGION_INFO VFIO_DEVICE_RESET VFIO_DEVICE_SET_IRQS This provides an I/O region, so that the user space program can pass a channel program to the kernel, to do further CCW translation before issuing them to a real device. This also provides the SET_IRQ ioctl to setup an event notifier to notify the user space program the I/O completion in an asynchronous way. h](h)}(hvfio_ccw device driver This driver utilizes the CCW translation APIs and introduces vfio_ccw, which is the driver for the I/O subchannel devices you want to pass through. vfio_ccw implements the following vfio ioctls::h]hvfio_ccw device driver This driver utilizes the CCW translation APIs and introduces vfio_ccw, which is the driver for the I/O subchannel devices you want to pass through. vfio_ccw implements the following vfio ioctls:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhjubjN)}(hpVFIO_DEVICE_GET_INFO VFIO_DEVICE_GET_IRQ_INFO VFIO_DEVICE_GET_REGION_INFO VFIO_DEVICE_RESET VFIO_DEVICE_SET_IRQSh]hpVFIO_DEVICE_GET_INFO VFIO_DEVICE_GET_IRQ_INFO VFIO_DEVICE_GET_REGION_INFO VFIO_DEVICE_RESET VFIO_DEVICE_SET_IRQS}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhMVhjubh)}(hX5This provides an I/O region, so that the user space program can pass a channel program to the kernel, to do further CCW translation before issuing them to a real device. This also provides the SET_IRQ ioctl to setup an event notifier to notify the user space program the I/O completion in an asynchronous way.h]hX5This provides an I/O region, so that the user space program can pass a channel program to the kernel, to do further CCW translation before issuing them to a real device. This also provides the SET_IRQ ioctl to setup an event notifier to notify the user space program the I/O completion in an asynchronous way.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM\hjubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j"*uh1hhhhMGhjhhubh)}(hThe use of vfio-ccw is not limited to QEMU, while QEMU is definitely a good example to get understand how these patches work. Here is a little bit more detail how an I/O request triggered by the QEMU guest will be handled (without error handling).h]hThe use of vfio-ccw is not limited to QEMU, while QEMU is definitely a good example to get understand how these patches work. Here is a little bit more detail how an I/O request triggered by the QEMU guest will be handled (without error handling).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMchjhhubh)}(h Explanation:h]h Explanation:}(hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhjhhubh)}(hhh](h)}(hQ1-Q7: QEMU side process.h]h)}(hj8 h]hQ1-Q7: QEMU side process.}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMjhj6 ubah}(h]h ]h"]h$]h&]uh1hhj3 hhhhhNubh)}(hK1-K5: Kernel side process. h]h)}(hK1-K5: Kernel side process.h]hK1-K5: Kernel side process.}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMkhjM ubah}(h]h ]h"]h$]h&]uh1hhj3 hhhhhNubeh}(h]h ]h"]h$]h&]j"j#uh1hhhhMjhjhhubjZ)}(hhh](j_)}(h/Q1. Get I/O region info during initialization. h](je)}(hQ1.h]hQ1.}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMnhjn ubj)}(hhh]h)}(h*Get I/O region info during initialization.h]h*Get I/O region info during initialization.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMnhj ubah}(h]h ]h"]h$]h&]uh1jhjn ubeh}(h]h ]h"]h$]h&]uh1j^hhhMnhjk ubj_)}(h?Q2. Setup event notifier and handler to handle I/O completion. h](je)}(hQ2.h]hQ2.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMqhj ubj)}(hhh]h)}(h:Setup event notifier and handler to handle I/O completion.h]h:Setup event notifier and handler to handle I/O completion.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMqhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMqhjk hhubeh}(h]h ]h"]h$]h&]uh1jYhjhhhhhNubh)}(h... ...h]h... ...}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMshjhhubjZ)}(hhh](j_)}(h!Q3. Intercept a ssch instruction.h](je)}(hQ3.h]hQ3.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMuhj ubj)}(hhh]h)}(hIntercept a ssch instruction.h]hIntercept a ssch instruction.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMvhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMuhj ubj_)}(hXzQ4. Write the guest channel program and ORB to the I/O region. K1. Copy from guest to kernel. K2. Translate the guest channel program to a host kernel space channel program, which becomes runnable for a real device. K3. With the necessary information contained in the orb passed in by QEMU, issue the ccwchain to the device. K4. Return the ssch CC code.h](je)}(hQ4.h]hQ4.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh](h)}(h:Write the guest channel program and ORB to the I/O region.h]h:Write the guest channel program and ORB to the I/O region.}(hj' hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj$ ubjZ)}(hhh](j_)}(hK1. Copy from guest to kernel.h](je)}(hK1.h]hK1.}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMzhj8 ubj)}(hhh]h)}(hCopy from guest to kernel.h]hCopy from guest to kernel.}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hjJ ubah}(h]h ]h"]h$]h&]uh1jhj8 ubeh}(h]h ]h"]h$]h&]uh1j^hhhMzhj5 ubj_)}(hyK2. Translate the guest channel program to a host kernel space channel program, which becomes runnable for a real device.h](je)}(hK2.h]hK2.}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhM}hjg ubj)}(hhh]h)}(huTranslate the guest channel program to a host kernel space channel program, which becomes runnable for a real device.h]huTranslate the guest channel program to a host kernel space channel program, which becomes runnable for a real device.}(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM}hjy ubah}(h]h ]h"]h$]h&]uh1jhjg ubeh}(h]h ]h"]h$]h&]uh1j^hhhM}hj5 ubj_)}(hlK3. With the necessary information contained in the orb passed in by QEMU, issue the ccwchain to the device.h](je)}(hK3.h]hK3.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(hhWith the necessary information contained in the orb passed in by QEMU, issue the ccwchain to the device.h]hhWith the necessary information contained in the orb passed in by QEMU, issue the ccwchain to the device.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj5 ubj_)}(hK4. Return the ssch CC code.h](je)}(hK4.h]hK4.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(hReturn the ssch CC code.h]hReturn the ssch CC code.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj5 ubeh}(h]h ]h"]h$]h&]uh1jYhj$ ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj hhubj_)}(h%Q5. Return the CC code to the guest. h](je)}(hQ5.h]hQ5.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(h Return the CC code to the guest.h]h Return the CC code to the guest.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj hhubeh}(h]h ]h"]h$]h&]uh1jYhjhhhhhNubh)}(h... ...h]h... ...}(hj; hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh block_quote)}(hK5. Interrupt handler gets the I/O result and write the result to the I/O region. K6. Signal QEMU to retrieve the result. h]jZ)}(hhh](j_)}(hQK5. Interrupt handler gets the I/O result and write the result to the I/O region.h](je)}(hK5.h]hK5.}(hjV hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhjR ubj)}(hhh]h)}(hMInterrupt handler gets the I/O result and write the result to the I/O region.h]hMInterrupt handler gets the I/O result and write the result to the I/O region.}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjd ubah}(h]h ]h"]h$]h&]uh1jhjR ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjO ubj_)}(h(K6. Signal QEMU to retrieve the result. h](je)}(hK6.h]hK6.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(h#Signal QEMU to retrieve the result.h]h#Signal QEMU to retrieve the result.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhjO ubeh}(h]h ]h"]h$]h&]uh1jYhjK ubah}(h]h ]h"]h$]h&]uh1jI hhhMhjhhubjZ)}(hhh](j_)}(hNQ6. Get the signal and event handler reads out the result from the I/O region.h](je)}(hQ6.h]hQ6.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(hJGet the signal and event handler reads out the result from the I/O region.h]hJGet the signal and event handler reads out the result from the I/O region.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj ubj_)}(h"Q7. Update the irb for the guest. h](je)}(hQ7.h]hQ7.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhhhMhj ubj)}(hhh]h)}(hUpdate the irb for the guest.h]hUpdate the irb for the guest.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j^hhhMhj hhubeh}(h]h ]h"]h$]h&]uh1jYhjhhhhhNubeh}(h]vfio-ccw-operation-detailsah ]h"]vfio-ccw operation detailsah$]h&]uh1hhhhhhhhMBubh)}(hhh](h)}(h Limitationsh]h Limitations}(hj. hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+ hhhhhMubh)}(hXThe current vfio-ccw implementation focuses on supporting basic commands needed to implement block device functionality (read/write) of DASD/ECKD device only. Some commands may need special handling in the future, for example, anything related to path grouping.h]hXThe current vfio-ccw implementation focuses on supporting basic commands needed to implement block device functionality (read/write) of DASD/ECKD device only. Some commands may need special handling in the future, for example, anything related to path grouping.}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(hDASD is a kind of storage device. While ECKD is a data recording format. More information for DASD and ECKD could be found here: https://en.wikipedia.org/wiki/Direct-access_storage_device https://en.wikipedia.org/wiki/Count_key_datah](hDASD is a kind of storage device. While ECKD is a data recording format. More information for DASD and ECKD could be found here: }(hjJ hhhNhNubjP)}(h:https://en.wikipedia.org/wiki/Direct-access_storage_deviceh]h:https://en.wikipedia.org/wiki/Direct-access_storage_device}(hjR hhhNhNubah}(h]h ]h"]h$]h&]refurijT uh1jOhjJ ubh }(hjJ hhhNhNubjP)}(h,https://en.wikipedia.org/wiki/Count_key_datah]h,https://en.wikipedia.org/wiki/Count_key_data}(hje hhhNhNubah}(h]h ]h"]h$]h&]refurijg uh1jOhjJ ubeh}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(hTogether with the corresponding work in QEMU, we can bring the passed through DASD/ECKD device online in a guest now and use it as a block device.h]hTogether with the corresponding work in QEMU, we can bring the passed through DASD/ECKD device online in a guest now and use it as a block device.}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(hThe current code allows the guest to start channel programs via START SUBCHANNEL, and to issue HALT SUBCHANNEL, CLEAR SUBCHANNEL, and STORE SUBCHANNEL.h]hThe current code allows the guest to start channel programs via START SUBCHANNEL, and to issue HALT SUBCHANNEL, CLEAR SUBCHANNEL, and STORE SUBCHANNEL.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(hX5Currently all channel programs are prefetched, regardless of the p-bit setting in the ORB. As a result, self modifying channel programs are not supported. For this reason, IPL has to be handled as a special case by a userspace/guest program; this has been implemented in QEMU's s390-ccw bios as of QEMU 4.1.h]hX7Currently all channel programs are prefetched, regardless of the p-bit setting in the ORB. As a result, self modifying channel programs are not supported. For this reason, IPL has to be handled as a special case by a userspace/guest program; this has been implemented in QEMU’s s390-ccw bios as of QEMU 4.1.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(havfio-ccw supports classic (command mode) channel I/O only. Transport mode (HPF) is not supported.h]havfio-ccw supports classic (command mode) channel I/O only. Transport mode (HPF) is not supported.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubh)}(hxQDIO subchannels are currently not supported. Classic devices other than DASD/ECKD might work, but have not been tested.h]hxQDIO subchannels are currently not supported. Classic devices other than DASD/ECKD might work, but have not been tested.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ hhubeh}(h] limitationsah ]h"] limitationsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h Referenceh]h Reference}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubjn)}(hhh](h)}(hAESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)h]h)}(hj h]hAESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hCESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)h]h)}(hj h]hCESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h)https://en.wikipedia.org/wiki/Channel_I/Oh]h)}(hj h]jP)}(hj h]h)https://en.wikipedia.org/wiki/Channel_I/O}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij uh1jOhj ubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hDocumentation/arch/s390/cds.rsth]h)}(hj- h]hDocumentation/arch/s390/cds.rst}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+ ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h!Documentation/driver-api/vfio.rsth]h)}(hjD h]h!Documentation/driver-api/vfio.rst}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjB ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h1Documentation/driver-api/vfio-mediated-device.rsth]h)}(hj[ h]h1Documentation/driver-api/vfio-mediated-device.rst}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjY ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubeh}(h]h ]h"]h$]h&]jjjhjjuh1jmhj hhhhhMubeh}(h] referenceah ]h"] referenceah$]h&]uh1hhhhhhhhMubeh}(h]!vfio-ccw-the-basic-infrastructureah ]h"]"vfio-ccw: the basic infrastructureah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jjjjjjjjjjj1j.jjj:j7jjj( j% j j j{ jx u nametypes}(j jjjjjj1jj:jj( j j{ uh}(j hjhjjjjjjjjj.jjj4j7jjj=j% jj j+ jx j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.