1 =============================
2 S/390 driver model interfaces
3 =============================
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
11 All ccw devices are accessed via a subchannel, this is reflected in the
12 structures under devices/::
13
14 devices/
15 - system/
16 - css0/
17 - 0.0.0000/0.0.0815/
18 - 0.0.0001/0.0.4711/
19 - 0.0.0002/
20 - 0.1.0000/0.1.1234/
21 ...
22 - defunct/
23
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.
27
28 The subchannel named 'defunct' does not represent any real subchannel on the
29 system; it is a pseudo subchannel where disconnected ccw devices are moved to
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
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
39 cutype:
40 The control unit type / model.
41
42 devtype:
43 The device type / model, if applicable.
44
45 availability:
46 Can be 'good' or 'boxed'; 'no path' or 'no device' for
47 disconnected devices.
48
49 online:
50 An interface to set the device online and offline.
51 In the special case of the device being disconnected (see the
52 notify function under 1.2), piping 0 to online will forcibly delete
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
60 chpids:
61 Via which chpids the device is connected.
62
63 pimpampom:
64 The path installed, path available and path operational masks.
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
84 under include/asm/ccwdev.h::
85
86 struct ccw_device {
87 spinlock_t *ccwlock;
88 struct ccw_device_private *private;
89 struct ccw_device_id id;
90
91 struct ccw_driver *drv;
92 struct device dev;
93 int online;
94
95 void (*handler) (struct ccw_device *dev, unsigned long intparm,
96 struct irb *irb);
97 };
98
99 struct ccw_driver {
100 struct module *owner;
101 struct ccw_device_id *ids;
102 int (*probe) (struct ccw_device *);
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;
109 };
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
116 in the struct ccw_device_id fields::
117
118 struct ccw_device_id {
119 __u16 match_flags;
120
121 __u16 cu_type;
122 __u16 dev_type;
123 __u8 cu_model;
124 __u8 dev_model;
125
126 unsigned long driver_info;
127 };
128
129 The functions in ccw_driver should be used in the following way:
130
131 probe:
132 This function is called by the device layer for each device the driver
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
137 ::
138
139 int (*probe) (struct ccw_device *cdev);
140
141 Parameters:
142 cdev
143 - the device to be probed.
144
145
146 remove:
147 This function is called by the device layer upon removal of the driver,
148 the device or the module. The driver should perform cleanups here.
149
150 ::
151
152 int (*remove) (struct ccw_device *cdev);
153
154 Parameters:
155 cdev
156 - the device to be removed.
157
158
159 set_online:
160 This function is called by the common I/O layer when the device is
161 activated via the 'online' attribute. The driver should finally
162 setup and activate the device here.
163
164 ::
165
166 int (*set_online) (struct ccw_device *);
167
168 Parameters:
169 cdev
170 - the device to be activated. The common layer has
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
178 ::
179
180 int (*set_offline) (struct ccw_device *);
181
182 Parameters:
183 cdev
184 - the device to be deactivated. The common layer has
185 verified that the device is online.
186
187
188 notify:
189 This function is called by the common I/O layer for some state changes
190 of the device.
191
192 Signalled to the driver are:
193
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
197 notify function is registered). If the driver wants to keep the
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.
206
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.
218
219 The handler field of the struct ccw_device is meant to be set to the interrupt
220 handler for the device. In order to accommodate drivers which use several
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
225 driver has been called. Also, after registering / before deregistering, path
226 grouping resp. disbanding of the path group (if applicable) are performed.
227
228 ::
229
230 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
231
232 Parameters: dev - the device the handler is called for
233 intparm - the intparm which allows the device driver to identify
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.
238
239 The device driver is called from the common ccw_device layer and can retrieve
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
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
263 To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
264 mind that most drivers will need to implement both a ccwgroup and a ccw
265 driver.
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
276 of it anyway).
277
278 status
279 - Can be 'online' or 'offline'.
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
286 type
287 - The physical type of the channel path.
288
289 shared
290 - Whether the channel path is shared.
291
292 cmg
293 - The channel measurement group.
294
295 3. System devices
296 -----------------
297
298 3.1 xpram
299 ---------
300
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.
308
309
310 4. Other devices
311 ----------------
312
313 4.1 Netiucv
314 -----------
315
316 The netiucv driver creates an attribute 'connection' under
317 bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
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
324 user
325 - shows the connection partner.
326
327 buffer
328 - maximum buffer size. Pipe to it to change buffer size.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.