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