1 |
3 |
xianfeng |
S/390 driver model interfaces
|
2 |
|
|
-----------------------------
|
3 |
|
|
|
4 |
|
|
1. CCW devices
|
5 |
|
|
--------------
|
6 |
|
|
|
7 |
|
|
All devices which can be addressed by means of ccws are called 'CCW devices' -
|
8 |
|
|
even if they aren't actually driven by ccws.
|
9 |
|
|
|
10 |
|
|
All ccw devices are accessed via a subchannel, this is reflected in the
|
11 |
|
|
structures under devices/:
|
12 |
|
|
|
13 |
|
|
devices/
|
14 |
|
|
- system/
|
15 |
|
|
- css0/
|
16 |
|
|
- 0.0.0000/0.0.0815/
|
17 |
|
|
- 0.0.0001/0.0.4711/
|
18 |
|
|
- 0.0.0002/
|
19 |
|
|
- 0.1.0000/0.1.1234/
|
20 |
|
|
...
|
21 |
|
|
- defunct/
|
22 |
|
|
|
23 |
|
|
In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
|
24 |
|
|
device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
|
25 |
|
|
subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
|
26 |
|
|
|
27 |
|
|
The subchannel named 'defunct' does not represent any real subchannel on the
|
28 |
|
|
system; it is a pseudo subchannel where disconnnected ccw devices are moved to
|
29 |
|
|
if they are displaced by another ccw device becoming operational on their
|
30 |
|
|
former subchannel. The ccw devices will be moved again to a proper subchannel
|
31 |
|
|
if they become operational again on that subchannel.
|
32 |
|
|
|
33 |
|
|
You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
|
34 |
|
|
be found under bus/ccw/devices/.
|
35 |
|
|
|
36 |
|
|
All ccw devices export some data via sysfs.
|
37 |
|
|
|
38 |
|
|
cutype: The control unit type / model.
|
39 |
|
|
|
40 |
|
|
devtype: The device type / model, if applicable.
|
41 |
|
|
|
42 |
|
|
availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
|
43 |
|
|
disconnected devices.
|
44 |
|
|
|
45 |
|
|
online: An interface to set the device online and offline.
|
46 |
|
|
In the special case of the device being disconnected (see the
|
47 |
|
|
notify function under 1.2), piping 0 to online will forcibly delete
|
48 |
|
|
the device.
|
49 |
|
|
|
50 |
|
|
The device drivers can add entries to export per-device data and interfaces.
|
51 |
|
|
|
52 |
|
|
There is also some data exported on a per-subchannel basis (see under
|
53 |
|
|
bus/css/devices/):
|
54 |
|
|
|
55 |
|
|
chpids: Via which chpids the device is connected.
|
56 |
|
|
|
57 |
|
|
pimpampom: The path installed, path available and path operational masks.
|
58 |
|
|
|
59 |
|
|
There also might be additional data, for example for block devices.
|
60 |
|
|
|
61 |
|
|
|
62 |
|
|
1.1 Bringing up a ccw device
|
63 |
|
|
----------------------------
|
64 |
|
|
|
65 |
|
|
This is done in several steps.
|
66 |
|
|
|
67 |
|
|
a. Each driver can provide one or more parameter interfaces where parameters can
|
68 |
|
|
be specified. These interfaces are also in the driver's responsibility.
|
69 |
|
|
b. After a. has been performed, if necessary, the device is finally brought up
|
70 |
|
|
via the 'online' interface.
|
71 |
|
|
|
72 |
|
|
|
73 |
|
|
1.2 Writing a driver for ccw devices
|
74 |
|
|
------------------------------------
|
75 |
|
|
|
76 |
|
|
The basic struct ccw_device and struct ccw_driver data structures can be found
|
77 |
|
|
under include/asm/ccwdev.h.
|
78 |
|
|
|
79 |
|
|
struct 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 |
|
|
|
92 |
|
|
struct 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 |
|
|
|
104 |
|
|
The 'private' field contains data needed for internal i/o operation only, and
|
105 |
|
|
is not available to the device driver.
|
106 |
|
|
|
107 |
|
|
Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
|
108 |
|
|
and/or device types/models it is interested. This information can later be found
|
109 |
|
|
in the struct ccw_device_id fields:
|
110 |
|
|
|
111 |
|
|
struct 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 |
|
|
|
122 |
|
|
The functions in ccw_driver should be used in the following way:
|
123 |
|
|
probe: 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 |
|
|
|
128 |
|
|
int (*probe) (struct ccw_device *cdev);
|
129 |
|
|
|
130 |
|
|
Parameters: cdev - the device to be probed.
|
131 |
|
|
|
132 |
|
|
|
133 |
|
|
remove: 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 |
|
|
|
136 |
|
|
int (*remove) (struct ccw_device *cdev);
|
137 |
|
|
|
138 |
|
|
Parameters: cdev - the device to be removed.
|
139 |
|
|
|
140 |
|
|
|
141 |
|
|
set_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 |
|
|
|
145 |
|
|
int (*set_online) (struct ccw_device *);
|
146 |
|
|
|
147 |
|
|
Parameters: cdev - the device to be activated. The common layer has
|
148 |
|
|
verified that the device is not already online.
|
149 |
|
|
|
150 |
|
|
|
151 |
|
|
set_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 |
|
|
|
155 |
|
|
int (*set_offline) (struct ccw_device *);
|
156 |
|
|
|
157 |
|
|
Parameters: cdev - the device to be deactivated. The common layer has
|
158 |
|
|
verified that the device is online.
|
159 |
|
|
|
160 |
|
|
|
161 |
|
|
notify: 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
|
167 |
|
|
notify function is registered). If the driver wants to keep the
|
168 |
|
|
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 |
|
|
|
177 |
|
|
int (*notify) (struct ccw_device *, int);
|
178 |
|
|
|
179 |
|
|
Parameters: 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 |
|
|
|
183 |
|
|
The handler field of the struct ccw_device is meant to be set to the interrupt
|
184 |
|
|
handler for the device. In order to accommodate drivers which use several
|
185 |
|
|
distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
|
186 |
|
|
instead of ccw_driver.
|
187 |
|
|
The handler is registered with the common layer during set_online() processing
|
188 |
|
|
before the driver is called, and is deregistered during set_offline() after the
|
189 |
|
|
driver has been called. Also, after registering / before deregistering, path
|
190 |
|
|
grouping resp. disbanding of the path group (if applicable) are performed.
|
191 |
|
|
|
192 |
|
|
void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
|
193 |
|
|
|
194 |
|
|
Parameters: 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 |
|
|
|
201 |
|
|
The device driver is called from the common ccw_device layer and can retrieve
|
202 |
|
|
information about the interrupt from the irb parameter.
|
203 |
|
|
|
204 |
|
|
|
205 |
|
|
1.3 ccwgroup devices
|
206 |
|
|
--------------------
|
207 |
|
|
|
208 |
|
|
The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
|
209 |
|
|
devices, like lcs or ctc.
|
210 |
|
|
|
211 |
|
|
The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
|
212 |
|
|
this attributes creates a ccwgroup device consisting of these ccw devices (if
|
213 |
|
|
possible). This ccwgroup device can be set online or offline just like a normal
|
214 |
|
|
ccw device.
|
215 |
|
|
|
216 |
|
|
Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
|
217 |
|
|
again (only when offline). This is a generic ccwgroup mechanism (the driver does
|
218 |
|
|
not need to implement anything beyond normal removal routines).
|
219 |
|
|
|
220 |
|
|
A ccw device which is a member of a ccwgroup device carries a pointer to the
|
221 |
|
|
ccwgroup device in the driver_data of its device struct. This field must not be
|
222 |
|
|
touched by the driver - it should use the ccwgroup device's driver_data for its
|
223 |
|
|
private data.
|
224 |
|
|
|
225 |
|
|
To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
|
226 |
|
|
mind that most drivers will need to implement both a ccwgroup and a ccw driver
|
227 |
|
|
(unless you have a meta ccw driver, like cu3088 for lcs and ctc).
|
228 |
|
|
|
229 |
|
|
|
230 |
|
|
2. Channel paths
|
231 |
|
|
-----------------
|
232 |
|
|
|
233 |
|
|
Channel paths show up, like subchannels, under the channel subsystem root (css0)
|
234 |
|
|
and are called 'chp0.'. They have no driver and do not belong to any bus.
|
235 |
|
|
Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
|
236 |
|
|
only the logical state and not the physical state, since we cannot track the
|
237 |
|
|
latter consistently due to lacking machine support (we don't need to be aware
|
238 |
|
|
of it anyway).
|
239 |
|
|
|
240 |
|
|
status - 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 |
|
|
|
247 |
|
|
type - The physical type of the channel path.
|
248 |
|
|
|
249 |
|
|
shared - Whether the channel path is shared.
|
250 |
|
|
|
251 |
|
|
cmg - The channel measurement group.
|
252 |
|
|
|
253 |
|
|
3. System devices
|
254 |
|
|
-----------------
|
255 |
|
|
|
256 |
|
|
3.1 xpram
|
257 |
|
|
---------
|
258 |
|
|
|
259 |
|
|
xpram shows up under devices/system/ as 'xpram'.
|
260 |
|
|
|
261 |
|
|
3.2 cpus
|
262 |
|
|
--------
|
263 |
|
|
|
264 |
|
|
For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
|
265 |
|
|
attribute 'online' which can be 0 or 1.
|
266 |
|
|
|
267 |
|
|
|
268 |
|
|
4. Other devices
|
269 |
|
|
----------------
|
270 |
|
|
|
271 |
|
|
4.1 Netiucv
|
272 |
|
|
-----------
|
273 |
|
|
|
274 |
|
|
The netiucv driver creates an attribute 'connection' under
|
275 |
|
|
bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
|
276 |
|
|
connection to the specified host.
|
277 |
|
|
|
278 |
|
|
Netiucv connections show up under devices/iucv/ as "netiucv". The interface
|
279 |
|
|
number is assigned sequentially to the connections defined via the 'connection'
|
280 |
|
|
attribute.
|
281 |
|
|
|
282 |
|
|
user - shows the connection partner.
|
283 |
|
|
|
284 |
|
|
buffer - maximum buffer size.
|
285 |
|
|
Pipe to it to change buffer size.
|
286 |
|
|
|
287 |
|
|
|