Commit | Line | Data |
---|---|---|
8b4a503d | 1 | ============================= |
1da177e4 | 2 | S/390 driver model interfaces |
8b4a503d | 3 | ============================= |
1da177e4 LT |
4 | |
5 | 1. CCW devices | |
6 | -------------- | |
7 | ||
8 | All devices which can be addressed by means of ccws are called 'CCW devices' - | |
9 | even if they aren't actually driven by ccws. | |
10 | ||
8b4a503d MCC |
11 | All ccw devices are accessed via a subchannel, this is reflected in the |
12 | structures under devices/:: | |
1da177e4 | 13 | |
8b4a503d | 14 | devices/ |
373c491f | 15 | - system/ |
1da177e4 | 16 | - css0/ |
8b4a503d | 17 | - 0.0.0000/0.0.0815/ |
1da177e4 LT |
18 | - 0.0.0001/0.0.4711/ |
19 | - 0.0.0002/ | |
dc06010c | 20 | - 0.1.0000/0.1.1234/ |
1da177e4 | 21 | ... |
7f090145 | 22 | - defunct/ |
1da177e4 | 23 | |
dc06010c CH |
24 | In this example, device 0815 is accessed via subchannel 0 in subchannel set 0, |
25 | device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O | |
26 | subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1. | |
1da177e4 | 27 | |
7f090145 | 28 | The subchannel named 'defunct' does not represent any real subchannel on the |
d9195881 | 29 | system; it is a pseudo subchannel where disconnected ccw devices are moved to |
7f090145 CH |
30 | if they are displaced by another ccw device becoming operational on their |
31 | former subchannel. The ccw devices will be moved again to a proper subchannel | |
32 | if they become operational again on that subchannel. | |
33 | ||
1da177e4 LT |
34 | You should address a ccw device via its bus id (e.g. 0.0.4711); the device can |
35 | be found under bus/ccw/devices/. | |
36 | ||
37 | All ccw devices export some data via sysfs. | |
38 | ||
8b4a503d MCC |
39 | cutype: |
40 | The control unit type / model. | |
1da177e4 | 41 | |
8b4a503d MCC |
42 | devtype: |
43 | The device type / model, if applicable. | |
1da177e4 | 44 | |
8b4a503d MCC |
45 | availability: |
46 | Can be 'good' or 'boxed'; 'no path' or 'no device' for | |
1da177e4 LT |
47 | disconnected devices. |
48 | ||
8b4a503d MCC |
49 | online: |
50 | An interface to set the device online and offline. | |
1da177e4 | 51 | In the special case of the device being disconnected (see the |
373c491f | 52 | notify function under 1.2), piping 0 to online will forcibly delete |
1da177e4 LT |
53 | the device. |
54 | ||
55 | The device drivers can add entries to export per-device data and interfaces. | |
56 | ||
57 | There is also some data exported on a per-subchannel basis (see under | |
58 | bus/css/devices/): | |
59 | ||
8b4a503d MCC |
60 | chpids: |
61 | Via which chpids the device is connected. | |
1da177e4 | 62 | |
8b4a503d MCC |
63 | pimpampom: |
64 | The path installed, path available and path operational masks. | |
1da177e4 LT |
65 | |
66 | There also might be additional data, for example for block devices. | |
67 | ||
68 | ||
69 | 1.1 Bringing up a ccw device | |
70 | ---------------------------- | |
71 | ||
72 | This is done in several steps. | |
73 | ||
74 | a. Each driver can provide one or more parameter interfaces where parameters can | |
75 | be specified. These interfaces are also in the driver's responsibility. | |
76 | b. After a. has been performed, if necessary, the device is finally brought up | |
77 | via the 'online' interface. | |
78 | ||
79 | ||
80 | 1.2 Writing a driver for ccw devices | |
81 | ------------------------------------ | |
82 | ||
83 | The basic struct ccw_device and struct ccw_driver data structures can be found | |
8b4a503d | 84 | under include/asm/ccwdev.h:: |
1da177e4 | 85 | |
8b4a503d MCC |
86 | struct ccw_device { |
87 | spinlock_t *ccwlock; | |
88 | struct ccw_device_private *private; | |
89 | struct ccw_device_id id; | |
1da177e4 | 90 | |
8b4a503d MCC |
91 | struct ccw_driver *drv; |
92 | struct device dev; | |
1da177e4 LT |
93 | int online; |
94 | ||
95 | void (*handler) (struct ccw_device *dev, unsigned long intparm, | |
8b4a503d MCC |
96 | struct irb *irb); |
97 | }; | |
1da177e4 | 98 | |
8b4a503d MCC |
99 | struct ccw_driver { |
100 | struct module *owner; | |
101 | struct ccw_device_id *ids; | |
102 | int (*probe) (struct ccw_device *); | |
1da177e4 LT |
103 | int (*remove) (struct ccw_device *); |
104 | int (*set_online) (struct ccw_device *); | |
105 | int (*set_offline) (struct ccw_device *); | |
106 | int (*notify) (struct ccw_device *, int); | |
107 | struct device_driver driver; | |
108 | char *name; | |
8b4a503d | 109 | }; |
1da177e4 LT |
110 | |
111 | The 'private' field contains data needed for internal i/o operation only, and | |
112 | is not available to the device driver. | |
113 | ||
114 | Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models | |
115 | and/or device types/models it is interested. This information can later be found | |
8b4a503d | 116 | in the struct ccw_device_id fields:: |
1da177e4 | 117 | |
8b4a503d MCC |
118 | struct ccw_device_id { |
119 | __u16 match_flags; | |
1da177e4 | 120 | |
8b4a503d MCC |
121 | __u16 cu_type; |
122 | __u16 dev_type; | |
123 | __u8 cu_model; | |
124 | __u8 dev_model; | |
1da177e4 LT |
125 | |
126 | unsigned long driver_info; | |
8b4a503d | 127 | }; |
1da177e4 LT |
128 | |
129 | The functions in ccw_driver should be used in the following way: | |
8b4a503d MCC |
130 | |
131 | probe: | |
132 | This function is called by the device layer for each device the driver | |
1da177e4 LT |
133 | is interested in. The driver should only allocate private structures |
134 | to put in dev->driver_data and create attributes (if needed). Also, | |
135 | the interrupt handler (see below) should be set here. | |
136 | ||
8b4a503d MCC |
137 | :: |
138 | ||
139 | int (*probe) (struct ccw_device *cdev); | |
1da177e4 | 140 | |
8b4a503d MCC |
141 | Parameters: |
142 | cdev | |
143 | - the device to be probed. | |
1da177e4 LT |
144 | |
145 | ||
8b4a503d MCC |
146 | remove: |
147 | This function is called by the device layer upon removal of the driver, | |
1da177e4 LT |
148 | the device or the module. The driver should perform cleanups here. |
149 | ||
8b4a503d | 150 | :: |
1da177e4 | 151 | |
8b4a503d | 152 | int (*remove) (struct ccw_device *cdev); |
1da177e4 | 153 | |
8b4a503d MCC |
154 | Parameters: |
155 | cdev | |
156 | - the device to be removed. | |
1da177e4 | 157 | |
8b4a503d MCC |
158 | |
159 | set_online: | |
160 | This function is called by the common I/O layer when the device is | |
1da177e4 LT |
161 | activated via the 'online' attribute. The driver should finally |
162 | setup and activate the device here. | |
163 | ||
8b4a503d MCC |
164 | :: |
165 | ||
166 | int (*set_online) (struct ccw_device *); | |
1da177e4 | 167 | |
8b4a503d MCC |
168 | Parameters: |
169 | cdev | |
170 | - the device to be activated. The common layer has | |
1da177e4 LT |
171 | verified that the device is not already online. |
172 | ||
173 | ||
174 | set_offline: This function is called by the common I/O layer when the device is | |
175 | de-activated via the 'online' attribute. The driver should shut | |
176 | down the device, but not de-allocate its private data. | |
177 | ||
8b4a503d | 178 | :: |
1da177e4 | 179 | |
8b4a503d MCC |
180 | int (*set_offline) (struct ccw_device *); |
181 | ||
182 | Parameters: | |
183 | cdev | |
184 | - the device to be deactivated. The common layer has | |
1da177e4 LT |
185 | verified that the device is online. |
186 | ||
187 | ||
8b4a503d MCC |
188 | notify: |
189 | This function is called by the common I/O layer for some state changes | |
1da177e4 | 190 | of the device. |
8b4a503d | 191 | |
1da177e4 | 192 | Signalled to the driver are: |
8b4a503d | 193 | |
1da177e4 LT |
194 | * In online state, device detached (CIO_GONE) or last path gone |
195 | (CIO_NO_PATH). The driver must return !0 to keep the device; for | |
196 | return code 0, the device will be deleted as usual (also when no | |
d6bc8ac9 | 197 | notify function is registered). If the driver wants to keep the |
1da177e4 LT |
198 | device, it is moved into disconnected state. |
199 | * In disconnected state, device operational again (CIO_OPER). The | |
200 | common I/O layer performs some sanity checks on device number and | |
201 | Device / CU to be reasonably sure if it is still the same device. | |
202 | If not, the old device is removed and a new one registered. By the | |
203 | return code of the notify function the device driver signals if it | |
204 | wants the device back: !0 for keeping, 0 to make the device being | |
205 | removed and re-registered. | |
1da177e4 | 206 | |
8b4a503d MCC |
207 | :: |
208 | ||
209 | int (*notify) (struct ccw_device *, int); | |
210 | ||
211 | Parameters: | |
212 | cdev | |
213 | - the device whose state changed. | |
214 | ||
215 | event | |
216 | - the event that happened. This can be one of CIO_GONE, | |
217 | CIO_NO_PATH or CIO_OPER. | |
1da177e4 LT |
218 | |
219 | The handler field of the struct ccw_device is meant to be set to the interrupt | |
8b4a503d | 220 | handler for the device. In order to accommodate drivers which use several |
1da177e4 LT |
221 | distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device |
222 | instead of ccw_driver. | |
223 | The handler is registered with the common layer during set_online() processing | |
224 | before the driver is called, and is deregistered during set_offline() after the | |
8b4a503d | 225 | driver has been called. Also, after registering / before deregistering, path |
1da177e4 LT |
226 | grouping resp. disbanding of the path group (if applicable) are performed. |
227 | ||
8b4a503d | 228 | :: |
1da177e4 | 229 | |
8b4a503d MCC |
230 | void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb); |
231 | ||
232 | Parameters: dev - the device the handler is called for | |
1da177e4 | 233 | intparm - the intparm which allows the device driver to identify |
8b4a503d MCC |
234 | the i/o the interrupt is associated with, or to recognize |
235 | the interrupt as unsolicited. | |
236 | irb - interruption response block which contains the accumulated | |
237 | status. | |
1da177e4 | 238 | |
8b4a503d | 239 | The device driver is called from the common ccw_device layer and can retrieve |
1da177e4 LT |
240 | information about the interrupt from the irb parameter. |
241 | ||
242 | ||
243 | 1.3 ccwgroup devices | |
244 | -------------------- | |
245 | ||
246 | The ccwgroup mechanism is designed to handle devices consisting of multiple ccw | |
247 | devices, like lcs or ctc. | |
248 | ||
249 | The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to | |
250 | this attributes creates a ccwgroup device consisting of these ccw devices (if | |
251 | possible). This ccwgroup device can be set online or offline just like a normal | |
252 | ccw device. | |
253 | ||
254 | Each ccwgroup device also provides an 'ungroup' attribute to destroy the device | |
255 | again (only when offline). This is a generic ccwgroup mechanism (the driver does | |
256 | not need to implement anything beyond normal removal routines). | |
257 | ||
dc06010c CH |
258 | A ccw device which is a member of a ccwgroup device carries a pointer to the |
259 | ccwgroup device in the driver_data of its device struct. This field must not be | |
260 | touched by the driver - it should use the ccwgroup device's driver_data for its | |
261 | private data. | |
262 | ||
1da177e4 | 263 | To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in |
6f5d09a0 UB |
264 | mind that most drivers will need to implement both a ccwgroup and a ccw |
265 | driver. | |
1da177e4 LT |
266 | |
267 | ||
268 | 2. Channel paths | |
269 | ----------------- | |
270 | ||
271 | Channel paths show up, like subchannels, under the channel subsystem root (css0) | |
272 | and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus. | |
273 | Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect | |
274 | only the logical state and not the physical state, since we cannot track the | |
275 | latter consistently due to lacking machine support (we don't need to be aware | |
373c491f | 276 | of it anyway). |
1da177e4 | 277 | |
8b4a503d MCC |
278 | status |
279 | - Can be 'online' or 'offline'. | |
1da177e4 LT |
280 | Piping 'on' or 'off' sets the chpid logically online/offline. |
281 | Piping 'on' to an online chpid triggers path reprobing for all devices | |
282 | the chpid connects to. This can be used to force the kernel to re-use | |
283 | a channel path the user knows to be online, but the machine hasn't | |
284 | created a machine check for. | |
285 | ||
8b4a503d MCC |
286 | type |
287 | - The physical type of the channel path. | |
dc06010c | 288 | |
8b4a503d MCC |
289 | shared |
290 | - Whether the channel path is shared. | |
9b10fe5b | 291 | |
8b4a503d MCC |
292 | cmg |
293 | - The channel measurement group. | |
1da177e4 LT |
294 | |
295 | 3. System devices | |
296 | ----------------- | |
297 | ||
8b4a503d | 298 | 3.1 xpram |
1da177e4 LT |
299 | --------- |
300 | ||
373c491f CH |
301 | xpram shows up under devices/system/ as 'xpram'. |
302 | ||
303 | 3.2 cpus | |
304 | -------- | |
305 | ||
306 | For each cpu, a directory is created under devices/system/cpu/. Each cpu has an | |
307 | attribute 'online' which can be 0 or 1. | |
1da177e4 LT |
308 | |
309 | ||
310 | 4. Other devices | |
311 | ---------------- | |
312 | ||
313 | 4.1 Netiucv | |
314 | ----------- | |
315 | ||
316 | The netiucv driver creates an attribute 'connection' under | |
3f6dee9b | 317 | bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv |
1da177e4 LT |
318 | connection to the specified host. |
319 | ||
320 | Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface | |
321 | number is assigned sequentially to the connections defined via the 'connection' | |
322 | attribute. | |
323 | ||
8b4a503d MCC |
324 | user |
325 | - shows the connection partner. | |
1da177e4 | 326 | |
8b4a503d MCC |
327 | buffer |
328 | - maximum buffer size. Pipe to it to change buffer size. |