driver-model.txt 9.83 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1 2 3 4 5 6 7 8 9 10
S/390 driver model interfaces
-----------------------------

1. CCW devices
--------------

All devices which can be addressed by means of ccws are called 'CCW devices' -
even if they aren't actually driven by ccws.

All ccw devices are accessed via a subchannel, this is reflected in the 
11
structures under devices/:
Linus Torvalds's avatar
Linus Torvalds committed
12

13 14
devices/
     - system/
Linus Torvalds's avatar
Linus Torvalds committed
15 16 17 18
     - css0/
           - 0.0.0000/0.0.0815/
	   - 0.0.0001/0.0.4711/
	   - 0.0.0002/
19
	   - 0.1.0000/0.1.1234/
Linus Torvalds's avatar
Linus Torvalds committed
20
	   ...
21
	   - defunct/
Linus Torvalds's avatar
Linus Torvalds committed
22

23 24 25
In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
Linus Torvalds's avatar
Linus Torvalds committed
26

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 30 31 32
if they are displaced by another ccw device becoming operational on their
former subchannel. The ccw devices will be moved again to a proper subchannel
if they become operational again on that subchannel.

Linus Torvalds's avatar
Linus Torvalds committed
33 34 35 36 37 38 39 40 41 42 43 44 45 46
You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
be found under bus/ccw/devices/.

All ccw devices export some data via sysfs.

cutype:	    The control unit type / model.

devtype:    The device type / model, if applicable.

availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
	      disconnected devices.

online:     An interface to set the device online and offline.
	    In the special case of the device being disconnected (see the
47
	    notify function under 1.2), piping 0 to online will forcibly delete
Linus Torvalds's avatar
Linus Torvalds committed
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
	    the device.

The device drivers can add entries to export per-device data and interfaces.

There is also some data exported on a per-subchannel basis (see under
bus/css/devices/):

chpids:	    Via which chpids the device is connected.

pimpampom:  The path installed, path available and path operational masks.

There also might be additional data, for example for block devices.


1.1 Bringing up a ccw device
----------------------------

This is done in several steps.

a. Each driver can provide one or more parameter interfaces where parameters can
   be specified. These interfaces are also in the driver's responsibility.
b. After a. has been performed, if necessary, the device is finally brought up
   via the 'online' interface.


1.2 Writing a driver for ccw devices
------------------------------------

The basic struct ccw_device and struct ccw_driver data structures can be found
under include/asm/ccwdev.h.

struct ccw_device {
        spinlock_t *ccwlock;
        struct ccw_device_private *private;
	struct ccw_device_id id;	

	struct ccw_driver *drv;		
	struct device dev;		
	int online;

	void (*handler) (struct ccw_device *dev, unsigned long intparm,
                         struct irb *irb);
};

struct ccw_driver {
	struct module *owner;		
	struct ccw_device_id *ids;	
	int (*probe) (struct ccw_device *); 
	int (*remove) (struct ccw_device *);
	int (*set_online) (struct ccw_device *);
	int (*set_offline) (struct ccw_device *);
	int (*notify) (struct ccw_device *, int);
	struct device_driver driver;
	char *name;
};

The 'private' field contains data needed for internal i/o operation only, and
is not available to the device driver.

Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
and/or device types/models it is interested. This information can later be found
109
in the struct ccw_device_id fields:
Linus Torvalds's avatar
Linus Torvalds committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

struct ccw_device_id {
	__u16	match_flags;	

	__u16	cu_type;	
	__u16	dev_type;	
	__u8	cu_model;	
	__u8	dev_model;	

	unsigned long driver_info;
};

The functions in ccw_driver should be used in the following way:
probe:   This function is called by the device layer for each device the driver
	 is interested in. The driver should only allocate private structures
	 to put in dev->driver_data and create attributes (if needed). Also,
	 the interrupt handler (see below) should be set here.

int (*probe) (struct ccw_device *cdev); 

Parameters:  cdev     - the device to be probed.


remove:  This function is called by the device layer upon removal of the driver,
	 the device or the module. The driver should perform cleanups here.

int (*remove) (struct ccw_device *cdev);

Parameters:   cdev    - the device to be removed.


set_online: This function is called by the common I/O layer when the device is
	    activated via the 'online' attribute. The driver should finally
	    setup and activate the device here.

int (*set_online) (struct ccw_device *);

Parameters:   cdev	- the device to be activated. The common layer has
			  verified that the device is not already online.


