Documentation/driver-model/driver.txt

   1
   2 Device Drivers
   3
   4 struct device_driver {
   5         char                    * name;
   6         struct bus_type         * bus;
   7
   8         struct completion       unloaded;
   9         struct kobject          kobj;
  10         list_t                  devices;
  11
  12         struct module           *owner;
  13
  14         int     (*probe)        (struct device * dev);
  15         int     (*remove)       (struct device * dev);
  16
  17         int     (*suspend)      (struct device * dev, pm_message_t state);
  18         int     (*resume)       (struct device * dev);
  19 };
  20
  21
  22
  23 Allocation
  24 ~~~~~~~~~~
  25
  26 Device drivers are statically allocated structures. Though there may
  27 be multiple devices in a system that a driver supports, struct
  28 device_driver represents the driver as a whole (not a particular
  29 device instance).
  30
  31 Initialization
  32 ~~~~~~~~~~~~~~
  33
  34 The driver must initialize at least the name and bus fields. It should
  35 also initialize the devclass field (when it arrives), so it may obtain
  36 the proper linkage internally. It should also initialize as many of
  37 the callbacks as possible, though each is optional.
  38
  39 Declaration
  40 ~~~~~~~~~~~
  41
  42 As stated above, struct device_driver objects are statically
  43 allocated. Below is an example declaration of the eepro100
  44 driver. This declaration is hypothetical only; it relies on the driver
  45 being converted completely to the new model.
  46
  47 static struct device_driver eepro100_driver = {
  48        .name            = "eepro100",
  49        .bus             = &pci_bus_type,
  50
  51        .probe           = eepro100_probe,
  52        .remove          = eepro100_remove,
  53        .suspend         = eepro100_suspend,
  54        .resume          = eepro100_resume,
  55 };
  56
  57 Most drivers will not be able to be converted completely to the new
  58 model because the bus they belong to has a bus-specific structure with
  59 bus-specific fields that cannot be generalized.
  60
  61 The most common example of this are device ID structures. A driver
  62 typically defines an array of device IDs that it supports. The format
  63 of these structures and the semantics for comparing device IDs are
  64 completely bus-specific. Defining them as bus-specific entities would
  65 sacrifice type-safety, so we keep bus-specific structures around.
  66
  67 Bus-specific drivers should include a generic struct device_driver in
  68 the definition of the bus-specific driver. Like this:
  69
  70 struct pci_driver {
  71        const struct pci_device_id *id_table;
  72        struct device_driver       driver;
  73 };
  74
  75 A definition that included bus-specific fields would look like
  76 (using the eepro100 driver again):
  77
  78 static struct pci_driver eepro100_driver = {
  79        .id_table       = eepro100_pci_tbl,
  80        .driver         = {
  81                 .name           = "eepro100",
  82                 .bus            = &pci_bus_type,
  83                 .probe          = eepro100_probe,
  84                 .remove         = eepro100_remove,
  85                 .suspend        = eepro100_suspend,
  86                 .resume         = eepro100_resume,
  87        },
  88 };
  89
  90 Some may find the syntax of embedded struct initialization awkward or
  91 even a bit ugly. So far, it's the best way we've found to do what we want...
  92
  93 Registration
  94 ~~~~~~~~~~~~
  95
  96 int driver_register(struct device_driver * drv);
  97
  98 The driver registers the structure on startup. For drivers that have
  99 no bus-specific fields (i.e. don't have a bus-specific driver
 100 structure), they would use driver_register and pass a pointer to their
 101 struct device_driver object.
 102
 103 Most drivers, however, will have a bus-specific structure and will
 104 need to register with the bus using something like pci_driver_register.
 105
 106 It is important that drivers register their driver structure as early as
 107 possible. Registration with the core initializes several fields in the
 108 struct device_driver object, including the reference count and the
 109 lock. These fields are assumed to be valid at all times and may be
 110 used by the device model core or the bus driver.
 111
 112
 113 Transition Bus Drivers
 114 ~~~~~~~~~~~~~~~~~~~~~~
 115
 116 By defining wrapper functions, the transition to the new model can be
 117 made easier. Drivers can ignore the generic structure altogether and
 118 let the bus wrapper fill in the fields. For the callbacks, the bus can
 119 define generic callbacks that forward the call to the bus-specific
 120 callbacks of the drivers.
 121
 122 This solution is intended to be only temporary. In order to get class
 123 information in the driver, the drivers must be modified anyway. Since
 124 converting drivers to the new model should reduce some infrastructural
 125 complexity and code size, it is recommended that they are converted as
 126 class information is added.
 127
 128 Access
 129 ~~~~~~
 130
 131 Once the object has been registered, it may access the common fields of
 132 the object, like the lock and the list of devices.
 133
 134 int driver_for_each_dev(struct device_driver * drv, void * data,
 135                         int (*callback)(struct device * dev, void * data));
 136
 137 The devices field is a list of all the devices that have been bound to
 138 the driver. The LDM core provides a helper function to operate on all
 139 the devices a driver controls. This helper locks the driver on each
 140 node access, and does proper reference counting on each device as it
 141 accesses it.
 142
 143
 144 sysfs
 145 ~~~~~
 146
 147 When a driver is registered, a sysfs directory is created in its
 148 bus's directory. In this directory, the driver can export an interface
 149 to userspace to control operation of the driver on a global basis;
 150 e.g. toggling debugging output in the driver.
 151
 152 A future feature of this directory will be a 'devices' directory. This
 153 directory will contain symlinks to the directories of devices it
 154 supports.
 155
 156
 157
 158 Callbacks
 159 ~~~~~~~~~
 160
 161         int     (*probe)        (struct device * dev);
 162
 163 The probe() entry is called in task context, with the bus's rwsem locked
 164 and the driver partially bound to the device.  Drivers commonly use
 165 container_of() to convert "dev" to a bus-specific type, both in probe()
 166 and other routines.  That type often provides device resource data, such
 167 as pci_dev.resource[] or platform_device.resources, which is used in
 168 addition to dev->platform_data to initialize the driver.
 169
 170 This callback holds the driver-specific logic to bind the driver to a
 171 given device.  That includes verifying that the device is present, that
 172 it's a version the driver can handle, that driver data structures can
 173 be allocated and initialized, and that any hardware can be initialized.
 174 Drivers often store a pointer to their state with dev_set_drvdata().
 175 When the driver has successfully bound itself to that device, then probe()
 176 returns zero and the driver model code will finish its part of binding
 177 the driver to that device.
 178
 179 A driver's probe() may return a negative errno value to indicate that
 180 the driver did not bind to this device, in which case it should have
 181 released all resources it allocated.
 182
 183         int     (*remove)       (struct device * dev);
 184
 185 remove is called to unbind a driver from a device. This may be
 186 called if a device is physically removed from the system, if the
 187 driver module is being unloaded, during a reboot sequence, or
 188 in other cases.
 189
 190 It is up to the driver to determine if the device is present or
 191 not. It should free any resources allocated specifically for the
 192 device; i.e. anything in the device's driver_data field.
 193
 194 If the device is still present, it should quiesce the device and place
 195 it into a supported low-power state.
 196
 197         int     (*suspend)      (struct device * dev, pm_message_t state);
 198
 199 suspend is called to put the device in a low power state.
 200
 201         int     (*resume)       (struct device * dev);
 202
 203 Resume is used to bring a device back from a low power state.
 204
 205
 206 Attributes
 207 ~~~~~~~~~~
 208 struct driver_attribute {
 209         struct attribute        attr;
 210         ssize_t (*show)(struct device_driver *, char * buf, size_t count, loff_t off);
 211         ssize_t (*store)(struct device_driver *, const char * buf, size_t count, loff_t off);
 212 };
 213
 214 Device drivers can export attributes via their sysfs directories.
 215 Drivers can declare attributes using a DRIVER_ATTR macro that works
 216 identically to the DEVICE_ATTR macro.
 217
 218 Example:
 219
 220 DRIVER_ATTR(debug,0644,show_debug,store_debug);
 221
 222 This is equivalent to declaring:
 223
 224 struct driver_attribute driver_attr_debug;
 225
 226 This can then be used to add and remove the attribute from the
 227 driver's directory using:
 228
 229 int driver_create_file(struct device_driver *, struct driver_attribute *);
 230 void driver_remove_file(struct device_driver *, struct driver_attribute *);