[PATCH] s390: channel subsystem docu.

Documentation changes for common i/o.

Documentation/s390/driver-model.txt

+S/390 driver model interfaces
+-----------------------------
+
+1. CCW devices
+--------------
+
+All devices which can be addressed by means of ccws are called 'CCW devices' -
+even if they aren't actually driven by ccws.
+
+All ccw devices are accessed via a subchannel, this is reflected in the 
+structures under root/:
+
+root/
+     - sys
+     - legacy
+     - css0/
+           - 0:0000/0:0815/
+	   - 0:0001/0:4711/
+	   - 0:0002/
+	   ...
+
+In this example, device 0815 is accessed via subchannel 0, device 4711 via 
+subchannel 1, and subchannel 2 is a non-I/O subchannel.
+
+You should address a ccw device via its bus id (e.g. 0:4711); the device can
+be found under bus/ccw/devices/.
+
+All ccw devices export some data via sysfs additional to the standard 'name'
+and 'power' entries.
+
+cutype:	    The control unit type / model.
+
+devtype:    The device type / model, if applicable.
+
+online:     An interface to set the device online and offline.
+
+The device drivers can add entries to export per-device data and interfaces.
+
+There is also some data exported on a per-subchannel basis (see under
+bus/css/devices/):
+
+chpids:	    Via which chpids the device is connected.
+
+pimpampom:  The path installed, path available and path operational masks.
+
+There also might be additional data, for example for block devices.
+
+
+1.1 Bringing up a ccw device
+----------------------------
+
+This is done in several steps.
+
+a. Some drivers need several ccw devices to make up one device. This drivers
+   provide a 'chaining' interface (driver dependend) which allows to specify
+   which ccw devices form a device.
+b. Each driver provides one or more parameter interfaces where parameters can
+   be specified. These interfaces are also in the driver's responsibility.
+c. After a. and b. have been performed, if neccessary, the device is finally
+   brought up via the 'online' interface.
+
+
+1.2 Writing a driver for ccw devices
+------------------------------------
+
+The basic struct ccw_device and struct ccw_driver data structures can be found
+under include/asm/ccwdev.h.
+
+struct ccw_device {
+        spinlock_t *ccwlock;
+        struct ccw_device_private *private;
+	struct ccw_device_id id;	
+
+	struct ccw_driver *drv;		
+	struct device dev;		
+	int online;
+
+	void (*handler) (struct ccw_device *dev, unsigned long intparm,
+                         struct irb *irb);
+};
+
+struct ccw_driver {
+	struct module *owner;		
+	struct ccw_device_id *ids;	
+	int (*probe) (struct ccw_device *); 
+	int (*remove) (struct ccw_device *);
+	void (*release) (struct ccw_driver *); 
+	int (*set_online) (struct ccw_device *);
+	int (*set_offline) (struct ccw_device *);
+	struct device_driver driver;
+	char *name;
+};
+
+The 'private' field contains data needed for internal i/o operation only, and
+is not available to the device driver.
+
+Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
+and/or device types/models it is interested. This information can later be found
+found in the struct ccw_device_id fields:
+
+struct ccw_device_id {
+	__u16	match_flags;	
+
+	__u16	cu_type;	
+	__u16	dev_type;	
+	__u8	cu_model;	
+	__u8	dev_model;	
+
+	unsigned long driver_info;
+};
+
+The functions in ccw_driver should be used in the following way:
+probe:   This function is called by the device layer for each device the driver
+	 is interested in. The driver should only allocate private structures
+	 to put in dev->driver_data and create attributes (if needed). Also,
+	 the interrupt handler (see below) should be set here.
+
+int (*probe) (struct ccw_device *cdev); 
+
+Parameters:  cdev     - the device to be probed.
+
+
+remove:  This function is called by the device layer upon removal of the driver,
+	 the device or the module. The driver should perform cleanups here.
+
+int (*remove) (struct ccw_device *cdev);
+
+Parameters:   cdev    - the device to be removed.
+
+
+set_online: This function is called by the common I/O layer when the device is
+	    activated via the 'online' attribute. The driver should finally
+	    setup and activate the device here.
+
+int (*set_online) (struct ccw_device *);
+
+Parameters:   cdev	- the device to be activated. The common layer has
+			  verified that the device is not already online.
+
+
+set_offline: This function is called by the common I/O layer when the device is
+	     de-activated via the 'online' attribute. The driver should shut
+	     down the device, but not de-allocate its private data.
+
+int (*set_offline) (struct ccw_device *);
+
+Parameters:   cdev       - the device to be deactivated. The common layer has
+			   verified that the device is online.
+
+
+The handler field of the struct ccw_device is meant to be set to the interrupt
+handler for the device. In order to accomodate drivers which use several 
+distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
+instead of ccw_driver.
+The handler is registered with the common layer during set_online() processing
+before the driver is called, and is deregistered during set_offline() after the
+driver has been called. Also, after registering / before deregistering, path 
+grouping resp. disbanding of the path group (if applicable) are performed.
+
+void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
+
+Parameters:	dev	- the device the handler is called for
+		intparm - the intparm which allows the device driver to identify
+                          the i/o the interrupt is associated with, or to recognize
+                          the interrupt as unsolicited.
+                irb     - interruption response block which contains the accumulated
+                          status.
+
+The device driver is called from the common ccw_device layer and can retrieve 
+information about the interrupt from the irb parameter.
+
+
+2. System devices
+-----------------
+
+2.1 Channel paths
+-----------------
+
+Every channel path is represented under sys/ as channel_path<nr>. (Unfortunately,
+<nr> is in decimal, which may look unfamiliar.)
+
+status - Can be 'online', 'logically offline' or 'n/a'.
+	 Piping 'on' or 'off' sets the chpid logically online/offline.
+
+
+2.2 xpram 
+---------
+
+xpram shows up under sys/ as 'xpram'.
+
+
+3. 'Legacy' devices
+-------------------
+
+The 'legacy' bus is for devices not detected, but specified by the user.
+
+
+3.1 Netiucv
+-----------
+
+Netiucv connections show up under legacy/ as "netiucv<ifnum>". The interface
+number is assigned sequentially at module load.
+
+user			  - the user the connection goes to.
+
+buffer			  - maximum buffer size.
+			    Pipe to it to change buffer size.
+
+