Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 69cfd92e authored by Cornelia Huck's avatar Cornelia Huck
Browse files

vfio-ccw: update documentation 



The vfio-ccw documentation comes from the cover letter of the
original patch submission, which shows in some parts. Give it some
love; in particular:

- Remove/rework statements that make sense in a cover letter, but not
  in regular documentation.
- Fix some typos.
- Describe the current limitations in more detail.

Acked-by: default avatarHalil Pasic <pasic@linux.vnet.ibm.com>
Reviewed-by: default avatarDong Jia Shi <bjsdjshi@linux.vnet.ibm.com>
Signed-off-by: default avatarCornelia Huck <cohuck@redhat.com>
parent 5628683c

Documentation/s390/vfio-ccw.txt

+38 −41
Original line number Original line Diff line number Diff line
@@ -28,7 +28,7 @@ every detail. More information/reference could be found here: 
  https://en.wikipedia.org/wiki/Channel_I/O

  https://en.wikipedia.org/wiki/Channel_I/O

- s390 architecture:

- s390 architecture:

  s390 Principles of Operation manual (IBM Form. No. SA22-7832)

  s390 Principles of Operation manual (IBM Form. No. SA22-7832)

- The existing Qemu code which implements a simple emulated channel

- The existing QEMU code which implements a simple emulated channel

  subsystem could also be a good reference. It makes it easier to follow

  subsystem could also be a good reference. It makes it easier to follow

  the flow.

  the flow.

  qemu/hw/s390x/css.c

  qemu/hw/s390x/css.c
@@ -39,22 +39,22 @@ For vfio mediated device framework: 
Motivation of vfio-ccw

Motivation of vfio-ccw

----------------------

----------------------





Currently, a guest virtualized via qemu/kvm on s390 only sees

Typically, a guest virtualized via QEMU/KVM on s390 only sees

paravirtualized virtio devices via the "Virtio Over Channel I/O

paravirtualized virtio devices via the "Virtio Over Channel I/O

(virtio-ccw)" transport. This makes virtio devices discoverable via

(virtio-ccw)" transport. This makes virtio devices discoverable via

standard operating system algorithms for handling channel devices.

standard operating system algorithms for handling channel devices.





However this is not enough. On s390 for the majority of devices, which

However 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

use the standard Channel I/O based mechanism, we also need to provide

the functionality of passing through them to a Qemu virtual machine.

the functionality of passing through them to a QEMU virtual machine.

This includes devices that don't have a virtio counterpart (e.g. tape

This includes devices that don't have a virtio counterpart (e.g. tape

drives) or that have specific characteristics which guests want to

drives) or that have specific characteristics which guests want to

exploit.

exploit.





For passing a device to a guest, we want to use the same interface as

For passing a device to a guest, we want to use the same interface as

everybody else, namely vfio. Thus, we would like to introduce vfio

everybody else, namely vfio. We implement this vfio support for channel

support for channel devices. And we would like to name this new vfio

devices via the vfio mediated device framework and the subchannel device

device "vfio-ccw".

driver "vfio_ccw".





Access patterns of CCW devices

Access patterns of CCW devices

------------------------------

------------------------------
@@ -99,7 +99,7 @@ As mentioned above, we realize vfio-ccw with a mdev implementation. 
Channel I/O does not have IOMMU hardware support, so the physical

Channel I/O does not have IOMMU hardware support, so the physical

vfio-ccw device does not have an IOMMU level translation or isolation.

vfio-ccw device does not have an IOMMU level translation or isolation.





Sub-channel I/O instructions are all privileged instructions, When

Subchannel I/O instructions are all privileged instructions. When

handling the I/O instruction interception, vfio-ccw has the software

handling the I/O instruction interception, vfio-ccw has the software

policing and translation how the channel program is programmed before

policing and translation how the channel program is programmed before

it gets sent to hardware.

it gets sent to hardware.
@@ -121,7 +121,7 @@ devices: 
- The vfio_mdev driver for the mediated vfio ccw device.

- The vfio_mdev driver for the mediated vfio ccw device.

  This is provided by the mdev framework. It is a vfio device driver for

  This is provided by the mdev framework. It is a vfio device driver for

  the mdev that created by vfio_ccw.

  the mdev that created by vfio_ccw.

  It realize a group of vfio device driver callbacks, adds itself to a

  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

  vfio group, and registers itself to the mdev framework as a mdev

  driver.

  driver.

  It uses a vfio iommu backend that uses the existing map and unmap

  It uses a vfio iommu backend that uses the existing map and unmap
@@ -178,7 +178,7 @@ vfio-ccw I/O region 




An I/O region is used to accept channel program request from user

An 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

space and store I/O interrupt result for user space to retrieve. The

defination of the region is:

definition of the region is:





