arch/s390/vfio-ccw.rst

2 vfio-ccw: the basic infrastructure
6 ------------
9 Linux/s390. Motivation for vfio-ccw is to passthrough subchannels to a
16 - Channel programs run asynchronously on a separate (co)processor.
17 - The channel subsystem will access any memory designated by the caller
18   in the channel program directly, i.e. there is no iommu involved.
22 added to an iommu group, so as to make itself able to be managed by the
31 - A good start to know Channel I/O in general:
33 - s390 architecture:
34   s390 Principles of Operation manual (IBM Form. No. SA22-7832)
35 - The existing QEMU code which implements a simple emulated channel
41 - Documentation/driver-api/vfio-mediated-device.rst
43 Motivation of vfio-ccw
44 ----------------------
47 paravirtualized virtio devices via the "Virtio Over Channel I/O
48 (virtio-ccw)" transport. This makes virtio devices discoverable via
54 This includes devices that don't have a virtio counterpart (e.g. tape
64 ------------------------------
81 the channel program with a SSCH (start sub-channel) instruction. The
82 central processor is then free to proceed with non-I/O instructions
86 Back to vfio-ccw, in short:
88 - ORBs and channel programs are built in guest kernel (with guest
90 - ORBs and channel programs are passed to the host kernel.
91 - Host kernel translates the guest physical addresses to real addresses
94 - channel programs run asynchronously on a separate processor.
95 - I/O completion will be signaled to the host with I/O interruptions.
100 -------------------------------------------
102 As mentioned above, we realize vfio-ccw with a mdev implementation.
104 Channel I/O does not have IOMMU hardware support, so the physical
105 vfio-ccw device does not have an IOMMU level translation or isolation.
108 handling the I/O instruction interception, vfio-ccw has the software
115 - The vfio_ccw driver for the physical subchannel device.
121   device that added to an IOMMU group and a vfio group.
127 - The vfio_mdev driver for the mediated vfio ccw device.
133   It uses a vfio iommu backend that uses the existing map and unmap
134   ioctls, but rather than programming them into an IOMMU for a device,
140   For a mdev, the vfio iommu backend will not pin the pages during the
142   of the iova<->vaddr mappings in this operation. And they export a
143   vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu
148  +-------------+
150  | +---------+ | mdev_register_driver() +--------------+
151  | |  Mdev   | +<-----------------------+              |
153  | | driver  | +----------------------->+              |<-> VFIO user
154  | +---------+ |    probe()/remove()    +--------------+    APIs
159  | +---------+ | mdev_register_parent() +--------------+
160  | |Physical | +<-----------------------+              |
161  | | device  | |                        |  vfio_ccw.ko |<-> subchannel
162  | |interface| +----------------------->+              |     device
163  | +---------+ |       callback         +--------------+
164  +-------------+
184 VFIO-CCW Regions
185 ----------------
187 The vfio-ccw driver exposes MMIO regions to accept requests from and return
190 vfio-ccw I/O region
191 -------------------
221 ``-EOPNOTSUPP``
225 ``-EIO``
229 ``-EBUSY``
232 ``-EAGAIN``
235 ``-EACCES``
238 ``-ENODEV``
241 ``-EINVAL``
246 vfio-ccw cmd region
247 -------------------
249 The vfio-ccw cmd region is used to accept asynchronous instructions
269 ``-ENODEV``
272 ``-EINVAL``
275 ``-EIO``
279 ``-EAGAIN``
282 ``-EBUSY``
285 vfio-ccw schib region
286 ---------------------
288 The vfio-ccw schib region is used to return Subchannel-Information
301 vfio-ccw crw region
302 ---------------------
304 The vfio-ccw crw region is used to return Channel Report Word (CRW)
321 vfio-ccw operation details
322 --------------------------
324 vfio-ccw follows what vfio-pci did on the s390 platform and uses
325 vfio-iommu-type1 as the vfio iommu backend.
333   Note that we have to use IDALs even for direct-access CCWs, as the
355 The use of vfio-ccw is not limited to QEMU, while QEMU is definitely a
362 - Q1-Q7: QEMU side process.
363 - K1-K5: Kernel side process.
406 -----------
408 The current vfio-ccw implementation focuses on supporting basic commands
415 https://en.wikipedia.org/wiki/Direct-access_storage_device
427 p-bit setting in the ORB.  As a result, self modifying channel
430 in QEMU's s390-ccw bios as of QEMU 4.1.
432 vfio-ccw supports classic (command mode) channel I/O only. Transport
439 ---------
440 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)
441 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)
444 5. Documentation/driver-api/vfio.rst
445 6. Documentation/driver-api/vfio-mediated-device.rst