set_offline: This function is called by the common I/O layer when the device is
	     de-activated via the 'online' attribute. The driver should shut
	     down the device, but not de-allocate its private data.

int (*set_offline) (struct ccw_device *);

Parameters:   cdev       - the device to be deactivated. The common layer has
			   verified that the device is online.


notify: This function is called by the common I/O layer for some state changes
	of the device.
	Signalled to the driver are:
	* In online state, device detached (CIO_GONE) or last path gone
	  (CIO_NO_PATH). The driver must return !0 to keep the device; for
	  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
Linus Torvalds's avatar
Linus Torvalds committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
	  device, it is moved into disconnected state.
	* In disconnected state, device operational again (CIO_OPER). The
	  common I/O layer performs some sanity checks on device number and
	  Device / CU to be reasonably sure if it is still the same device.
	  If not, the old device is removed and a new one registered. By the
	  return code of the notify function the device driver signals if it
	  wants the device back: !0 for keeping, 0 to make the device being
	  removed and re-registered.
	
int (*notify) (struct ccw_device *, int);

Parameters:   cdev    - the device whose state changed.
	      event   - the event that happened. This can be one of CIO_GONE,
		        CIO_NO_PATH or CIO_OPER.

The handler field of the struct ccw_device is meant to be set to the interrupt
handler for the device. In order to accommodate drivers which use several 
distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
instead of ccw_driver.
The handler is registered with the common layer during set_online() processing
before the driver is called, and is deregistered during set_offline() after the
driver has been called. Also, after registering / before deregistering, path 
grouping resp. disbanding of the path group (if applicable) are performed.

void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);

Parameters:	dev	- the device the handler is called for
		intparm - the intparm which allows the device driver to identify
                          the i/o the interrupt is associated with, or to recognize
                          the interrupt as unsolicited.
                irb     - interruption response block which contains the accumulated
                          status.

The device driver is called from the common ccw_device layer and can retrieve 
information about the interrupt from the irb parameter.


1.3 ccwgroup devices
--------------------

The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
devices, like lcs or ctc.

The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
this attributes creates a ccwgroup device consisting of these ccw devices (if
possible). This ccwgroup device can be set online or offline just like a normal
ccw device.

Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
again (only when offline). This is a generic ccwgroup mechanism (the driver does
not need to implement anything beyond normal removal routines).

220 221 222 223 224
A ccw device which is a member of a ccwgroup device carries a pointer to the
ccwgroup device in the driver_data of its device struct. This field must not be
touched by the driver - it should use the ccwgroup device's driver_data for its
private data.

Linus Torvalds's avatar
Linus Torvalds committed
225
To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
226 227
mind that most drivers will need to implement both a ccwgroup and a ccw
driver.
Linus Torvalds's avatar
Linus Torvalds committed
228 229 230 231 232 233 234 235 236 237


2. Channel paths
-----------------

Channel paths show up, like subchannels, under the channel subsystem root (css0)
and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
only the logical state and not the physical state, since we cannot track the
latter consistently due to lacking machine support (we don't need to be aware
238
of it anyway).
Linus Torvalds's avatar
Linus Torvalds committed
239 240 241 242 243 244 245 246

status - Can be 'online' or 'offline'.
	 Piping 'on' or 'off' sets the chpid logically online/offline.
	 Piping 'on' to an online chpid triggers path reprobing for all devices
	 the chpid connects to. This can be used to force the kernel to re-use
	 a channel path the user knows to be online, but the machine hasn't
	 created a machine check for.

247 248
type - The physical type of the channel path.

249 250 251
shared - Whether the channel path is shared.

cmg - The channel measurement group.
Linus Torvalds's avatar
Linus Torvalds committed
252 253 254 255 256 257 258

3. System devices
-----------------

3.1 xpram 
---------

259 260 261 262 263 264 265
xpram shows up under devices/system/ as 'xpram'.

3.2 cpus
--------

For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
attribute 'online' which can be 0 or 1.
Linus Torvalds's avatar
Linus Torvalds committed
266 267 268 269 270 271 272 273 274


4. Other devices
----------------

4.1 Netiucv
-----------

The netiucv driver creates an attribute 'connection' under
275
bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
Linus Torvalds's avatar
Linus Torvalds committed
276 277 278 279 280 281 282 283 284 285 286 287
connection to the specified host.

Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
number is assigned sequentially to the connections defined via the 'connection'
attribute.

user			  - shows the connection partner.

buffer			  - maximum buffer size.
			    Pipe to it to change buffer size.