driver-api/driver-model/porting.rst

12 Please refer to `Documentation/driver-api/driver-model/*.rst` for definitions of
16 at the bus driver layer. This was intentional, to minimize the
18 of bus drivers.
21 be embedded in larger, bus-specific objects. Fields in these generic
22 objects can replace fields in the bus-specific objects.
28 	# mount -t sysfs sysfs /sys
36 Step 1: Registering the bus driver.
39 - Define a struct bus_type for the bus driver::
46 - Register the bus type.
48   This should be done in the initialization function for the bus type,
59   The bus type may be unregistered (if the bus driver may be compiled
65 - Export the bus type for others to use.
67   Other code may wish to reference the bus type, so declare it in a
81 - This will cause the bus to show up in /sys/bus/pci/ with two
84     # tree -d /sys/bus/pci/
85     /sys/bus/pci/
86     |-- devices
87     `-- drivers
97 - Embed a struct device in the bus-specific device type::
121   This allows the compiler to verify type-safety of the operations
125 - Initialize the device on registration.
127   When devices are discovered or registered with the bus type, the
128   bus driver should initialize the generic device. The most important
129   things to initialize are the bus_id, parent, and bus fields.
132   the bus. The format of this string is bus-specific. This is
136   the bus driver sets this field correctly.
149   The device's bus field is a pointer to the bus type the device
153   Optionally, the bus driver may set the device's name and release
165 - Register the device.
170        device_register(&dev->dev);
174        device_unregister(&dev->dev);
177   If a bus driver unregisters a device, it should not immediately free
179   device's release method, then free the bus-specific object.
189     |-- 00:00.0
190     |-- 00:01.0
191     |   `-- 01:00.0
192     |-- 00:02.0
193     |   `-- 02:1f.0
194     |       `-- 03:00.0
195     |-- 00:1e.0
196     |   `-- 04:04.0
197     |-- 00:1f.0
198     |-- 00:1f.1
199     |   |-- ide0
200     |   |   |-- 0.0
201     |   |   `-- 0.1
202     |   `-- ide1
203     |       `-- 1.0
204     |-- 00:1f.2
205     |-- 00:1f.3
206     `-- 00:1f.5
208   Also, symlinks are created in the bus's 'devices' directory
211     /sys/bus/pci/devices/
212     |-- 00:00.0 -> ../../../devices/pci0/00:00.0
213     |-- 00:01.0 -> ../../../devices/pci0/00:01.0
214     |-- 00:02.0 -> ../../../devices/pci0/00:02.0
215     |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
216     |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
217     |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
218     |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
219     |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
220     |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
221     |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
222     |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
223     |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
224     `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
234 - Embed a struct device_driver in the bus-specific driver.
244 - Initialize the generic driver structure.
246   When the driver registers with the bus (e.g. doing pci_register_driver()),
247   initialize the necessary fields of the driver: the name and bus
251 - Register the driver.
255 	driver_register(&drv->driver);
259   When the driver is unregistered from the bus, unregister it from the
262         driver_unregister(&drv->driver);
268 - Sysfs representation.
270   Drivers are exported via sysfs in their bus's 'driver's directory.
273     /sys/bus/pci/drivers/
274     |-- 3c59x
275     |-- Ensoniq AudioPCI
276     |-- agpgart-amdk7
277     |-- e100
278     `-- serial
285 operations the bus already defines for drivers, but taking different
288 It would be difficult and tedious to force every driver on a bus to
290 bus driver should define single instances of the generic methods that
291 forward call to the bus-specific drivers. For instance::
297           struct pci_driver * drv = pci_dev->driver;
300                   if (drv->remove)
301                           drv->remove(pci_dev);
302                   pci_dev->driver = NULL;
312         drv->driver.name = drv->name;
313         drv->driver.bus = &pci_bus_type;
314         drv->driver.probe = pci_device_probe;
315         drv->driver.resume = pci_device_resume;
316         drv->driver.suspend = pci_device_suspend;
317         drv->driver.remove = pci_device_remove;
320         driver_register(&drv->driver);
323 Ideally, the bus should only initialize the fields if they are not
331 registered with the bus at any time. When registration happens,
336 bus driver compares these IDs to the IDs of devices registered with it.
338 bus-specific, so the generic model does attempt to generalize them.
340 Instead, a bus may supply a method in struct bus_type that does the
347 -EPROBE_DEFER) if determining that given driver supports the device is
350 When a device is registered, the bus's list of drivers is iterated
351 over. bus->match() is called for each one until a match is found.
353 When a driver is registered, the bus's list of devices is iterated
354 over. bus->match() is called for each device that is not already
357 When a device is successfully bound to a driver, device->driver is
358 set, the device is added to a per-driver list of devices, and a
362   /sys/bus/pci/drivers/
363   |-- 3c59x
364   |   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
365   |-- Ensoniq AudioPCI
366   |-- agpgart-amdk7
367   |   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
368   |-- e100
369   |   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
370   `-- serial
374 mechanism the bus currently uses.
387 - ACTION: set to 'add' or 'remove'
388 - DEVPATH: set to the device's physical path in sysfs.
390 A bus driver may also supply additional parameters for userspace to
391 consume. To do this, a bus must implement the 'hotplug' method in
400 Step 7: Cleaning up the bus driver.
402 The generic bus, device, and driver structures provide several fields
403 that can replace those defined privately to the bus driver.
405 - Device list.
407 struct bus_type contains a list of all devices registered with the bus
408 type. This includes all devices on all instances of that bus type.
409 An internal list that the bus uses may be removed, in favor of using
414   int bus_for_each_dev(struct bus_type * bus, struct device * start,
418 - Driver list.
421 it. An internal list of drivers that the bus driver maintains may
426   int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
430 Please see drivers/base/bus.c for more information.
433 - rwsem
436 the device and driver lists. This can be used by the bus driver
438 lists the bus maintains.
441 - Device and driver fields.
444 fields in the bus-specific representations of these objects. Feel free
445 to remove the bus-specific ones and favor the generic ones. Note
447 reference the bus-specific fields (though those should all be 1-line