Documentation/s390/driver-model.txt

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