driver-api/driver-model/porting.rst

12 Please refer to `Documentation/driver-api/driver-model/*.rst` for definitions of
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
34 Step 0: Read include/linux/device.h for object and function definitions.
39 - Define a struct bus_type for the bus driver::
46 - Register the bus type.
65 - Export the bus type for others to use.
81 - This will cause the bus to show up in /sys/bus/pci/ with two
84     # tree -d /sys/bus/pci/
86     |-- devices
87     `-- drivers
93 struct device represents a single device. It mainly contains metadata
94 describing the relationship the device has to other entities.
97 - Embed a struct device in the bus-specific device type::
102            struct  device  dev;            /* Generic device interface */
106   It is recommended that the generic device not be the first item in
121   This allows the compiler to verify type-safety of the operations
125 - Initialize the device on registration.
128   bus driver should initialize the generic device. The most important
131   The bus_id is an ASCII string that contains the device's address on
132   the bus. The format of this string is bus-specific. This is
135   parent is the physical parent of the device. It is important that
144   Also, the location of the device's sysfs directory depends on a
145   device's parent. sysfs exports a directory structure that mirrors
146   the device hierarchy. Accurately setting the parent guarantees that
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
156   The name field is an ASCII string describing the device, like
161   when the device has been removed, and all references to it have
165 - Register the device.
167   Once the generic device has been initialized, it can be registered
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.
180   (There may be other code that is currently referencing the device
181   structure, and it would be rude to free the device while that is
185   When the device is registered, a directory in sysfs is created.
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
209   that point to the device's directory in the physical hierarchy::
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.
251 - Register the driver.
255 	driver_register(&drv->driver);
262         driver_unregister(&drv->driver);
268 - Sysfs representation.
274     |-- 3c59x
275     |-- Ensoniq AudioPCI
276     |-- agpgart-amdk7
277     |-- e100
278     `-- serial
291 forward call to the bus-specific drivers. For instance::
294   static int pci_device_remove(struct device * dev)
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);
330 The model assumes that a device or driver can be dynamically
335 A driver typically contains a list of device IDs that it supports. The
337 The format of the device IDs, and the semantics for comparing them are
338 bus-specific, so the generic model does attempt to generalize them.
343   int (*match)(struct device * dev, struct device_driver * drv);
345 match should return positive value if the driver supports the device,
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.
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
360 device's physical directory::
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
379 Whenever a device is registered with the driver model core, the
381 Users can define actions to perform when a device is inserted or
387 - ACTION: set to 'add' or 'remove'
388 - DEVPATH: set to the device's physical path in sysfs.
394      int (*hotplug) (struct device *dev, char **envp,
402 The generic bus, device, and driver structures provide several fields
405 - Device list.
414   int bus_for_each_dev(struct bus_type * bus, struct device * start,
415                        void * data, int (*fn)(struct device *, void *));
418 - Driver list.
433 - rwsem
436 the device and driver lists. This can be used by the bus driver
437 internally, and should be used when accessing the device or driver
441 - Device and driver fields.
443 Some of the fields in struct device and struct device_driver duplicate
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