Commit | Line | Data |
---|---|---|
bcb1a87a MCC |
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 | ||
7ddd0913 CH |
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 | ||
bcb1a87a | 29 | Some additional information can also be found in the kernel source under |
8b4a503d | 30 | Documentation/s390/driver-model.rst. |
bcb1a87a | 31 | |
7ddd0913 CH |
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 | |
8b4a503d | 41 | Documentation/s390/vfio-ccw.rst. |
7ddd0913 CH |
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 | ||
bcb1a87a MCC |
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 | ||
405d4c5a | 97 | .. kernel-doc:: arch/s390/include/uapi/asm/cmb.h |
bcb1a87a MCC |
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 | ||
0f0929bc CH |
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. | |
bcb1a87a MCC |
133 | |
134 | .. kernel-doc:: drivers/s390/cio/airq.c | |
135 | :export: |