Linux 2.6.13-rc4
[linux-2.6/next.git] / Documentation / s390 / driver-model.txt
blob19461958e2bd98a24260866329eb2e26b5188dbd
1 S/390 driver model interfaces
2 -----------------------------
4 1. CCW devices
5 --------------
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.
10 All ccw devices are accessed via a subchannel, this is reflected in the 
11 structures under root/:
13 root/
14      - sys
15      - legacy
16      - css0/
17            - 0.0.0000/0.0.0815/
18            - 0.0.0001/0.0.4711/
19            - 0.0.0002/
20            ...
22 In this example, device 0815 is accessed via subchannel 0, device 4711 via 
23 subchannel 1, and subchannel 2 is a non-I/O subchannel.
25 You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
26 be found under bus/ccw/devices/.
28 All ccw devices export some data via sysfs.
30 cutype:     The control unit type / model.
32 devtype:    The device type / model, if applicable.
34 availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
35               disconnected devices.
37 online:     An interface to set the device online and offline.
38             In the special case of the device being disconnected (see the
39             notify function under 1.2), piping 0 to online will focibly delete
40             the device.
42 The device drivers can add entries to export per-device data and interfaces.
44 There is also some data exported on a per-subchannel basis (see under
45 bus/css/devices/):
47 chpids:     Via which chpids the device is connected.
49 pimpampom:  The path installed, path available and path operational masks.
51 There also might be additional data, for example for block devices.
54 1.1 Bringing up a ccw device
55 ----------------------------
57 This is done in several steps.
59 a. Each driver can provide one or more parameter interfaces where parameters can
60    be specified. These interfaces are also in the driver's responsibility.
61 b. After a. has been performed, if necessary, the device is finally brought up
62    via the 'online' interface.
65 1.2 Writing a driver for ccw devices
66 ------------------------------------
68 The basic struct ccw_device and struct ccw_driver data structures can be found
69 under include/asm/ccwdev.h.
71 struct ccw_device {
72         spinlock_t *ccwlock;
73         struct ccw_device_private *private;
74         struct ccw_device_id id;        
76         struct ccw_driver *drv;         
77         struct device dev;              
78         int online;
80         void (*handler) (struct ccw_device *dev, unsigned long intparm,
81                          struct irb *irb);
84 struct ccw_driver {
85         struct module *owner;           
86         struct ccw_device_id *ids;      
87         int (*probe) (struct ccw_device *); 
88         int (*remove) (struct ccw_device *);
89         int (*set_online) (struct ccw_device *);
90         int (*set_offline) (struct ccw_device *);
91         int (*notify) (struct ccw_device *, int);
92         struct device_driver driver;
93         char *name;
96 The 'private' field contains data needed for internal i/o operation only, and
97 is not available to the device driver.
99 Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
100 and/or device types/models it is interested. This information can later be found
101 found in the struct ccw_device_id fields:
103 struct ccw_device_id {
104         __u16   match_flags;    
106         __u16   cu_type;        
107         __u16   dev_type;       
108         __u8    cu_model;       
109         __u8    dev_model;      
111         unsigned long driver_info;
114 The functions in ccw_driver should be used in the following way:
115 probe:   This function is called by the device layer for each device the driver
116          is interested in. The driver should only allocate private structures
117          to put in dev->driver_data and create attributes (if needed). Also,
118          the interrupt handler (see below) should be set here.
120 int (*probe) (struct ccw_device *cdev); 
122 Parameters:  cdev     - the device to be probed.
125 remove:  This function is called by the device layer upon removal of the driver,
126          the device or the module. The driver should perform cleanups here.
128 int (*remove) (struct ccw_device *cdev);
130 Parameters:   cdev    - the device to be removed.
133 set_online: This function is called by the common I/O layer when the device is
134             activated via the 'online' attribute. The driver should finally
135             setup and activate the device here.
137 int (*set_online) (struct ccw_device *);
139 Parameters:   cdev      - the device to be activated. The common layer has
140                           verified that the device is not already online.
143 set_offline: This function is called by the common I/O layer when the device is
144              de-activated via the 'online' attribute. The driver should shut
145              down the device, but not de-allocate its private data.
147 int (*set_offline) (struct ccw_device *);
149 Parameters:   cdev       - the device to be deactivated. The common layer has
150                            verified that the device is online.
153 notify: This function is called by the common I/O layer for some state changes
154         of the device.
155         Signalled to the driver are:
156         * In online state, device detached (CIO_GONE) or last path gone
157           (CIO_NO_PATH). The driver must return !0 to keep the device; for
158           return code 0, the device will be deleted as usual (also when no
159           notify function is registerd). If the driver wants to keep the
160           device, it is moved into disconnected state.
161         * In disconnected state, device operational again (CIO_OPER). The
162           common I/O layer performs some sanity checks on device number and
163           Device / CU to be reasonably sure if it is still the same device.
164           If not, the old device is removed and a new one registered. By the
165           return code of the notify function the device driver signals if it
166           wants the device back: !0 for keeping, 0 to make the device being
167           removed and re-registered.
168         
169 int (*notify) (struct ccw_device *, int);
171 Parameters:   cdev    - the device whose state changed.
172               event   - the event that happened. This can be one of CIO_GONE,
173                         CIO_NO_PATH or CIO_OPER.
175 The handler field of the struct ccw_device is meant to be set to the interrupt
176 handler for the device. In order to accommodate drivers which use several 
177 distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
178 instead of ccw_driver.
179 The handler is registered with the common layer during set_online() processing
180 before the driver is called, and is deregistered during set_offline() after the
181 driver has been called. Also, after registering / before deregistering, path 
182 grouping resp. disbanding of the path group (if applicable) are performed.
184 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
186 Parameters:     dev     - the device the handler is called for
187                 intparm - the intparm which allows the device driver to identify
188                           the i/o the interrupt is associated with, or to recognize
189                           the interrupt as unsolicited.
190                 irb     - interruption response block which contains the accumulated
191                           status.
193 The device driver is called from the common ccw_device layer and can retrieve 
194 information about the interrupt from the irb parameter.
197 1.3 ccwgroup devices
198 --------------------
200 The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
201 devices, like lcs or ctc.
203 The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
204 this attributes creates a ccwgroup device consisting of these ccw devices (if
205 possible). This ccwgroup device can be set online or offline just like a normal
206 ccw device.
208 Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
209 again (only when offline). This is a generic ccwgroup mechanism (the driver does
210 not need to implement anything beyond normal removal routines).
212 To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
213 mind that most drivers will need to implement both a ccwgroup and a ccw driver
214 (unless you have a meta ccw driver, like cu3088 for lcs and ctc).
217 2. Channel paths
218 -----------------
220 Channel paths show up, like subchannels, under the channel subsystem root (css0)
221 and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
222 Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
223 only the logical state and not the physical state, since we cannot track the
224 latter consistently due to lacking machine support (we don't need to be aware
225 of anyway).
227 status - Can be 'online' or 'offline'.
228          Piping 'on' or 'off' sets the chpid logically online/offline.
229          Piping 'on' to an online chpid triggers path reprobing for all devices
230          the chpid connects to. This can be used to force the kernel to re-use
231          a channel path the user knows to be online, but the machine hasn't
232          created a machine check for.
235 3. System devices
236 -----------------
238 Note: cpus may yet be added here.
240 3.1 xpram 
241 ---------
243 xpram shows up under sys/ as 'xpram'.
246 4. Other devices
247 ----------------
249 4.1 Netiucv
250 -----------
252 The netiucv driver creates an attribute 'connection' under
253 bus/iucv/drivers/netiucv. Piping to this attibute creates a new netiucv
254 connection to the specified host.
256 Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
257 number is assigned sequentially to the connections defined via the 'connection'
258 attribute.
260 user                      - shows the connection partner.
262 buffer                    - maximum buffer size.
263                             Pipe to it to change buffer size.