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