Root/Documentation/driver-model/porting.txt

1
2Porting Drivers to the New Driver Model
3
4Patrick Mochel
5
67 January 2003
7
8
9Overview
10
11Please refer to Documentation/driver-model/*.txt for definitions of
12various driver types and concepts.
13
14Most of the work of porting devices drivers to the new model happens
15at the bus driver layer. This was intentional, to minimize the
16negative effect on kernel drivers, and to allow a gradual transition
17of bus drivers.
18
19In a nutshell, the driver model consists of a set of objects that can
20be embedded in larger, bus-specific objects. Fields in these generic
21objects can replace fields in the bus-specific objects.
22
23The generic objects must be registered with the driver model core. By
24doing so, they will exported via the sysfs filesystem. sysfs can be
25mounted by doing
26
27    # mount -t sysfs sysfs /sys
28
29
30
31The Process
32
33Step 0: Read include/linux/device.h for object and function definitions.
34
35Step 1: Registering the bus driver.
36
37
38- Define a struct bus_type for the bus driver.
39
40struct 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
49static int __init pci_driver_init(void)
50{
51        return bus_register(&pci_bus_type);
52}
53
54subsys_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
68From include/linux/pci.h:
69
70extern struct bus_type pci_bus_type;
71
72
73From file the above code appears in:
74
75EXPORT_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
89Step 2: Registering Devices.
90
91struct device represents a single device. It mainly contains metadata
92describing the relationship the device has to other entities.
93
94
95- Embed a struct device in the bus-specific device type.
96
97
98struct 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
112or
113
114static 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
226Step 3: Registering Drivers.
227
228struct device_driver is a simple driver structure that contains a set
229of 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
236struct 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
279Step 4: Define Generic Methods for Drivers.
280
281struct device_driver defines a set of operations that the driver model
282core calls. Most of these operations are probably similar to
283operations the bus already defines for drivers, but taking different
284parameters.
285
286It would be difficult and tedious to force every driver on a bus to
287simultaneously convert their drivers to generic format. Instead, the
288bus driver should define single instances of the generic methods that
289forward call to the bus-specific drivers. For instance:
290
291
292static 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
306The generic driver should be initialized with these methods before it
307is 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
321Ideally, the bus should only initialize the fields if they are not
322already set. This allows the drivers to implement their own generic
323methods.
324
325
326Step 5: Support generic driver binding.
327
328The model assumes that a device or driver can be dynamically
329registered with the bus at any time. When registration happens,
330devices must be bound to a driver, or drivers must be bound to all
331devices that it supports.
332
333A driver typically contains a list of device IDs that it supports. The
334bus driver compares these IDs to the IDs of devices registered with it.
335The format of the device IDs, and the semantics for comparing them are
336bus-specific, so the generic model does attempt to generalize them.
337
338Instead, a bus may supply a method in struct bus_type that does the
339comparison:
340
341  int (*match)(struct device * dev, struct device_driver * drv);
342
343match should return '1' if the driver supports the device, and '0'
344otherwise.
345
346When a device is registered, the bus's list of drivers is iterated
347over. bus->match() is called for each one until a match is found.
348
349When a driver is registered, the bus's list of devices is iterated
350over. bus->match() is called for each device that is not already
351claimed by a driver.
352
353When a device is successfully bound to a driver, device->driver is
354set, the device is added to a per-driver list of devices, and a
355symlink is created in the driver's sysfs directory that points to the
356device's physical directory:
357
358/sys/bus/pci/drivers/
359|-- 3c59x
360| `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
361|-- Ensoniq AudioPCI
362|-- agpgart-amdk7
363| `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
364|-- e100
365| `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
366`-- serial
367
368
369This driver binding should replace the existing driver binding
370mechanism the bus currently uses.
371
372
373Step 6: Supply a hotplug callback.
374
375Whenever a device is registered with the driver model core, the
376userspace program /sbin/hotplug is called to notify userspace.
377Users can define actions to perform when a device is inserted or
378removed.
379
380The driver model core passes several arguments to userspace via
381environment variables, including
382
383- ACTION: set to 'add' or 'remove'
384- DEVPATH: set to the device's physical path in sysfs.
385
386A bus driver may also supply additional parameters for userspace to
387consume. To do this, a bus must implement the 'hotplug' method in
388struct bus_type:
389
390     int (*hotplug) (struct device *dev, char **envp,
391                     int num_envp, char *buffer, int buffer_size);
392
393This is called immediately before /sbin/hotplug is executed.
394
395
396Step 7: Cleaning up the bus driver.
397
398The generic bus, device, and driver structures provide several fields
399that can replace those defined privately to the bus driver.
400
401- Device list.
402
403struct bus_type contains a list of all devices registered with the bus
404type. This includes all devices on all instances of that bus type.
405An internal list that the bus uses may be removed, in favor of using
406this one.
407
408The core provides an iterator to access these devices.
409
410int bus_for_each_dev(struct bus_type * bus, struct device * start,
411                     void * data, int (*fn)(struct device *, void *));
412
413
414- Driver list.
415
416struct bus_type also contains a list of all drivers registered with
417it. An internal list of drivers that the bus driver maintains may
418be removed in favor of using the generic one.
419
420The drivers may be iterated over, like devices:
421
422int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
423                     void * data, int (*fn)(struct device_driver *, void *));
424
425
426Please see drivers/base/bus.c for more information.
427
428
429- rwsem
430
431struct bus_type contains an rwsem that protects all core accesses to
432the device and driver lists. This can be used by the bus driver
433internally, and should be used when accessing the device or driver
434lists the bus maintains.
435
436
437- Device and driver fields.
438
439Some of the fields in struct device and struct device_driver duplicate
440fields in the bus-specific representations of these objects. Feel free
441to remove the bus-specific ones and favor the generic ones. Note
442though, that this will likely mean fixing up all the drivers that
443reference the bus-specific fields (though those should all be 1-line
444changes).
445
446

Archive Download this file

Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master

Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9



interactive