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
9 even if they aren't actually driven by ccws.
10
11 All ccw devices are accessed via a subchannel,
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 s
25 device 4711 via subchannel 1 in subchannel set
26 subchannel. Device 1234 is accessed via subcha
27
28 The subchannel named 'defunct' does not repres
29 system; it is a pseudo subchannel where discon
30 if they are displaced by another ccw device be
31 former subchannel. The ccw devices will be mov
32 if they become operational again on that subch
33
34 You should address a ccw device via its bus id
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 pa
47 disconnected devices.
48
49 online:
50 An interface to set the device onl
51 In the special case of the device
52 notify function under 1.2), piping
53 the device.
54
55 The device drivers can add entries to export p
56
57 There is also some data exported on a per-subc
58 bus/css/devices/):
59
60 chpids:
61 Via which chpids the device is connect
62
63 pimpampom:
64 The path installed, path available and
65
66 There also might be additional data, for examp
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 paramet
75 be specified. These interfaces are also in
76 b. After a. has been performed, if necessary,
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_dri
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 *de
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 *, in
107 struct device_driver driver;
108 char *name;
109 };
110
111 The 'private' field contains data needed for i
112 is not available to the device driver.
113
114 Each driver should declare in a MODULE_DEVICE_
115 and/or device types/models it is interested. T
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
130
131 probe:
132 This function is called by the device
133 is interested in. The driver should o
134 to put in dev->driver_data and create
135 the interrupt handler (see below) sho
136
137 ::
138
139 int (*probe) (struct ccw_device *cdev);
140
141 Parameters:
142 cdev
143 - the device to be pro
144
145
146 remove:
147 This function is called by the device
148 the device or the module. The driver
149
150 ::
151
152 int (*remove) (struct ccw_device *cdev);
153
154 Parameters:
155 cdev
156 - the device to be rem
157
158
159 set_online:
160 This function is called by the com
161 activated via the 'online' attribu
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 act
171 verified that the de
172
173
174 set_offline: This function is called by the co
175 de-activated via the 'online' att
176 down the device, but not de-alloc
177
178 ::
179
180 int (*set_offline) (struct ccw_device *);
181
182 Parameters:
183 cdev
184 - the device to be dea
185 verified that the d
186
187
188 notify:
189 This function is called by the common
190 of the device.
191
192 Signalled to the driver are:
193
194 * In online state, device detached (CI
195 (CIO_NO_PATH). The driver must retur
196 return code 0, the device will be de
197 notify function is registered). If t
198 device, it is moved into disconnecte
199 * In disconnected state, device operat
200 common I/O layer performs some sanit
201 Device / CU to be reasonably sure if
202 If not, the old device is removed an
203 return code of the notify function t
204 wants the device back: !0 for keepin
205 removed and re-registered.
206
207 ::
208
209 int (*notify) (struct ccw_device *, int);
210
211 Parameters:
212 cdev
213 - the device whose sta
214
215 event
216 - the event that happe
217 CIO_NO_PATH or CIO_O
218
219 The handler field of the struct ccw_device is
220 handler for the device. In order to accommodat
221 distinct handlers (e.g. multi subchannel devic
222 instead of ccw_driver.
223 The handler is registered with the common laye
224 before the driver is called, and is deregister
225 driver has been called. Also, after registerin
226 grouping resp. disbanding of the path group (i
227
228 ::
229
230 void (*handler) (struct ccw_device *dev, uns
231
232 Parameters: dev - the device the handl
233 intparm - the intparm which al
234 the i/o the interrup
235 the interrupt as uns
236 irb - interruption respons
237 status.
238
239 The device driver is called from the common cc
240 information about the interrupt from the irb p
241
242
243 1.3 ccwgroup devices
244 --------------------
245
246 The ccwgroup mechanism is designed to handle d
247 devices, like lcs or ctc.
248
249 The ccw driver provides a 'group' attribute. P
250 this attributes creates a ccwgroup device cons
251 possible). This ccwgroup device can be set onl
252 ccw device.
253
254 Each ccwgroup device also provides an 'ungroup
255 again (only when offline). This is a generic c
256 not need to implement anything beyond normal r
257
258 A ccw device which is a member of a ccwgroup d
259 ccwgroup device in the driver_data of its devi
260 touched by the driver - it should use the ccwg
261 private data.
262
263 To implement a ccwgroup driver, please refer t
264 mind that most drivers will need to implement
265 driver.
266
267
268 2. Channel paths
269 -----------------
270
271 Channel paths show up, like subchannels, under
272 and are called 'chp0.<chpid>'. They have no dr
273 Please note, that unlike /proc/chpids in 2.4,
274 only the logical state and not the physical st
275 latter consistently due to lacking machine sup
276 of it anyway).
277
278 status
279 - Can be 'online' or 'offline'.
280 Piping 'on' or 'off' sets the chpid l
281 Piping 'on' to an online chpid trigge
282 the chpid connects to. This can be us
283 a channel path the user knows to be o
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 dev
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 'conne
317 bus/iucv/drivers/netiucv. Piping to this attri
318 connection to the specified host.
319
320 Netiucv connections show up under devices/iucv
321 number is assigned sequentially to the connect
322 attribute.
323
324 user
325 - shows the connection partner.
326
327 buffer
328 - maximum buffer size. Pipe to it to chang
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.