1============================= 2S/390 driver model interfaces 3============================= 4 51. CCW devices 6-------------- 7 8All devices which can be addressed by means of ccws are called 'CCW devices' - 9even if they aren't actually driven by ccws. 10 11All ccw devices are accessed via a subchannel, this is reflected in the 12structures under devices/:: 13 14 devices/ 15 - system/ 16 - css0/ 17 - 0.0.0000/0.0.0815/ 18 - 0.0.0001/0.0.4711/ 19 - 0.0.0002/ 20 - 0.1.0000/0.1.1234/ 21 ... 22 - defunct/ 23 24In this example, device 0815 is accessed via subchannel 0 in subchannel set 0, 25device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O 26subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1. 27 28The subchannel named 'defunct' does not represent any real subchannel on the 29system; it is a pseudo subchannel where disconnected ccw devices are moved to 30if they are displaced by another ccw device becoming operational on their 31former subchannel. The ccw devices will be moved again to a proper subchannel 32if they become operational again on that subchannel. 33 34You should address a ccw device via its bus id (e.g. 0.0.4711); the device can 35be found under bus/ccw/devices/. 36 37All ccw devices export some data via sysfs. 38 39cutype: 40 The control unit type / model. 41 42devtype: 43 The device type / model, if applicable. 44 45availability: 46 Can be 'good' or 'boxed'; 'no path' or 'no device' for 47 disconnected devices. 48 49online: 50 An interface to set the device online and offline. 51 In the special case of the device being disconnected (see the 52 notify function under 1.2), piping 0 to online will forcibly delete 53 the device. 54 55The device drivers can add entries to export per-device data and interfaces. 56 57There is also some data exported on a per-subchannel basis (see under 58bus/css/devices/): 59 60chpids: 61 Via which chpids the device is connected. 62 63pimpampom: 64 The path installed, path available and path operational masks. 65 66There also might be additional data, for example for block devices. 67 68 691.1 Bringing up a ccw device 70---------------------------- 71 72This is done in several steps. 73 74a. Each driver can provide one or more parameter interfaces where parameters can 75 be specified. These interfaces are also in the driver's responsibility. 76b. After a. has been performed, if necessary, the device is finally brought up 77 via the 'online' interface. 78 79 801.2 Writing a driver for ccw devices 81------------------------------------ 82 83The basic struct ccw_device and struct ccw_driver data structures can be found 84under include/asm/ccwdev.h:: 85 86 struct ccw_device { 87 spinlock_t *ccwlock; 88 struct ccw_device_private *private; 89 struct ccw_device_id id; 90 91 struct ccw_driver *drv; 92 struct device dev; 93 int online; 94 95 void (*handler) (struct ccw_device *dev, unsigned long intparm, 96 struct irb *irb); 97 }; 98 99 struct ccw_driver { 100 struct module *owner; 101 struct ccw_device_id *ids; 102 int (*probe) (struct ccw_device *); 103 int (*remove) (struct ccw_device *); 104 int (*set_online) (struct ccw_device *); 105 int (*set_offline) (struct ccw_device *); 106 int (*notify) (struct ccw_device *, int); 107 struct device_driver driver; 108 char *name; 109 }; 110 111The 'private' field contains data needed for internal i/o operation only, and 112is not available to the device driver. 113 114Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models 115and/or device types/models it is interested. This information can later be found 116in the struct ccw_device_id fields:: 117 118 struct ccw_device_id { 119 __u16 match_flags; 120 121 __u16 cu_type; 122 __u16 dev_type; 123 __u8 cu_model; 124 __u8 dev_model; 125 126 unsigned long driver_info; 127 }; 128 129The functions in ccw_driver should be used in the following way: 130 131probe: 132 This function is called by the device layer for each device the driver 133 is interested in. The driver should only allocate private structures 134 to put in dev->driver_data and create attributes (if needed). Also, 135 the interrupt handler (see below) should be set here. 136 137:: 138 139 int (*probe) (struct ccw_device *cdev); 140 141Parameters: 142 cdev 143 - the device to be probed. 144 145 146remove: 147 This function is called by the device layer upon removal of the driver, 148 the device or the module. The driver should perform cleanups here. 149 150:: 151 152 int (*remove) (struct ccw_device *cdev); 153 154Parameters: 155 cdev 156 - the device to be removed. 157 158 159set_online: 160 This function is called by the common I/O layer when the device is 161 activated via the 'online' attribute. The driver should finally 162 setup and activate the device here. 163 164:: 165 166 int (*set_online) (struct ccw_device *); 167 168Parameters: 169 cdev 170 - the device to be activated. The common layer has 171 verified that the device is not already online. 172 173 174set_offline: This function is called by the common I/O layer when the device is 175 de-activated via the 'online' attribute. The driver should shut 176 down the device, but not de-allocate its private data. 177 178:: 179 180 int (*set_offline) (struct ccw_device *); 181 182Parameters: 183 cdev 184 - the device to be deactivated. The common layer has 185 verified that the device is online. 186 187 188notify: 189 This function is called by the common I/O layer for some state changes 190 of the device. 191 192 Signalled to the driver are: 193 194 * In online state, device detached (CIO_GONE) or last path gone 195 (CIO_NO_PATH). The driver must return !0 to keep the device; for 196 return code 0, the device will be deleted as usual (also when no 197 notify function is registered). If the driver wants to keep the 198 device, it is moved into disconnected state. 199 * In disconnected state, device operational again (CIO_OPER). The 200 common I/O layer performs some sanity checks on device number and 201 Device / CU to be reasonably sure if it is still the same device. 202 If not, the old device is removed and a new one registered. By the 203 return code of the notify function the device driver signals if it 204 wants the device back: !0 for keeping, 0 to make the device being 205 removed and re-registered. 206 207:: 208 209 int (*notify) (struct ccw_device *, int); 210 211Parameters: 212 cdev 213 - the device whose state changed. 214 215 event 216 - the event that happened. This can be one of CIO_GONE, 217 CIO_NO_PATH or CIO_OPER. 218 219The handler field of the struct ccw_device is meant to be set to the interrupt 220handler for the device. In order to accommodate drivers which use several 221distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device 222instead of ccw_driver. 223The handler is registered with the common layer during set_online() processing 224before the driver is called, and is deregistered during set_offline() after the 225driver has been called. Also, after registering / before deregistering, path 226grouping resp. disbanding of the path group (if applicable) are performed. 227 228:: 229 230 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb); 231 232Parameters: dev - the device the handler is called for 233 intparm - the intparm which allows the device driver to identify 234 the i/o the interrupt is associated with, or to recognize 235 the interrupt as unsolicited. 236 irb - interruption response block which contains the accumulated 237 status. 238 239The device driver is called from the common ccw_device layer and can retrieve 240information about the interrupt from the irb parameter. 241 242 2431.3 ccwgroup devices 244-------------------- 245 246The ccwgroup mechanism is designed to handle devices consisting of multiple ccw 247devices, like lcs or ctc. 248 249The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to 250this attributes creates a ccwgroup device consisting of these ccw devices (if 251possible). This ccwgroup device can be set online or offline just like a normal 252ccw device. 253 254Each ccwgroup device also provides an 'ungroup' attribute to destroy the device 255again (only when offline). This is a generic ccwgroup mechanism (the driver does 256not need to implement anything beyond normal removal routines). 257 258A ccw device which is a member of a ccwgroup device carries a pointer to the 259ccwgroup device in the driver_data of its device struct. This field must not be 260touched by the driver - it should use the ccwgroup device's driver_data for its 261private data. 262 263To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in 264mind that most drivers will need to implement both a ccwgroup and a ccw 265driver. 266 267 2682. Channel paths 269----------------- 270 271Channel paths show up, like subchannels, under the channel subsystem root (css0) 272and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus. 273Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect 274only the logical state and not the physical state, since we cannot track the 275latter consistently due to lacking machine support (we don't need to be aware 276of it anyway). 277 278status 279 - Can be 'online' or 'offline'. 280 Piping 'on' or 'off' sets the chpid logically online/offline. 281 Piping 'on' to an online chpid triggers path reprobing for all devices 282 the chpid connects to. This can be used to force the kernel to re-use 283 a channel path the user knows to be online, but the machine hasn't 284 created a machine check for. 285 286type 287 - The physical type of the channel path. 288 289shared 290 - Whether the channel path is shared. 291 292cmg 293 - The channel measurement group. 294 2953. System devices 296----------------- 297 2983.1 xpram 299--------- 300 301xpram shows up under devices/system/ as 'xpram'. 302 3033.2 cpus 304-------- 305 306For each cpu, a directory is created under devices/system/cpu/. Each cpu has an 307attribute 'online' which can be 0 or 1. 308 309 3104. Other devices 311---------------- 312 3134.1 Netiucv 314----------- 315 316The netiucv driver creates an attribute 'connection' under 317bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv 318connection to the specified host. 319 320Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface 321number is assigned sequentially to the connections defined via the 'connection' 322attribute. 323 324user 325 - shows the connection partner. 326 327buffer 328 - maximum buffer size. Pipe to it to change buffer size. 329