Linux 4.19.133
[linux/fpc-iii.git] / Documentation / s390 / driver-model.txt
blobed265cf54cde70f20c98de6a7bfbffa1758f3cfb
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 devices/:
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/
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.
27 The subchannel named 'defunct' does not represent any real subchannel on the
28 system; it is a pseudo subchannel where disconnected 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.
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/.
36 All ccw devices export some data via sysfs.
38 cutype:     The control unit type / model.
40 devtype:    The device type / model, if applicable.
42 availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
43               disconnected devices.
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.
50 The device drivers can add entries to export per-device data and interfaces.
52 There is also some data exported on a per-subchannel basis (see under
53 bus/css/devices/):
55 chpids:     Via which chpids the device is connected.
57 pimpampom:  The path installed, path available and path operational masks.
59 There also might be additional data, for example for block devices.
62 1.1 Bringing up a ccw device
63 ----------------------------
65 This is done in several steps.
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.
73 1.2 Writing a driver for ccw devices
74 ------------------------------------
76 The basic struct ccw_device and struct ccw_driver data structures can be found
77 under include/asm/ccwdev.h.
79 struct ccw_device {
80         spinlock_t *ccwlock;
81         struct ccw_device_private *private;
82         struct ccw_device_id id;        
84         struct ccw_driver *drv;         
85         struct device dev;              
86         int online;
88         void (*handler) (struct ccw_device *dev, unsigned long intparm,
89                          struct irb *irb);
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;
104 The 'private' field contains data needed for internal i/o operation only, and
105 is not available to the device driver.
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:
111 struct ccw_device_id {
112         __u16   match_flags;    
114         __u16   cu_type;        
115         __u16   dev_type;       
116         __u8    cu_model;       
117         __u8    dev_model;      
119         unsigned long driver_info;
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.
128 int (*probe) (struct ccw_device *cdev); 
130 Parameters:  cdev     - the device to be probed.
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.
136 int (*remove) (struct ccw_device *cdev);
138 Parameters:   cdev    - the device to be removed.
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.
145 int (*set_online) (struct ccw_device *);
147 Parameters:   cdev      - the device to be activated. The common layer has
148                           verified that the device is not already online.
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.
155 int (*set_offline) (struct ccw_device *);
157 Parameters:   cdev       - the device to be deactivated. The common layer has
158                            verified that the device is online.
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);
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.
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.
192 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
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.
201 The device driver is called from the common ccw_device layer and can retrieve 
202 information about the interrupt from the irb parameter.
205 1.3 ccwgroup devices
206 --------------------
208 The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
209 devices, like lcs or ctc.
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.
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).
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.
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
227 driver.
230 2. Channel paths
231 -----------------
233 Channel paths show up, like subchannels, under the channel subsystem root (css0)
234 and are called 'chp0.<chpid>'. 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).
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.
247 type - The physical type of the channel path.
249 shared - Whether the channel path is shared.
251 cmg - The channel measurement group.
253 3. System devices
254 -----------------
256 3.1 xpram 
257 ---------
259 xpram shows up under devices/system/ as 'xpram'.
261 3.2 cpus
262 --------
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.
268 4. Other devices
269 ----------------
271 4.1 Netiucv
272 -----------
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.
278 Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
279 number is assigned sequentially to the connections defined via the 'connection'
280 attribute.
282 user                      - shows the connection partner.
284 buffer                    - maximum buffer size.
285                             Pipe to it to change buffer size.