blob: ed265cf54cde70f20c98de6a7bfbffa1758f3cfb [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/
Cornelia Huckdc060102006-03-24 03:15:13 -080019 - 0.1.0000/0.1.1234/
Linus Torvalds1da177e2005-04-16 15:20:36 -070020 ...
Cornelia Huck7f090142006-12-08 15:56:02 +010021 - defunct/
Linus Torvalds1da177e2005-04-16 15:20:36 -070022
Cornelia Huckdc060102006-03-24 03:15:13 -080023In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
24device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
25subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
Linus Torvalds1da177e2005-04-16 15:20:36 -070026
Cornelia Huck7f090142006-12-08 15:56:02 +010027The subchannel named 'defunct' does not represent any real subchannel on the
Matt LaPlanted9195882008-07-25 19:45:33 -070028system; it is a pseudo subchannel where disconnected ccw devices are moved to
Cornelia Huck7f090142006-12-08 15:56:02 +010029if they are displaced by another ccw device becoming operational on their
30former subchannel. The ccw devices will be moved again to a proper subchannel
31if they become operational again on that subchannel.
32
Linus Torvalds1da177e2005-04-16 15:20:36 -070033You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
34be found under bus/ccw/devices/.
35
36All ccw devices export some data via sysfs.
37
38cutype: The control unit type / model.
39
40devtype: The device type / model, if applicable.
41
42availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
43 disconnected devices.
44
45online: An interface to set the device online and offline.
46 In the special case of the device being disconnected (see the
Cornelia Huck373c4912005-11-07 00:59:03 -080047 notify function under 1.2), piping 0 to online will forcibly delete
Linus Torvalds1da177e2005-04-16 15:20:36 -070048 the device.
49
50The device drivers can add entries to export per-device data and interfaces.
51
52There is also some data exported on a per-subchannel basis (see under
53bus/css/devices/):
54
55chpids: Via which chpids the device is connected.
56
57pimpampom: The path installed, path available and path operational masks.
58
59There also might be additional data, for example for block devices.
60
61
621.1 Bringing up a ccw device
63----------------------------
64
65This is done in several steps.
66
67a. Each driver can provide one or more parameter interfaces where parameters can
68 be specified. These interfaces are also in the driver's responsibility.
69b. After a. has been performed, if necessary, the device is finally brought up
70 via the 'online' interface.
71
72
731.2 Writing a driver for ccw devices
74------------------------------------
75
76The basic struct ccw_device and struct ccw_driver data structures can be found
77under include/asm/ccwdev.h.
78
79struct ccw_device {
80 spinlock_t *ccwlock;
81 struct ccw_device_private *private;
82 struct ccw_device_id id;
83
84 struct ccw_driver *drv;
85 struct device dev;
86 int online;
87
88 void (*handler) (struct ccw_device *dev, unsigned long intparm,
89 struct irb *irb);
90};
91
92struct ccw_driver {
93 struct module *owner;
94 struct ccw_device_id *ids;
95 int (*probe) (struct ccw_device *);
96 int (*remove) (struct ccw_device *);
97 int (*set_online) (struct ccw_device *);
98 int (*set_offline) (struct ccw_device *);
99 int (*notify) (struct ccw_device *, int);
100 struct device_driver driver;
101 char *name;
102};
103
104The 'private' field contains data needed for internal i/o operation only, and
105is not available to the device driver.
106
107Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
108and/or device types/models it is interested. This information can later be found
Cornelia Huckdc060102006-03-24 03:15:13 -0800109in the struct ccw_device_id fields:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110
111struct ccw_device_id {
112 __u16 match_flags;
113
114 __u16 cu_type;
115 __u16 dev_type;
116 __u8 cu_model;
117 __u8 dev_model;
118
119 unsigned long driver_info;
120};
121
122The functions in ccw_driver should be used in the following way:
123probe: This function is called by the device layer for each device the driver
124 is interested in. The driver should only allocate private structures
125 to put in dev->driver_data and create attributes (if needed). Also,
126 the interrupt handler (see below) should be set here.
127
128int (*probe) (struct ccw_device *cdev);
129
130Parameters: cdev - the device to be probed.
131
132
133remove: This function is called by the device layer upon removal of the driver,
134 the device or the module. The driver should perform cleanups here.
135
136int (*remove) (struct ccw_device *cdev);
137
138Parameters: cdev - the device to be removed.
139
140
141set_online: This function is called by the common I/O layer when the device is
142 activated via the 'online' attribute. The driver should finally
143 setup and activate the device here.
144
145int (*set_online) (struct ccw_device *);
146
147Parameters: cdev - the device to be activated. The common layer has
148 verified that the device is not already online.
149
150
151set_offline: This function is called by the common I/O layer when the device is
152 de-activated via the 'online' attribute. The driver should shut
153 down the device, but not de-allocate its private data.
154
155int (*set_offline) (struct ccw_device *);
156
157Parameters: cdev - the device to be deactivated. The common layer has
158 verified that the device is online.
159
160
161notify: This function is called by the common I/O layer for some state changes
162 of the device.
163 Signalled to the driver are:
164 * In online state, device detached (CIO_GONE) or last path gone
165 (CIO_NO_PATH). The driver must return !0 to keep the device; for
166 return code 0, the device will be deleted as usual (also when no
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +0200167 notify function is registered). If the driver wants to keep the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700168 device, it is moved into disconnected state.
169 * In disconnected state, device operational again (CIO_OPER). The
170 common I/O layer performs some sanity checks on device number and
171 Device / CU to be reasonably sure if it is still the same device.
172 If not, the old device is removed and a new one registered. By the
173 return code of the notify function the device driver signals if it
174 wants the device back: !0 for keeping, 0 to make the device being
175 removed and re-registered.
176
177int (*notify) (struct ccw_device *, int);
178
179Parameters: cdev - the device whose state changed.
180 event - the event that happened. This can be one of CIO_GONE,
181 CIO_NO_PATH or CIO_OPER.
182
183The handler field of the struct ccw_device is meant to be set to the interrupt
184handler for the device. In order to accommodate drivers which use several
185distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
186instead of ccw_driver.
187The handler is registered with the common layer during set_online() processing
188before the driver is called, and is deregistered during set_offline() after the
189driver has been called. Also, after registering / before deregistering, path
190grouping resp. disbanding of the path group (if applicable) are performed.
191
192void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
193
194Parameters: dev - the device the handler is called for
195 intparm - the intparm which allows the device driver to identify
196 the i/o the interrupt is associated with, or to recognize
197 the interrupt as unsolicited.
198 irb - interruption response block which contains the accumulated
199 status.
200
201The device driver is called from the common ccw_device layer and can retrieve
202information about the interrupt from the irb parameter.
203
204
2051.3 ccwgroup devices
206--------------------
207
208The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
209devices, like lcs or ctc.
210
211The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
212this attributes creates a ccwgroup device consisting of these ccw devices (if
213possible). This ccwgroup device can be set online or offline just like a normal
214ccw device.
215
216Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
217again (only when offline). This is a generic ccwgroup mechanism (the driver does
218not need to implement anything beyond normal removal routines).
219
Cornelia Huckdc060102006-03-24 03:15:13 -0800220A ccw device which is a member of a ccwgroup device carries a pointer to the
221ccwgroup device in the driver_data of its device struct. This field must not be
222touched by the driver - it should use the ccwgroup device's driver_data for its
223private data.
224
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
Ursula Braun6f5d09a2010-02-26 22:37:23 +0100226mind that most drivers will need to implement both a ccwgroup and a ccw
227driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700228
229
2302. Channel paths
231-----------------
232
233Channel paths show up, like subchannels, under the channel subsystem root (css0)
234and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
235Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
236only the logical state and not the physical state, since we cannot track the
237latter consistently due to lacking machine support (we don't need to be aware
Cornelia Huck373c4912005-11-07 00:59:03 -0800238of it anyway).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700239
240status - Can be 'online' or 'offline'.
241 Piping 'on' or 'off' sets the chpid logically online/offline.
242 Piping 'on' to an online chpid triggers path reprobing for all devices
243 the chpid connects to. This can be used to force the kernel to re-use
244 a channel path the user knows to be online, but the machine hasn't
245 created a machine check for.
246
Cornelia Huckdc060102006-03-24 03:15:13 -0800247type - The physical type of the channel path.
248
Cornelia Huck9b10fe52006-10-18 18:30:55 +0200249shared - Whether the channel path is shared.
250
251cmg - The channel measurement group.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700252
2533. System devices
254-----------------
255
Linus Torvalds1da177e2005-04-16 15:20:36 -07002563.1 xpram
257---------
258
Cornelia Huck373c4912005-11-07 00:59:03 -0800259xpram shows up under devices/system/ as 'xpram'.
260
2613.2 cpus
262--------
263
264For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
265attribute 'online' which can be 0 or 1.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700266
267
2684. Other devices
269----------------
270
2714.1 Netiucv
272-----------
273
274The netiucv driver creates an attribute 'connection' under
Matt LaPlante3f6dee92006-10-03 22:45:33 +0200275bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276connection to the specified host.
277
278Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
279number is assigned sequentially to the connections defined via the 'connection'
280attribute.
281
282user - shows the connection partner.
283
284buffer - maximum buffer size.
285 Pipe to it to change buffer size.
286
287