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