vfio-ccw.rst 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445
  1. ==================================
  2. vfio-ccw: the basic infrastructure
  3. ==================================
  4. Introduction
  5. ------------
  6. Here we describe the vfio support for I/O subchannel devices for
  7. Linux/s390. Motivation for vfio-ccw is to passthrough subchannels to a
  8. virtual machine, while vfio is the means.
  9. Different than other hardware architectures, s390 has defined a unified
  10. I/O access method, which is so called Channel I/O. It has its own access
  11. patterns:
  12. - Channel programs run asynchronously on a separate (co)processor.
  13. - The channel subsystem will access any memory designated by the caller
  14. in the channel program directly, i.e. there is no iommu involved.
  15. Thus when we introduce vfio support for these devices, we realize it
  16. with a mediated device (mdev) implementation. The vfio mdev will be
  17. added to an iommu group, so as to make itself able to be managed by the
  18. vfio framework. And we add read/write callbacks for special vfio I/O
  19. regions to pass the channel programs from the mdev to its parent device
  20. (the real I/O subchannel device) to do further address translation and
  21. to perform I/O instructions.
  22. This document does not intend to explain the s390 I/O architecture in
  23. every detail. More information/reference could be found here:
  24. - A good start to know Channel I/O in general:
  25. https://en.wikipedia.org/wiki/Channel_I/O
  26. - s390 architecture:
  27. s390 Principles of Operation manual (IBM Form. No. SA22-7832)
  28. - The existing QEMU code which implements a simple emulated channel
  29. subsystem could also be a good reference. It makes it easier to follow
  30. the flow.
  31. qemu/hw/s390x/css.c
  32. For vfio mediated device framework:
  33. - Documentation/driver-api/vfio-mediated-device.rst
  34. Motivation of vfio-ccw
  35. ----------------------
  36. Typically, a guest virtualized via QEMU/KVM on s390 only sees
  37. paravirtualized virtio devices via the "Virtio Over Channel I/O
  38. (virtio-ccw)" transport. This makes virtio devices discoverable via
  39. standard operating system algorithms for handling channel devices.
  40. However this is not enough. On s390 for the majority of devices, which
  41. use the standard Channel I/O based mechanism, we also need to provide
  42. the functionality of passing through them to a QEMU virtual machine.
  43. This includes devices that don't have a virtio counterpart (e.g. tape
  44. drives) or that have specific characteristics which guests want to
  45. exploit.
  46. For passing a device to a guest, we want to use the same interface as
  47. everybody else, namely vfio. We implement this vfio support for channel
  48. devices via the vfio mediated device framework and the subchannel device
  49. driver "vfio_ccw".
  50. Access patterns of CCW devices
  51. ------------------------------
  52. s390 architecture has implemented a so called channel subsystem, that
  53. provides a unified view of the devices physically attached to the
  54. systems. Though the s390 hardware platform knows about a huge variety of
  55. different peripheral attachments like disk devices (aka. DASDs), tapes,
  56. communication controllers, etc. They can all be accessed by a well
  57. defined access method and they are presenting I/O completion a unified
  58. way: I/O interruptions.
  59. All I/O requires the use of channel command words (CCWs). A CCW is an
  60. instruction to a specialized I/O channel processor. A channel program is
  61. a sequence of CCWs which are executed by the I/O channel subsystem. To
  62. issue a channel program to the channel subsystem, it is required to
  63. build an operation request block (ORB), which can be used to point out
  64. the format of the CCW and other control information to the system. The
  65. operating system signals the I/O channel subsystem to begin executing
  66. the channel program with a SSCH (start sub-channel) instruction. The
  67. central processor is then free to proceed with non-I/O instructions
  68. until interrupted. The I/O completion result is received by the
  69. interrupt handler in the form of interrupt response block (IRB).
  70. Back to vfio-ccw, in short:
  71. - ORBs and channel programs are built in guest kernel (with guest
  72. physical addresses).
  73. - ORBs and channel programs are passed to the host kernel.
  74. - Host kernel translates the guest physical addresses to real addresses
  75. and starts the I/O with issuing a privileged Channel I/O instruction
  76. (e.g SSCH).
  77. - channel programs run asynchronously on a separate processor.
  78. - I/O completion will be signaled to the host with I/O interruptions.
  79. And it will be copied as IRB to user space to pass it back to the
  80. guest.
  81. Physical vfio ccw device and its child mdev
  82. -------------------------------------------
  83. As mentioned above, we realize vfio-ccw with a mdev implementation.
  84. Channel I/O does not have IOMMU hardware support, so the physical
  85. vfio-ccw device does not have an IOMMU level translation or isolation.
  86. Subchannel I/O instructions are all privileged instructions. When
  87. handling the I/O instruction interception, vfio-ccw has the software
  88. policing and translation how the channel program is programmed before
  89. it gets sent to hardware.
  90. Within this implementation, we have two drivers for two types of
  91. devices:
  92. - The vfio_ccw driver for the physical subchannel device.
  93. This is an I/O subchannel driver for the real subchannel device. It
  94. realizes a group of callbacks and registers to the mdev framework as a
  95. parent (physical) device. As a consequence, mdev provides vfio_ccw a
  96. generic interface (sysfs) to create mdev devices. A vfio mdev could be
  97. created by vfio_ccw then and added to the mediated bus. It is the vfio
  98. device that added to an IOMMU group and a vfio group.
  99. vfio_ccw also provides an I/O region to accept channel program
  100. request from user space and store I/O interrupt result for user
  101. space to retrieve. To notify user space an I/O completion, it offers
  102. an interface to setup an eventfd fd for asynchronous signaling.
  103. - The vfio_mdev driver for the mediated vfio ccw device.
  104. This is provided by the mdev framework. It is a vfio device driver for
  105. the mdev that created by vfio_ccw.
  106. It realizes a group of vfio device driver callbacks, adds itself to a
  107. vfio group, and registers itself to the mdev framework as a mdev
  108. driver.
  109. It uses a vfio iommu backend that uses the existing map and unmap
  110. ioctls, but rather than programming them into an IOMMU for a device,
  111. it simply stores the translations for use by later requests. This
  112. means that a device programmed in a VM with guest physical addresses
  113. can have the vfio kernel convert that address to process virtual
  114. address, pin the page and program the hardware with the host physical
  115. address in one step.
  116. For a mdev, the vfio iommu backend will not pin the pages during the
  117. VFIO_IOMMU_MAP_DMA ioctl. Mdev framework will only maintain a database
  118. of the iova<->vaddr mappings in this operation. And they export a
  119. vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu
  120. backend for the physical devices to pin and unpin pages by demand.
  121. Below is a high Level block diagram::
  122. +-------------+
  123. | |
  124. | +---------+ | mdev_register_driver() +--------------+
  125. | | Mdev | +<-----------------------+ |
  126. | | bus | | | vfio_mdev.ko |
  127. | | driver | +----------------------->+ |<-> VFIO user
  128. | +---------+ | probe()/remove() +--------------+ APIs
  129. | |
  130. | MDEV CORE |
  131. | MODULE |
  132. | mdev.ko |
  133. | +---------+ | mdev_register_device() +--------------+
  134. | |Physical | +<-----------------------+ |
  135. | | device | | | vfio_ccw.ko |<-> subchannel
  136. | |interface| +----------------------->+ | device
  137. | +---------+ | callback +--------------+
  138. +-------------+
  139. The process of how these work together.
  140. 1. vfio_ccw.ko drives the physical I/O subchannel, and registers the
  141. physical device (with callbacks) to mdev framework.
  142. When vfio_ccw probing the subchannel device, it registers device
  143. pointer and callbacks to the mdev framework. Mdev related file nodes
  144. under the device node in sysfs would be created for the subchannel
  145. device, namely 'mdev_create', 'mdev_destroy' and
  146. 'mdev_supported_types'.
  147. 2. Create a mediated vfio ccw device.
  148. Use the 'mdev_create' sysfs file, we need to manually create one (and
  149. only one for our case) mediated device.
  150. 3. vfio_mdev.ko drives the mediated ccw device.
  151. vfio_mdev is also the vfio device drvier. It will probe the mdev and
  152. add it to an iommu_group and a vfio_group. Then we could pass through
  153. the mdev to a guest.
  154. VFIO-CCW Regions
  155. ----------------
  156. The vfio-ccw driver exposes MMIO regions to accept requests from and return
  157. results to userspace.
  158. vfio-ccw I/O region
  159. -------------------
  160. An I/O region is used to accept channel program request from user
  161. space and store I/O interrupt result for user space to retrieve. The
  162. definition of the region is::
  163. struct ccw_io_region {
  164. #define ORB_AREA_SIZE 12
  165. __u8 orb_area[ORB_AREA_SIZE];
  166. #define SCSW_AREA_SIZE 12
  167. __u8 scsw_area[SCSW_AREA_SIZE];
  168. #define IRB_AREA_SIZE 96
  169. __u8 irb_area[IRB_AREA_SIZE];
  170. __u32 ret_code;
  171. } __packed;
  172. This region is always available.
  173. While starting an I/O request, orb_area should be filled with the
  174. guest ORB, and scsw_area should be filled with the SCSW of the Virtual
  175. Subchannel.
  176. irb_area stores the I/O result.
  177. ret_code stores a return code for each access of the region. The following
  178. values may occur:
  179. ``0``
  180. The operation was successful.
  181. ``-EOPNOTSUPP``
  182. The orb specified transport mode or an unidentified IDAW format, or the
  183. scsw specified a function other than the start function.
  184. ``-EIO``
  185. A request was issued while the device was not in a state ready to accept
  186. requests, or an internal error occurred.
  187. ``-EBUSY``
  188. The subchannel was status pending or busy, or a request is already active.
  189. ``-EAGAIN``
  190. A request was being processed, and the caller should retry.
  191. ``-EACCES``
  192. The channel path(s) used for the I/O were found to be not operational.
  193. ``-ENODEV``
  194. The device was found to be not operational.
  195. ``-EINVAL``
  196. The orb specified a chain longer than 255 ccws, or an internal error
  197. occurred.
  198. vfio-ccw cmd region
  199. -------------------
  200. The vfio-ccw cmd region is used to accept asynchronous instructions
  201. from userspace::
  202. #define VFIO_CCW_ASYNC_CMD_HSCH (1 << 0)
  203. #define VFIO_CCW_ASYNC_CMD_CSCH (1 << 1)
  204. struct ccw_cmd_region {
  205. __u32 command;
  206. __u32 ret_code;
  207. } __packed;
  208. This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD.
  209. Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region.
  210. command specifies the command to be issued; ret_code stores a return code
  211. for each access of the region. The following values may occur:
  212. ``0``
  213. The operation was successful.
  214. ``-ENODEV``
  215. The device was found to be not operational.
  216. ``-EINVAL``
  217. A command other than halt or clear was specified.
  218. ``-EIO``
  219. A request was issued while the device was not in a state ready to accept
  220. requests.
  221. ``-EAGAIN``
  222. A request was being processed, and the caller should retry.
  223. ``-EBUSY``
  224. The subchannel was status pending or busy while processing a halt request.
  225. vfio-ccw schib region
  226. ---------------------
  227. The vfio-ccw schib region is used to return Subchannel-Information
  228. Block (SCHIB) data to userspace::
  229. struct ccw_schib_region {
  230. #define SCHIB_AREA_SIZE 52
  231. __u8 schib_area[SCHIB_AREA_SIZE];
  232. } __packed;
  233. This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB.
  234. Reading this region triggers a STORE SUBCHANNEL to be issued to the
  235. associated hardware.
  236. vfio-ccw crw region
  237. ---------------------
  238. The vfio-ccw crw region is used to return Channel Report Word (CRW)
  239. data to userspace::
  240. struct ccw_crw_region {
  241. __u32 crw;
  242. __u32 pad;
  243. } __packed;
  244. This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_CRW.
  245. Reading this region returns a CRW if one that is relevant for this
  246. subchannel (e.g. one reporting changes in channel path state) is
  247. pending, or all zeroes if not. If multiple CRWs are pending (including
  248. possibly chained CRWs), reading this region again will return the next
  249. one, until no more CRWs are pending and zeroes are returned. This is
  250. similar to how STORE CHANNEL REPORT WORD works.
  251. vfio-ccw operation details
  252. --------------------------
  253. vfio-ccw follows what vfio-pci did on the s390 platform and uses
  254. vfio-iommu-type1 as the vfio iommu backend.
  255. * CCW translation APIs
  256. A group of APIs (start with `cp_`) to do CCW translation. The CCWs
  257. passed in by a user space program are organized with their guest
  258. physical memory addresses. These APIs will copy the CCWs into kernel
  259. space, and assemble a runnable kernel channel program by updating the
  260. guest physical addresses with their corresponding host physical addresses.
  261. Note that we have to use IDALs even for direct-access CCWs, as the
  262. referenced memory can be located anywhere, including above 2G.
  263. * vfio_ccw device driver
  264. This driver utilizes the CCW translation APIs and introduces
  265. vfio_ccw, which is the driver for the I/O subchannel devices you want
  266. to pass through.
  267. vfio_ccw implements the following vfio ioctls::
  268. VFIO_DEVICE_GET_INFO
  269. VFIO_DEVICE_GET_IRQ_INFO
  270. VFIO_DEVICE_GET_REGION_INFO
  271. VFIO_DEVICE_RESET
  272. VFIO_DEVICE_SET_IRQS
  273. This provides an I/O region, so that the user space program can pass a
  274. channel program to the kernel, to do further CCW translation before
  275. issuing them to a real device.
  276. This also provides the SET_IRQ ioctl to setup an event notifier to
  277. notify the user space program the I/O completion in an asynchronous
  278. way.
  279. The use of vfio-ccw is not limited to QEMU, while QEMU is definitely a
  280. good example to get understand how these patches work. Here is a little
  281. bit more detail how an I/O request triggered by the QEMU guest will be
  282. handled (without error handling).
  283. Explanation:
  284. - Q1-Q7: QEMU side process.
  285. - K1-K5: Kernel side process.
  286. Q1.
  287. Get I/O region info during initialization.
  288. Q2.
  289. Setup event notifier and handler to handle I/O completion.
  290. ... ...
  291. Q3.
  292. Intercept a ssch instruction.
  293. Q4.
  294. Write the guest channel program and ORB to the I/O region.
  295. K1.
  296. Copy from guest to kernel.
  297. K2.
  298. Translate the guest channel program to a host kernel space
  299. channel program, which becomes runnable for a real device.
  300. K3.
  301. With the necessary information contained in the orb passed in
  302. by QEMU, issue the ccwchain to the device.
  303. K4.
  304. Return the ssch CC code.
  305. Q5.
  306. Return the CC code to the guest.
  307. ... ...
  308. K5.
  309. Interrupt handler gets the I/O result and write the result to
  310. the I/O region.
  311. K6.
  312. Signal QEMU to retrieve the result.
  313. Q6.
  314. Get the signal and event handler reads out the result from the I/O
  315. region.
  316. Q7.
  317. Update the irb for the guest.
  318. Limitations
  319. -----------
  320. The current vfio-ccw implementation focuses on supporting basic commands
  321. needed to implement block device functionality (read/write) of DASD/ECKD
  322. device only. Some commands may need special handling in the future, for
  323. example, anything related to path grouping.
  324. DASD is a kind of storage device. While ECKD is a data recording format.
  325. More information for DASD and ECKD could be found here:
  326. https://en.wikipedia.org/wiki/Direct-access_storage_device
  327. https://en.wikipedia.org/wiki/Count_key_data
  328. Together with the corresponding work in QEMU, we can bring the passed
  329. through DASD/ECKD device online in a guest now and use it as a block
  330. device.
  331. The current code allows the guest to start channel programs via
  332. START SUBCHANNEL, and to issue HALT SUBCHANNEL, CLEAR SUBCHANNEL,
  333. and STORE SUBCHANNEL.
  334. Currently all channel programs are prefetched, regardless of the
  335. p-bit setting in the ORB. As a result, self modifying channel
  336. programs are not supported. For this reason, IPL has to be handled as
  337. a special case by a userspace/guest program; this has been implemented
  338. in QEMU's s390-ccw bios as of QEMU 4.1.
  339. vfio-ccw supports classic (command mode) channel I/O only. Transport
  340. mode (HPF) is not supported.
  341. QDIO subchannels are currently not supported. Classic devices other than
  342. DASD/ECKD might work, but have not been tested.
  343. Reference
  344. ---------
  345. 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)
  346. 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)
  347. 3. https://en.wikipedia.org/wiki/Channel_I/O
  348. 4. Documentation/s390/cds.rst
  349. 5. Documentation/driver-api/vfio.rst
  350. 6. Documentation/driver-api/vfio-mediated-device.rst