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