]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | 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 | |
373c491f | 11 | structures under devices/: |
1da177e4 | 12 | |
373c491f CH |
13 | devices/ |
14 | - system/ | |
1da177e4 LT |
15 | - css0/ |
16 | - 0.0.0000/0.0.0815/ | |
17 | - 0.0.0001/0.0.4711/ | |
18 | - 0.0.0002/ | |
19 | ... | |
20 | ||
21 | In this example, device 0815 is accessed via subchannel 0, device 4711 via | |
22 | subchannel 1, and subchannel 2 is a non-I/O subchannel. | |
23 | ||
24 | You should address a ccw device via its bus id (e.g. 0.0.4711); the device can | |
25 | be found under bus/ccw/devices/. | |
26 | ||
27 | All ccw devices export some data via sysfs. | |
28 | ||
29 | cutype: The control unit type / model. | |
30 | ||
31 | devtype: The device type / model, if applicable. | |
32 | ||
33 | availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for | |
34 | disconnected devices. | |
35 | ||
36 | online: An interface to set the device online and offline. | |
37 | In the special case of the device being disconnected (see the | |
373c491f | 38 | notify function under 1.2), piping 0 to online will forcibly delete |
1da177e4 LT |
39 | the device. |
40 | ||
41 | The device drivers can add entries to export per-device data and interfaces. | |
42 | ||
43 | There is also some data exported on a per-subchannel basis (see under | |
44 | bus/css/devices/): | |
45 | ||
46 | chpids: Via which chpids the device is connected. | |
47 | ||
48 | pimpampom: The path installed, path available and path operational masks. | |
49 | ||
50 | There also might be additional data, for example for block devices. | |
51 | ||
52 | ||
53 | 1.1 Bringing up a ccw device | |
54 | ---------------------------- | |
55 | ||
56 | This is done in several steps. | |
57 | ||
58 | a. Each driver can provide one or more parameter interfaces where parameters can | |
59 | be specified. These interfaces are also in the driver's responsibility. | |
60 | b. After a. has been performed, if necessary, the device is finally brought up | |
61 | via the 'online' interface. | |
62 | ||
63 | ||
64 | 1.2 Writing a driver for ccw devices | |
65 | ------------------------------------ | |
66 | ||
67 | The basic struct ccw_device and struct ccw_driver data structures can be found | |
68 | under include/asm/ccwdev.h. | |
69 | ||
70 | struct 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 | ||
83 | struct 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 | ||
95 | The 'private' field contains data needed for internal i/o operation only, and | |
96 | is not available to the device driver. | |
97 | ||
98 | Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models | |
99 | and/or device types/models it is interested. This information can later be found | |
100 | found in the struct ccw_device_id fields: | |
101 | ||
102 | struct 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 | ||
113 | The functions in ccw_driver should be used in the following way: | |
114 | probe: 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 | ||
119 | int (*probe) (struct ccw_device *cdev); | |
120 | ||
121 | Parameters: cdev - the device to be probed. | |
122 | ||
123 | ||
124 | remove: 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 | ||
127 | int (*remove) (struct ccw_device *cdev); | |
128 | ||
129 | Parameters: cdev - the device to be removed. | |
130 | ||
131 | ||
132 | set_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 | ||
136 | int (*set_online) (struct ccw_device *); | |
137 | ||
138 | Parameters: cdev - the device to be activated. The common layer has | |
139 | verified that the device is not already online. | |
140 | ||
141 | ||
142 | set_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 | ||
146 | int (*set_offline) (struct ccw_device *); | |
147 | ||
148 | Parameters: cdev - the device to be deactivated. The common layer has | |
149 | verified that the device is online. | |
150 | ||
151 | ||
152 | notify: 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 | ||
168 | int (*notify) (struct ccw_device *, int); | |
169 | ||
170 | Parameters: 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 | ||
174 | The handler field of the struct ccw_device is meant to be set to the interrupt | |
175 | handler for the device. In order to accommodate drivers which use several | |
176 | distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device | |
177 | instead of ccw_driver. | |
178 | The handler is registered with the common layer during set_online() processing | |
179 | before the driver is called, and is deregistered during set_offline() after the | |
180 | driver has been called. Also, after registering / before deregistering, path | |
181 | grouping resp. disbanding of the path group (if applicable) are performed. | |
182 | ||
183 | void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb); | |
184 | ||
185 | Parameters: 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 | ||
192 | The device driver is called from the common ccw_device layer and can retrieve | |
193 | information about the interrupt from the irb parameter. | |
194 | ||
195 | ||
196 | 1.3 ccwgroup devices | |
197 | -------------------- | |
198 | ||
199 | The ccwgroup mechanism is designed to handle devices consisting of multiple ccw | |
200 | devices, like lcs or ctc. | |
201 | ||
202 | The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to | |
203 | this attributes creates a ccwgroup device consisting of these ccw devices (if | |
204 | possible). This ccwgroup device can be set online or offline just like a normal | |
205 | ccw device. | |
206 | ||
207 | Each ccwgroup device also provides an 'ungroup' attribute to destroy the device | |
208 | again (only when offline). This is a generic ccwgroup mechanism (the driver does | |
209 | not need to implement anything beyond normal removal routines). | |
210 | ||
211 | To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in | |
212 | mind 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 | ||
216 | 2. Channel paths | |
217 | ----------------- | |
218 | ||
219 | Channel paths show up, like subchannels, under the channel subsystem root (css0) | |
220 | and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus. | |
221 | Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect | |
222 | only the logical state and not the physical state, since we cannot track the | |
223 | latter consistently due to lacking machine support (we don't need to be aware | |
373c491f | 224 | of it anyway). |
1da177e4 LT |
225 | |
226 | status - 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 | ||
234 | 3. System devices | |
235 | ----------------- | |
236 | ||
1da177e4 LT |
237 | 3.1 xpram |
238 | --------- | |
239 | ||
373c491f CH |
240 | xpram shows up under devices/system/ as 'xpram'. |
241 | ||
242 | 3.2 cpus | |
243 | -------- | |
244 | ||
245 | For each cpu, a directory is created under devices/system/cpu/. Each cpu has an | |
246 | attribute 'online' which can be 0 or 1. | |
1da177e4 LT |
247 | |
248 | ||
249 | 4. Other devices | |
250 | ---------------- | |
251 | ||
252 | 4.1 Netiucv | |
253 | ----------- | |
254 | ||
255 | The netiucv driver creates an attribute 'connection' under | |
256 | bus/iucv/drivers/netiucv. Piping to this attibute creates a new netiucv | |
257 | connection to the specified host. | |
258 | ||
259 | Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface | |
260 | number is assigned sequentially to the connections defined via the 'connection' | |
261 | attribute. | |
262 | ||
263 | user - shows the connection partner. | |
264 | ||
265 | buffer - maximum buffer size. | |
266 | Pipe to it to change buffer size. | |
267 | ||
268 |