linux/Documentation/driver-model/porting.txt
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.