Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 1 | =================================== |
| 2 | Writing s390 channel device drivers |
| 3 | =================================== |
| 4 | |
| 5 | :Author: Cornelia Huck |
| 6 | |
| 7 | Introduction |
| 8 | ============ |
| 9 | |
| 10 | This document describes the interfaces available for device drivers that |
| 11 | drive s390 based channel attached I/O devices. This includes interfaces |
| 12 | for interaction with the hardware and interfaces for interacting with |
| 13 | the common driver core. Those interfaces are provided by the s390 common |
| 14 | I/O layer. |
| 15 | |
| 16 | The document assumes a familarity with the technical terms associated |
| 17 | with the s390 channel I/O architecture. For a description of this |
| 18 | architecture, please refer to the "z/Architecture: Principles of |
| 19 | Operation", IBM publication no. SA22-7832. |
| 20 | |
| 21 | While most I/O devices on a s390 system are typically driven through the |
| 22 | channel I/O mechanism described here, there are various other methods |
| 23 | (like the diag interface). These are out of the scope of this document. |
| 24 | |
Cornelia Huck | 7ddd091 | 2017-07-11 15:44:09 +0200 | [diff] [blame] | 25 | The s390 common I/O layer also provides access to some devices that are |
| 26 | not strictly considered I/O devices. They are considered here as well, |
| 27 | although they are not the focus of this document. |
| 28 | |
Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 29 | Some additional information can also be found in the kernel source under |
Mauro Carvalho Chehab | 8b4a503 | 2019-06-08 23:27:16 -0300 | [diff] [blame] | 30 | Documentation/s390/driver-model.rst. |
Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 31 | |
Cornelia Huck | 7ddd091 | 2017-07-11 15:44:09 +0200 | [diff] [blame] | 32 | The css bus |
| 33 | =========== |
| 34 | |
| 35 | The css bus contains the subchannels available on the system. They fall |
| 36 | into several categories: |
| 37 | |
| 38 | * Standard I/O subchannels, for use by the system. They have a child |
| 39 | device on the ccw bus and are described below. |
| 40 | * I/O subchannels bound to the vfio-ccw driver. See |
Mauro Carvalho Chehab | 8b4a503 | 2019-06-08 23:27:16 -0300 | [diff] [blame] | 41 | Documentation/s390/vfio-ccw.rst. |
Cornelia Huck | 7ddd091 | 2017-07-11 15:44:09 +0200 | [diff] [blame] | 42 | * Message subchannels. No Linux driver currently exists. |
| 43 | * CHSC subchannels (at most one). The chsc subchannel driver can be used |
| 44 | to send asynchronous chsc commands. |
| 45 | * eADM subchannels. Used for talking to storage class memory. |
| 46 | |
Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 47 | The ccw bus |
| 48 | =========== |
| 49 | |
| 50 | The ccw bus typically contains the majority of devices available to a |
| 51 | s390 system. Named after the channel command word (ccw), the basic |
| 52 | command structure used to address its devices, the ccw bus contains |
| 53 | so-called channel attached devices. They are addressed via I/O |
| 54 | subchannels, visible on the css bus. A device driver for |
| 55 | channel-attached devices, however, will never interact with the |
| 56 | subchannel directly, but only via the I/O device on the ccw bus, the ccw |
| 57 | device. |
| 58 | |
| 59 | I/O functions for channel-attached devices |
| 60 | ------------------------------------------ |
| 61 | |
| 62 | Some hardware structures have been translated into C structures for use |
| 63 | by the common I/O layer and device drivers. For more information on the |
| 64 | hardware structures represented here, please consult the Principles of |
| 65 | Operation. |
| 66 | |
| 67 | .. kernel-doc:: arch/s390/include/asm/cio.h |
| 68 | :internal: |
| 69 | |
| 70 | ccw devices |
| 71 | ----------- |
| 72 | |
| 73 | Devices that want to initiate channel I/O need to attach to the ccw bus. |
| 74 | Interaction with the driver core is done via the common I/O layer, which |
| 75 | provides the abstractions of ccw devices and ccw device drivers. |
| 76 | |
| 77 | The functions that initiate or terminate channel I/O all act upon a ccw |
| 78 | device structure. Device drivers must not bypass those functions or |
| 79 | strange side effects may happen. |
| 80 | |
| 81 | .. kernel-doc:: arch/s390/include/asm/ccwdev.h |
| 82 | :internal: |
| 83 | |
| 84 | .. kernel-doc:: drivers/s390/cio/device.c |
| 85 | :export: |
| 86 | |
| 87 | .. kernel-doc:: drivers/s390/cio/device_ops.c |
| 88 | :export: |
| 89 | |
| 90 | The channel-measurement facility |
| 91 | -------------------------------- |
| 92 | |
| 93 | The channel-measurement facility provides a means to collect measurement |
| 94 | data which is made available by the channel subsystem for each channel |
| 95 | attached device. |
| 96 | |
Jonathan Corbet | 405d4c5 | 2017-07-17 14:19:25 -0600 | [diff] [blame] | 97 | .. kernel-doc:: arch/s390/include/uapi/asm/cmb.h |
Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 98 | :internal: |
| 99 | |
| 100 | .. kernel-doc:: drivers/s390/cio/cmf.c |
| 101 | :export: |
| 102 | |
| 103 | The ccwgroup bus |
| 104 | ================ |
| 105 | |
| 106 | The ccwgroup bus only contains artificial devices, created by the user. |
| 107 | Many networking devices (e.g. qeth) are in fact composed of several ccw |
| 108 | devices (like read, write and data channel for qeth). The ccwgroup bus |
| 109 | provides a mechanism to create a meta-device which contains those ccw |
| 110 | devices as slave devices and can be associated with the netdevice. |
| 111 | |
| 112 | ccw group devices |
| 113 | ----------------- |
| 114 | |
| 115 | .. kernel-doc:: arch/s390/include/asm/ccwgroup.h |
| 116 | :internal: |
| 117 | |
| 118 | .. kernel-doc:: drivers/s390/cio/ccwgroup.c |
| 119 | :export: |
| 120 | |
| 121 | Generic interfaces |
| 122 | ================== |
| 123 | |
Cornelia Huck | 0f0929b | 2017-07-11 16:04:45 +0200 | [diff] [blame] | 124 | The following section contains interfaces in use not only by drivers |
| 125 | dealing with ccw devices, but drivers for various other s390 hardware |
| 126 | as well. |
| 127 | |
| 128 | Adapter interrupts |
| 129 | ------------------ |
| 130 | |
| 131 | The common I/O layer provides helper functions for dealing with adapter |
| 132 | interrupts and interrupt vectors. |
Mauro Carvalho Chehab | bcb1a87 | 2017-05-12 08:57:50 -0300 | [diff] [blame] | 133 | |
| 134 | .. kernel-doc:: drivers/s390/cio/airq.c |
| 135 | :export: |