Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 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).