struct ccw_io_region {

struct ccw_io_region {

#define ORB_AREA_SIZE 12

#define ORB_AREA_SIZE 12
@@ -198,30 +198,23 @@ irb_area stores the I/O result. 




ret_code stores a return code for each access of the region.

ret_code stores a return code for each access of the region.





vfio-ccw patches overview

vfio-ccw operation details

-------------------------

--------------------------





For now, our patches are rebased on the latest mdev implementation.

vfio-ccw follows what vfio-pci did on the s390 platform and uses

vfio-ccw follows what vfio-pci did on the s390 paltform and uses

vfio-iommu-type1 as the vfio iommu backend.

vfio-iommu-type1 as the vfio iommu backend. It's a good start to launch

the code review for vfio-ccw. Note that the implementation is far from

complete yet; but we'd like to get feedback for the general

architecture.





* CCW translation APIs

* CCW translation APIs

- Description:

  A group of APIs (start with 'cp_') to do CCW translation. The CCWs

  These introduce a group of APIs (start with 'cp_') to do CCW

  passed in by a user space program are organized with their guest

  translation. The CCWs passed in by a user space program are

  physical memory addresses. These APIs will copy the CCWs into kernel

  organized with their guest physical memory addresses. These APIs

  space, and assemble a runnable kernel channel program by updating the

  will copy the CCWs into the kernel space, and assemble a runnable

  guest physical addresses with their corresponding host physical addresses.

  kernel channel program by updating the guest physical addresses with

  Note that we have to use IDALs even for direct-access CCWs, as the

  their corresponding host physical addresses.

  referenced memory can be located anywhere, including above 2G.

- Patches:

  vfio: ccw: introduce channel program interfaces





* vfio_ccw device driver

* vfio_ccw device driver

- Description:

  This driver utilizes the CCW translation APIs and introduces

  The following patches utilizes the CCW translation APIs and introduce

  vfio_ccw, which is the driver for the I/O subchannel devices you want

  vfio_ccw, which is the driver for the I/O subchannel devices you want

  to pass through.

  to pass through.

  vfio_ccw implements the following vfio ioctls:

  vfio_ccw implements the following vfio ioctls:
@@ -236,20 +229,14 @@ architecture. 
  This also provides the SET_IRQ ioctl to setup an event notifier to

  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

  notify the user space program the I/O completion in an asynchronous

  way.

  way.

- Patches:



  vfio: ccw: basic implementation for vfio_ccw driver

The use of vfio-ccw is not limited to QEMU, while QEMU is definitely a

  vfio: ccw: introduce ccw_io_region

  vfio: ccw: realize VFIO_DEVICE_GET_REGION_INFO ioctl

  vfio: ccw: realize VFIO_DEVICE_RESET ioctl

  vfio: ccw: realize VFIO_DEVICE_G(S)ET_IRQ_INFO ioctls



The user 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

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

bit more detail how an I/O request triggered by the QEMU guest will be

handled (without error handling).

handled (without error handling).





Explanation:

Explanation:

Q1-Q7: Qemu side process.

Q1-Q7: QEMU side process.

K1-K5: Kernel side process.

K1-K5: Kernel side process.





Q1. Get I/O region info during initialization.

Q1. Get I/O region info during initialization.
@@ -263,7 +250,7 @@ Q4. Write the guest channel program and ORB to the I/O region. 
    K2. Translate the guest channel program to a host kernel space

    K2. Translate the guest channel program to a host kernel space

        channel program, which becomes runnable for a real device.

        channel program, which becomes runnable for a real device.

    K3. With the necessary information contained in the orb passed in

    K3. With the necessary information contained in the orb passed in

        by Qemu, issue the ccwchain to the device.

        by QEMU, issue the ccwchain to the device.

    K4. Return the ssch CC code.

    K4. Return the ssch CC code.

Q5. Return the CC code to the guest.

Q5. Return the CC code to the guest.
@@ -271,7 +258,7 @@ Q5. Return the CC code to the guest. 




    K5. Interrupt handler gets the I/O result and write the result to

    K5. Interrupt handler gets the I/O result and write the result to

        the I/O region.

        the I/O region.

    K6. Signal Qemu to retrieve the result.

    K6. Signal QEMU to retrieve the result.

Q6. Get the signal and event handler reads out the result from the I/O

Q6. Get the signal and event handler reads out the result from the I/O

    region.

    region.

Q7. Update the irb for the guest.

Q7. Update the irb for the guest.
@@ -289,10 +276,20 @@ More information for DASD and ECKD could be found here: 
https://en.wikipedia.org/wiki/Direct-access_storage_device

https://en.wikipedia.org/wiki/Direct-access_storage_device

https://en.wikipedia.org/wiki/Count_key_data

https://en.wikipedia.org/wiki/Count_key_data





Together with the corresponding work in Qemu, we can bring the passed

Together 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

through DASD/ECKD device online in a guest now and use it as a block

device.

device.





While the current code allows the guest to start channel programs via

START SUBCHANNEL, support for HALT SUBCHANNEL or CLEAR SUBCHANNEL is

not yet implemented.



vfio-ccw supports classic (command mode) channel I/O only. Transport

mode (HPF) is not supported.



QDIO subchannels are currently not supported. Classic devices other than

DASD/ECKD might work, but have not been tested.



Reference

Reference

---------

---------

1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)

1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)