About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / s390 / driver-model.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

1	S/390 driver model interfaces
2	-----------------------------
3	
4	1. CCW devices
5	--------------
6	
7	All devices which can be addressed by means of ccws are called 'CCW devices' -
8	even if they aren't actually driven by ccws.
9	
10	All ccw devices are accessed via a subchannel, this is reflected in the 
11	structures under devices/:
12	
13	devices/
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	
23	In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
24	device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
25	subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
26	
27	The subchannel named 'defunct' does not represent any real subchannel on the
28	system; it is a pseudo subchannel where disconnected ccw devices are moved to
29	if they are displaced by another ccw device becoming operational on their
30	former subchannel. The ccw devices will be moved again to a proper subchannel
31	if they become operational again on that subchannel.
32	
33	You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
34	be found under bus/ccw/devices/.
35	
36	All ccw devices export some data via sysfs.
37	
38	cutype:	    The control unit type / model.
39	
40	devtype:    The device type / model, if applicable.
41	
42	availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
43		      disconnected devices.
44	
45	online:     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	
50	The device drivers can add entries to export per-device data and interfaces.
51	
52	There is also some data exported on a per-subchannel basis (see under
53	bus/css/devices/):
54	
55	chpids:	    Via which chpids the device is connected.
56	
57	pimpampom:  The path installed, path available and path operational masks.
58	
59	There also might be additional data, for example for block devices.
60	
61	
62	1.1 Bringing up a ccw device
63	----------------------------
64	
65	This is done in several steps.
66	
67	a. Each driver can provide one or more parameter interfaces where parameters can
68	   be specified. These interfaces are also in the driver's responsibility.
69	b. After a. has been performed, if necessary, the device is finally brought up
70	   via the 'online' interface.
71	
72	
73	1.2 Writing a driver for ccw devices
74	------------------------------------
75	
76	The basic struct ccw_device and struct ccw_driver data structures can be found
77	under include/asm/ccwdev.h.
78	
79	struct 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	
92	struct 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	
104	The 'private' field contains data needed for internal i/o operation only, and
105	is not available to the device driver.
106	
107	Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
108	and/or device types/models it is interested. This information can later be found
109	in the struct ccw_device_id fields:
110	
111	struct 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	
122	The functions in ccw_driver should be used in the following way:
123	probe:   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	
128	int (*probe) (struct ccw_device *cdev); 
129	
130	Parameters:  cdev     - the device to be probed.
131	
132	
133	remove:  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	
136	int (*remove) (struct ccw_device *cdev);
137	
138	Parameters:   cdev    - the device to be removed.
139	
140	
141	set_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	
145	int (*set_online) (struct ccw_device *);
146	
147	Parameters:   cdev	- the device to be activated. The common layer has
148				  verified that the device is not already online.
149	
150	
151	set_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	
155	int (*set_offline) (struct ccw_device *);
156	
157	Parameters:   cdev       - the device to be deactivated. The common layer has
158				   verified that the device is online.
159	
160	
161	notify: 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		
177	int (*notify) (struct ccw_device *, int);
178	
179	Parameters:   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	
183	The handler field of the struct ccw_device is meant to be set to the interrupt
184	handler for the device. In order to accommodate drivers which use several 
185	distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
186	instead of ccw_driver.
187	The handler is registered with the common layer during set_online() processing
188	before the driver is called, and is deregistered during set_offline() after the
189	driver has been called. Also, after registering / before deregistering, path 
190	grouping resp. disbanding of the path group (if applicable) are performed.
191	
192	void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
193	
194	Parameters:	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	
201	The device driver is called from the common ccw_device layer and can retrieve 
202	information about the interrupt from the irb parameter.
203	
204	
205	1.3 ccwgroup devices
206	--------------------
207	
208	The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
209	devices, like lcs or ctc.
210	
211	The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
212	this attributes creates a ccwgroup device consisting of these ccw devices (if
213	possible). This ccwgroup device can be set online or offline just like a normal
214	ccw device.
215	
216	Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
217	again (only when offline). This is a generic ccwgroup mechanism (the driver does
218	not need to implement anything beyond normal removal routines).
219	
220	A ccw device which is a member of a ccwgroup device carries a pointer to the
221	ccwgroup device in the driver_data of its device struct. This field must not be
222	touched by the driver - it should use the ccwgroup device's driver_data for its
223	private data.
224	
225	To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
226	mind that most drivers will need to implement both a ccwgroup and a ccw
227	driver.
228	
229	
230	2. Channel paths
231	-----------------
232	
233	Channel paths show up, like subchannels, under the channel subsystem root (css0)
234	and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
235	Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
236	only the logical state and not the physical state, since we cannot track the
237	latter consistently due to lacking machine support (we don't need to be aware
238	of it anyway).
239	
240	status - 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	
247	type - The physical type of the channel path.
248	
249	shared - Whether the channel path is shared.
250	
251	cmg - The channel measurement group.
252	
253	3. System devices
254	-----------------
255	
256	3.1 xpram 
257	---------
258	
259	xpram shows up under devices/system/ as 'xpram'.
260	
261	3.2 cpus
262	--------
263	
264	For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
265	attribute 'online' which can be 0 or 1.
266	
267	
268	4. Other devices
269	----------------
270	
271	4.1 Netiucv
272	-----------
273	
274	The netiucv driver creates an attribute 'connection' under
275	bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
276	connection to the specified host.
277	
278	Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
279	number is assigned sequentially to the connections defined via the 'connection'
280	attribute.
281	
282	user			  - shows the connection partner.
283	
284	buffer			  - maximum buffer size.
285				    Pipe to it to change buffer size.
286	
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.