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
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 ----------------------
48 (virtio-ccw)" transport. This makes virtio devices discoverable via
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.
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.
127 - The vfio_mdev driver for the mediated vfio ccw device.
142   of the iova<->vaddr mappings in this operation. And they export a
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
334   referenced memory can be located anywhere, including above 2G.
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