About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / driver-model / porting.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

1	
2	Porting Drivers to the New Driver Model
3	
4	Patrick Mochel
5	
6	7 January 2003
7	
8	
9	Overview
10	
11	Please refer to Documentation/driver-model/*.txt for definitions of
12	various driver types and concepts. 
13	
14	Most of the work of porting devices drivers to the new model happens
15	at the bus driver layer. This was intentional, to minimize the
16	negative effect on kernel drivers, and to allow a gradual transition
17	of bus drivers.
18	
19	In a nutshell, the driver model consists of a set of objects that can
20	be embedded in larger, bus-specific objects. Fields in these generic
21	objects can replace fields in the bus-specific objects. 
22	
23	The generic objects must be registered with the driver model core. By
24	doing so, they will exported via the sysfs filesystem. sysfs can be
25	mounted by doing 
26	
27		# mount -t sysfs sysfs /sys
28	
29	
30	
31	The Process
32	
33	Step 0: Read include/linux/device.h for object and function definitions. 
34	
35	Step 1: Registering the bus driver. 
36	
37	
38	- Define a struct bus_type for the bus driver.
39	
40	struct bus_type pci_bus_type = {
41	        .name           = "pci",
42	};
43	
44	
45	- Register the bus type.
46	  This should be done in the initialization function for the bus type,
47	  which is usually the module_init(), or equivalent, function. 
48	
49	static int __init pci_driver_init(void)
50	{
51	        return bus_register(&pci_bus_type);
52	}
53	
54	subsys_initcall(pci_driver_init);
55	
56	
57	  The bus type may be unregistered (if the bus driver may be compiled
58	  as a module) by doing:
59	
60	     bus_unregister(&pci_bus_type);
61	
62	
63	- Export the bus type for others to use. 
64	
65	  Other code may wish to reference the bus type, so declare it in a 
66	  shared header file and export the symbol.
67	
68	From include/linux/pci.h:
69	
70	extern struct bus_type pci_bus_type;
71	
72	
73	From file the above code appears in:
74	
75	EXPORT_SYMBOL(pci_bus_type);
76	
77	
78	
79	- This will cause the bus to show up in /sys/bus/pci/ with two
80	  subdirectories: 'devices' and 'drivers'.
81	
82	# tree -d /sys/bus/pci/
83	/sys/bus/pci/
84	|-- devices
85	`-- drivers
86	
87	
88	
89	Step 2: Registering Devices. 
90	
91	struct device represents a single device. It mainly contains metadata
92	describing the relationship the device has to other entities. 
93	
94	
95	- Embed a struct device in the bus-specific device type. 
96	
97	
98	struct pci_dev {
99	       ...
100	       struct  device  dev;            /* Generic device interface */
101	       ...
102	};
103	
104	  It is recommended that the generic device not be the first item in 
105	  the struct to discourage programmers from doing mindless casts
106	  between the object types. Instead macros, or inline functions,
107	  should be created to convert from the generic object type.
108	
109	
110	#define to_pci_dev(n) container_of(n, struct pci_dev, dev)
111	
112	or 
113	
114	static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
115	{
116		return container_of(n, struct pci_dev, dev);
117	}
118	
119	  This allows the compiler to verify type-safety of the operations 
120	  that are performed (which is Good).
121	
122	
123	- Initialize the device on registration.
124	
125	  When devices are discovered or registered with the bus type, the 
126	  bus driver should initialize the generic device. The most important
127	  things to initialize are the bus_id, parent, and bus fields.
128	
129	  The bus_id is an ASCII string that contains the device's address on
130	  the bus. The format of this string is bus-specific. This is
131	  necessary for representing devices in sysfs. 
132	
133	  parent is the physical parent of the device. It is important that
134	  the bus driver sets this field correctly. 
135	
136	  The driver model maintains an ordered list of devices that it uses
137	  for power management. This list must be in order to guarantee that
138	  devices are shutdown before their physical parents, and vice versa.
139	  The order of this list is determined by the parent of registered
140	  devices.
141	
142	  Also, the location of the device's sysfs directory depends on a
143	  device's parent. sysfs exports a directory structure that mirrors 
144	  the device hierarchy. Accurately setting the parent guarantees that
145	  sysfs will accurately represent the hierarchy.
146	
147	  The device's bus field is a pointer to the bus type the device
148	  belongs to. This should be set to the bus_type that was declared
149	  and initialized before. 
150	
151	  Optionally, the bus driver may set the device's name and release
152	  fields.
153	
154	  The name field is an ASCII string describing the device, like
155	
156	     "ATI Technologies Inc Radeon QD"
157	
158	  The release field is a callback that the driver model core calls 
159	  when the device has been removed, and all references to it have 
160	  been released. More on this in a moment.
161	
162	
163	- Register the device. 
164	
165	  Once the generic device has been initialized, it can be registered
166	  with the driver model core by doing:
167	
168	       device_register(&dev->dev);
169	
170	  It can later be unregistered by doing: 
171	
172	       device_unregister(&dev->dev);
173	
174	  This should happen on buses that support hotpluggable devices. 
175	  If a bus driver unregisters a device, it should not immediately free
176	  it. It should instead wait for the driver model core to call the 
177	  device's release method, then free the bus-specific object. 
178	  (There may be other code that is currently referencing the device
179	  structure, and it would be rude to free the device while that is 
180	  happening).
181	
182	
183	  When the device is registered, a directory in sysfs is created. 
184	  The PCI tree in sysfs looks like: 
185	
186	/sys/devices/pci0/
187	|-- 00:00.0
188	|-- 00:01.0
189	|   `-- 01:00.0
190	|-- 00:02.0
191	|   `-- 02:1f.0
192	|       `-- 03:00.0
193	|-- 00:1e.0
194	|   `-- 04:04.0
195	|-- 00:1f.0
196	|-- 00:1f.1
197	|   |-- ide0
198	|   |   |-- 0.0
199	|   |   `-- 0.1
200	|   `-- ide1
201	|       `-- 1.0
202	|-- 00:1f.2
203	|-- 00:1f.3
204	`-- 00:1f.5
205	
206	  Also, symlinks are created in the bus's 'devices' directory
207	  that point to the device's directory in the physical hierarchy. 
208	
209	/sys/bus/pci/devices/
210	|-- 00:00.0 -> ../../../devices/pci0/00:00.0
211	|-- 00:01.0 -> ../../../devices/pci0/00:01.0
212	|-- 00:02.0 -> ../../../devices/pci0/00:02.0
213	|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
214	|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
215	|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
216	|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
217	|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
218	|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
219	|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
220	|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
221	|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
222	`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
223	
224	
225	
226	Step 3: Registering Drivers.
227	
228	struct device_driver is a simple driver structure that contains a set
229	of operations that the driver model core may call. 
230	
231	
232	- Embed a struct device_driver in the bus-specific driver. 
233	
234	  Just like with devices, do something like:
235	
236	struct pci_driver {
237	       ...
238	       struct device_driver    driver;
239	};
240	
241	
242	- Initialize the generic driver structure. 
243	
244	  When the driver registers with the bus (e.g. doing pci_register_driver()),
245	  initialize the necessary fields of the driver: the name and bus
246	  fields. 
247	
248	
249	- Register the driver.
250	
251	  After the generic driver has been initialized, call
252	
253		driver_register(&drv->driver);
254	
255	  to register the driver with the core.
256	
257	  When the driver is unregistered from the bus, unregister it from the
258	  core by doing:
259	
260	        driver_unregister(&drv->driver);
261	
262	  Note that this will block until all references to the driver have
263	  gone away. Normally, there will not be any.
264	
265	
266	- Sysfs representation.
267	
268	  Drivers are exported via sysfs in their bus's 'driver's directory. 
269	  For example:
270	
271	/sys/bus/pci/drivers/
272	|-- 3c59x
273	|-- Ensoniq AudioPCI
274	|-- agpgart-amdk7
275	|-- e100
276	`-- serial
277	
278	
279	Step 4: Define Generic Methods for Drivers.
280	
281	struct device_driver defines a set of operations that the driver model
282	core calls. Most of these operations are probably similar to
283	operations the bus already defines for drivers, but taking different
284	parameters. 
285	
286	It would be difficult and tedious to force every driver on a bus to
287	simultaneously convert their drivers to generic format. Instead, the
288	bus driver should define single instances of the generic methods that
289	forward call to the bus-specific drivers. For instance: 
290	
291	
292	static int pci_device_remove(struct device * dev)
293	{
294	        struct pci_dev * pci_dev = to_pci_dev(dev);
295	        struct pci_driver * drv = pci_dev->driver;
296	
297	        if (drv) {
298	                if (drv->remove)
299	                        drv->remove(pci_dev);
300	                pci_dev->driver = NULL;
301	        }
302	        return 0;
303	}
304	
305	
306	The generic driver should be initialized with these methods before it
307	is registered. 
308	
309	        /* initialize common driver fields */
310	        drv->driver.name = drv->name;
311	        drv->driver.bus = &pci_bus_type;
312	        drv->driver.probe = pci_device_probe;
313	        drv->driver.resume = pci_device_resume;
314	        drv->driver.suspend = pci_device_suspend;
315	        drv->driver.remove = pci_device_remove;
316	
317	        /* register with core */
318	        driver_register(&drv->driver);
319	
320	
321	Ideally, the bus should only initialize the fields if they are not
322	already set. This allows the drivers to implement their own generic
323	methods. 
324	
325	
326	Step 5: Support generic driver binding. 
327	
328	The model assumes that a device or driver can be dynamically
329	registered with the bus at any time. When registration happens,
330	devices must be bound to a driver, or drivers must be bound to all
331	devices that it supports. 
332	
333	A driver typically contains a list of device IDs that it supports. The
334	bus driver compares these IDs to the IDs of devices registered with it. 
335	The format of the device IDs, and the semantics for comparing them are
336	bus-specific, so the generic model does attempt to generalize them. 
337	
338	Instead, a bus may supply a method in struct bus_type that does the
339	comparison: 
340	
341	  int (*match)(struct device * dev, struct device_driver * drv);
342	
343	match should return positive value if the driver supports the device,
344	and zero otherwise. It may also return error code (for example
345	-EPROBE_DEFER) if determining that given driver supports the device is
346	not possible.
347	
348	When a device is registered, the bus's list of drivers is iterated
349	over. bus->match() is called for each one until a match is found. 
350	
351	When a driver is registered, the bus's list of devices is iterated
352	over. bus->match() is called for each device that is not already
353	claimed by a driver. 
354	
355	When a device is successfully bound to a driver, device->driver is
356	set, the device is added to a per-driver list of devices, and a
357	symlink is created in the driver's sysfs directory that points to the
358	device's physical directory:
359	
360	/sys/bus/pci/drivers/
361	|-- 3c59x
362	|   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
363	|-- Ensoniq AudioPCI
364	|-- agpgart-amdk7
365	|   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
366	|-- e100
367	|   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
368	`-- serial
369	
370	
371	This driver binding should replace the existing driver binding
372	mechanism the bus currently uses. 
373	
374	
375	Step 6: Supply a hotplug callback.
376	
377	Whenever a device is registered with the driver model core, the
378	userspace program /sbin/hotplug is called to notify userspace. 
379	Users can define actions to perform when a device is inserted or
380	removed. 
381	
382	The driver model core passes several arguments to userspace via
383	environment variables, including
384	
385	- ACTION: set to 'add' or 'remove'
386	- DEVPATH: set to the device's physical path in sysfs. 
387	
388	A bus driver may also supply additional parameters for userspace to
389	consume. To do this, a bus must implement the 'hotplug' method in
390	struct bus_type:
391	
392	     int (*hotplug) (struct device *dev, char **envp, 
393	                     int num_envp, char *buffer, int buffer_size);
394	
395	This is called immediately before /sbin/hotplug is executed. 
396	
397	
398	Step 7: Cleaning up the bus driver.
399	
400	The generic bus, device, and driver structures provide several fields
401	that can replace those defined privately to the bus driver. 
402	
403	- Device list.
404	
405	struct bus_type contains a list of all devices registered with the bus
406	type. This includes all devices on all instances of that bus type.
407	An internal list that the bus uses may be removed, in favor of using
408	this one.
409	
410	The core provides an iterator to access these devices. 
411	
412	int bus_for_each_dev(struct bus_type * bus, struct device * start, 
413	                     void * data, int (*fn)(struct device *, void *));
414	
415	
416	- Driver list.
417	
418	struct bus_type also contains a list of all drivers registered with
419	it. An internal list of drivers that the bus driver maintains may 
420	be removed in favor of using the generic one. 
421	
422	The drivers may be iterated over, like devices: 
423	
424	int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
425	                     void * data, int (*fn)(struct device_driver *, void *));
426	
427	
428	Please see drivers/base/bus.c for more information.
429	
430	
431	- rwsem 
432	
433	struct bus_type contains an rwsem that protects all core accesses to
434	the device and driver lists. This can be used by the bus driver
435	internally, and should be used when accessing the device or driver
436	lists the bus maintains. 
437	
438	
439	- Device and driver fields. 
440	
441	Some of the fields in struct device and struct device_driver duplicate
442	fields in the bus-specific representations of these objects. Feel free
443	to remove the bus-specific ones and favor the generic ones. Note
444	though, that this will likely mean fixing up all the drivers that
445	reference the bus-specific fields (though those should all be 1-line
446	changes).
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.