Documentation/s390/driver-model.rst

   1 =============================
   2 S/390 driver model interfaces
   3 =============================
   4
   5 1. CCW devices
   6 --------------
   7
   8 All devices which can be addressed by means of ccws are called 'CCW devices' -
   9 even if they aren't actually driven by ccws.
  10
  11 All ccw devices are accessed via a subchannel, this is reflected in the
  12 structures 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
  24 In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
  25 device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
  26 subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
  27
  28 The subchannel named 'defunct' does not represent any real subchannel on the
  29 system; it is a pseudo subchannel where disconnected ccw devices are moved to
  30 if they are displaced by another ccw device becoming operational on their
  31 former subchannel. The ccw devices will be moved again to a proper subchannel
  32 if they become operational again on that subchannel.
  33
  34 You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
  35 be found under bus/ccw/devices/.
  36
  37 All ccw devices export some data via sysfs.
  38
  39 cutype:
  40         The control unit type / model.
  41
  42 devtype:
  43         The device type / model, if applicable.
  44
  45 availability:
  46               Can be 'good' or 'boxed'; 'no path' or 'no device' for
  47               disconnected devices.
  48
  49 online:
  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
  55 The device drivers can add entries to export per-device data and interfaces.
  56
  57 There is also some data exported on a per-subchannel basis (see under
  58 bus/css/devices/):
  59
  60 chpids:
  61         Via which chpids the device is connected.
  62
  63 pimpampom:
  64         The path installed, path available and path operational masks.
  65
  66 There also might be additional data, for example for block devices.
  67
  68
  69 1.1 Bringing up a ccw device
  70 ----------------------------
  71
  72 This is done in several steps.
  73
  74 a. Each driver can provide one or more parameter interfaces where parameters can
  75    be specified. These interfaces are also in the driver's responsibility.
  76 b. After a. has been performed, if necessary, the device is finally brought up
  77    via the 'online' interface.
  78
  79
  80 1.2 Writing a driver for ccw devices
  81 ------------------------------------
  82
  83 The basic struct ccw_device and struct ccw_driver data structures can be found
  84 under 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
 111 The 'private' field contains data needed for internal i/o operation only, and
 112 is not available to the device driver.
 113
 114 Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
 115 and/or device types/models it is interested. This information can later be found
 116 in 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
 129 The functions in ccw_driver should be used in the following way:
 130
 131 probe:
 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
 141 Parameters:
 142                 cdev
 143                         - the device to be probed.
 144
 145
 146 remove:
 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
 154 Parameters:
 155                 cdev
 156                         - the device to be removed.
 157
 158
 159 set_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
 168 Parameters:
 169                 cdev
 170                         - the device to be activated. The common layer has
 171                           verified that the device is not already online.
 172
 173
 174 set_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
 182 Parameters:
 183                 cdev
 184                         - the device to be deactivated. The common layer has
 185                            verified that the device is online.
 186
 187
 188 notify:
 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
 211 Parameters:
 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
 219 The handler field of the struct ccw_device is meant to be set to the interrupt
 220 handler for the device. In order to accommodate drivers which use several
 221 distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
 222 instead of ccw_driver.
 223 The handler is registered with the common layer during set_online() processing
 224 before the driver is called, and is deregistered during set_offline() after the
 225 driver has been called. Also, after registering / before deregistering, path
 226 grouping 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
 232 Parameters:     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
 239 The device driver is called from the common ccw_device layer and can retrieve
 240 information about the interrupt from the irb parameter.
 241
 242
 243 1.3 ccwgroup devices
 244 --------------------
 245
 246 The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
 247 devices, like lcs or ctc.
 248
 249 The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
 250 this attributes creates a ccwgroup device consisting of these ccw devices (if
 251 possible). This ccwgroup device can be set online or offline just like a normal
 252 ccw device.
 253
 254 Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
 255 again (only when offline). This is a generic ccwgroup mechanism (the driver does
 256 not need to implement anything beyond normal removal routines).
 257
 258 A ccw device which is a member of a ccwgroup device carries a pointer to the
 259 ccwgroup device in the driver_data of its device struct. This field must not be
 260 touched by the driver - it should use the ccwgroup device's driver_data for its
 261 private data.
 262
 263 To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
 264 mind that most drivers will need to implement both a ccwgroup and a ccw
 265 driver.
 266
 267
 268 2. Channel paths
 269 -----------------
 270
 271 Channel paths show up, like subchannels, under the channel subsystem root (css0)
 272 and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
 273 Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
 274 only the logical state and not the physical state, since we cannot track the
 275 latter consistently due to lacking machine support (we don't need to be aware
 276 of it anyway).
 277
 278 status
 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
 286 type
 287        - The physical type of the channel path.
 288
 289 shared
 290        - Whether the channel path is shared.
 291
 292 cmg
 293        - The channel measurement group.
 294
 295 3. System devices
 296 -----------------
 297
 298 3.1 xpram
 299 ---------
 300
 301 xpram shows up under devices/system/ as 'xpram'.
 302
 303 3.2 cpus
 304 --------
 305
 306 For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
 307 attribute 'online' which can be 0 or 1.
 308
 309
 310 4. Other devices
 311 ----------------
 312
 313 4.1 Netiucv
 314 -----------
 315
 316 The netiucv driver creates an attribute 'connection' under
 317 bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
 318 connection to the specified host.
 319
 320 Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
 321 number is assigned sequentially to the connections defined via the 'connection'
 322 attribute.
 323
 324 user
 325     - shows the connection partner.
 326
 327 buffer
 328     - maximum buffer size. Pipe to it to change buffer size.