PageRenderTime 13ms CodeModel.GetById 1ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/Documentation/s390/driver-model.txt

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