0001 =============================
0002 S/390 driver model interfaces
0003 =============================
0004
0005 1. CCW devices
0006 --------------
0007
0008 All devices which can be addressed by means of ccws are called 'CCW devices' -
0009 even if they aren't actually driven by ccws.
0010
0011 All ccw devices are accessed via a subchannel, this is reflected in the
0012 structures under devices/::
0013
0014 devices/
0015 - system/
0016 - css0/
0017 - 0.0.0000/0.0.0815/
0018 - 0.0.0001/0.0.4711/
0019 - 0.0.0002/
0020 - 0.1.0000/0.1.1234/
0021 ...
0022 - defunct/
0023
0024 In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
0025 device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
0026 subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
0027
0028 The subchannel named 'defunct' does not represent any real subchannel on the
0029 system; it is a pseudo subchannel where disconnected ccw devices are moved to
0030 if they are displaced by another ccw device becoming operational on their
0031 former subchannel. The ccw devices will be moved again to a proper subchannel
0032 if they become operational again on that subchannel.
0033
0034 You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
0035 be found under bus/ccw/devices/.
0036
0037 All ccw devices export some data via sysfs.
0038
0039 cutype:
0040 The control unit type / model.
0041
0042 devtype:
0043 The device type / model, if applicable.
0044
0045 availability:
0046 Can be 'good' or 'boxed'; 'no path' or 'no device' for
0047 disconnected devices.
0048
0049 online:
0050 An interface to set the device online and offline.
0051 In the special case of the device being disconnected (see the
0052 notify function under 1.2), piping 0 to online will forcibly delete
0053 the device.
0054
0055 The device drivers can add entries to export per-device data and interfaces.
0056
0057 There is also some data exported on a per-subchannel basis (see under
0058 bus/css/devices/):
0059
0060 chpids:
0061 Via which chpids the device is connected.
0062
0063 pimpampom:
0064 The path installed, path available and path operational masks.
0065
0066 There also might be additional data, for example for block devices.
0067
0068
0069 1.1 Bringing up a ccw device
0070 ----------------------------
0071
0072 This is done in several steps.
0073
0074 a. Each driver can provide one or more parameter interfaces where parameters can
0075 be specified. These interfaces are also in the driver's responsibility.
0076 b. After a. has been performed, if necessary, the device is finally brought up
0077 via the 'online' interface.
0078
0079
0080 1.2 Writing a driver for ccw devices
0081 ------------------------------------
0082
0083 The basic struct ccw_device and struct ccw_driver data structures can be found
0084 under include/asm/ccwdev.h::
0085
0086 struct ccw_device {
0087 spinlock_t *ccwlock;
0088 struct ccw_device_private *private;
0089 struct ccw_device_id id;
0090
0091 struct ccw_driver *drv;
0092 struct device dev;
0093 int online;
0094
0095 void (*handler) (struct ccw_device *dev, unsigned long intparm,
0096 struct irb *irb);
0097 };
0098
0099 struct ccw_driver {
0100 struct module *owner;
0101 struct ccw_device_id *ids;
0102 int (*probe) (struct ccw_device *);
0103 int (*remove) (struct ccw_device *);
0104 int (*set_online) (struct ccw_device *);
0105 int (*set_offline) (struct ccw_device *);
0106 int (*notify) (struct ccw_device *, int);
0107 struct device_driver driver;
0108 char *name;
0109 };
0110
0111 The 'private' field contains data needed for internal i/o operation only, and
0112 is not available to the device driver.
0113
0114 Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
0115 and/or device types/models it is interested. This information can later be found
0116 in the struct ccw_device_id fields::
0117
0118 struct ccw_device_id {
0119 __u16 match_flags;
0120
0121 __u16 cu_type;
0122 __u16 dev_type;
0123 __u8 cu_model;
0124 __u8 dev_model;
0125
0126 unsigned long driver_info;
0127 };
0128
0129 The functions in ccw_driver should be used in the following way:
0130
0131 probe:
0132 This function is called by the device layer for each device the driver
0133 is interested in. The driver should only allocate private structures
0134 to put in dev->driver_data and create attributes (if needed). Also,
0135 the interrupt handler (see below) should be set here.
0136
0137 ::
0138
0139 int (*probe) (struct ccw_device *cdev);
0140
0141 Parameters:
0142 cdev
0143 - the device to be probed.
0144
0145
0146 remove:
0147 This function is called by the device layer upon removal of the driver,
0148 the device or the module. The driver should perform cleanups here.
0149
0150 ::
0151
0152 int (*remove) (struct ccw_device *cdev);
0153
0154 Parameters:
0155 cdev
0156 - the device to be removed.
0157
0158
0159 set_online:
0160 This function is called by the common I/O layer when the device is
0161 activated via the 'online' attribute. The driver should finally
0162 setup and activate the device here.
0163
0164 ::
0165
0166 int (*set_online) (struct ccw_device *);
0167
0168 Parameters:
0169 cdev
0170 - the device to be activated. The common layer has
0171 verified that the device is not already online.
0172
0173
0174 set_offline: This function is called by the common I/O layer when the device is
0175 de-activated via the 'online' attribute. The driver should shut
0176 down the device, but not de-allocate its private data.
0177
0178 ::
0179
0180 int (*set_offline) (struct ccw_device *);
0181
0182 Parameters:
0183 cdev
0184 - the device to be deactivated. The common layer has
0185 verified that the device is online.
0186
0187
0188 notify:
0189 This function is called by the common I/O layer for some state changes
0190 of the device.
0191
0192 Signalled to the driver are:
0193
0194 * In online state, device detached (CIO_GONE) or last path gone
0195 (CIO_NO_PATH). The driver must return !0 to keep the device; for
0196 return code 0, the device will be deleted as usual (also when no
0197 notify function is registered). If the driver wants to keep the
0198 device, it is moved into disconnected state.
0199 * In disconnected state, device operational again (CIO_OPER). The
0200 common I/O layer performs some sanity checks on device number and
0201 Device / CU to be reasonably sure if it is still the same device.
0202 If not, the old device is removed and a new one registered. By the
0203 return code of the notify function the device driver signals if it
0204 wants the device back: !0 for keeping, 0 to make the device being
0205 removed and re-registered.
0206
0207 ::
0208
0209 int (*notify) (struct ccw_device *, int);
0210
0211 Parameters:
0212 cdev
0213 - the device whose state changed.
0214
0215 event
0216 - the event that happened. This can be one of CIO_GONE,
0217 CIO_NO_PATH or CIO_OPER.
0218
0219 The handler field of the struct ccw_device is meant to be set to the interrupt
0220 handler for the device. In order to accommodate drivers which use several
0221 distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
0222 instead of ccw_driver.
0223 The handler is registered with the common layer during set_online() processing
0224 before the driver is called, and is deregistered during set_offline() after the
0225 driver has been called. Also, after registering / before deregistering, path
0226 grouping resp. disbanding of the path group (if applicable) are performed.
0227
0228 ::
0229
0230 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
0231
0232 Parameters: dev - the device the handler is called for
0233 intparm - the intparm which allows the device driver to identify
0234 the i/o the interrupt is associated with, or to recognize
0235 the interrupt as unsolicited.
0236 irb - interruption response block which contains the accumulated
0237 status.
0238
0239 The device driver is called from the common ccw_device layer and can retrieve
0240 information about the interrupt from the irb parameter.
0241
0242
0243 1.3 ccwgroup devices
0244 --------------------
0245
0246 The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
0247 devices, like lcs or ctc.
0248
0249 The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
0250 this attributes creates a ccwgroup device consisting of these ccw devices (if
0251 possible). This ccwgroup device can be set online or offline just like a normal
0252 ccw device.
0253
0254 Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
0255 again (only when offline). This is a generic ccwgroup mechanism (the driver does
0256 not need to implement anything beyond normal removal routines).
0257
0258 A ccw device which is a member of a ccwgroup device carries a pointer to the
0259 ccwgroup device in the driver_data of its device struct. This field must not be
0260 touched by the driver - it should use the ccwgroup device's driver_data for its
0261 private data.
0262
0263 To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
0264 mind that most drivers will need to implement both a ccwgroup and a ccw
0265 driver.
0266
0267
0268 2. Channel paths
0269 -----------------
0270
0271 Channel paths show up, like subchannels, under the channel subsystem root (css0)
0272 and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
0273 Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
0274 only the logical state and not the physical state, since we cannot track the
0275 latter consistently due to lacking machine support (we don't need to be aware
0276 of it anyway).
0277
0278 status
0279 - Can be 'online' or 'offline'.
0280 Piping 'on' or 'off' sets the chpid logically online/offline.
0281 Piping 'on' to an online chpid triggers path reprobing for all devices
0282 the chpid connects to. This can be used to force the kernel to re-use
0283 a channel path the user knows to be online, but the machine hasn't
0284 created a machine check for.
0285
0286 type
0287 - The physical type of the channel path.
0288
0289 shared
0290 - Whether the channel path is shared.
0291
0292 cmg
0293 - The channel measurement group.
0294
0295 3. System devices
0296 -----------------
0297
0298 3.1 xpram
0299 ---------
0300
0301 xpram shows up under devices/system/ as 'xpram'.
0302
0303 3.2 cpus
0304 --------
0305
0306 For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
0307 attribute 'online' which can be 0 or 1.
0308
0309
0310 4. Other devices
0311 ----------------
0312
0313 4.1 Netiucv
0314 -----------
0315
0316 The netiucv driver creates an attribute 'connection' under
0317 bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
0318 connection to the specified host.
0319
0320 Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
0321 number is assigned sequentially to the connections defined via the 'connection'
0322 attribute.
0323
0324 user
0325 - shows the connection partner.
0326
0327 buffer
0328 - maximum buffer size. Pipe to it to change buffer size.
