Documentation/driver-api/driver-model/driver.rst

   1 ==============
   2 Device Drivers
   3 ==============
   4
   5 See the kerneldoc for the struct device_driver.
   6
   7 Allocation
   8 ~~~~~~~~~~
   9
  10 Device drivers are statically allocated structures. Though there may
  11 be multiple devices in a system that a driver supports, struct
  12 device_driver represents the driver as a whole (not a particular
  13 device instance).
  14
  15 Initialization
  16 ~~~~~~~~~~~~~~
  17
  18 The driver must initialize at least the name and bus fields. It should
  19 also initialize the devclass field (when it arrives), so it may obtain
  20 the proper linkage internally. It should also initialize as many of
  21 the callbacks as possible, though each is optional.
  22
  23 Declaration
  24 ~~~~~~~~~~~
  25
  26 As stated above, struct device_driver objects are statically
  27 allocated. Below is an example declaration of the eepro100
  28 driver. This declaration is hypothetical only; it relies on the driver
  29 being converted completely to the new model::
  30
  31   static struct device_driver eepro100_driver = {
  32          .name          = "eepro100",
  33          .bus           = &pci_bus_type,
  34
  35          .probe         = eepro100_probe,
  36          .remove                = eepro100_remove,
  37          .suspend               = eepro100_suspend,
  38          .resume                = eepro100_resume,
  39   };
  40
  41 Most drivers will not be able to be converted completely to the new
  42 model because the bus they belong to has a bus-specific structure with
  43 bus-specific fields that cannot be generalized.
  44
  45 The most common example of this are device ID structures. A driver
  46 typically defines an array of device IDs that it supports. The format
  47 of these structures and the semantics for comparing device IDs are
  48 completely bus-specific. Defining them as bus-specific entities would
  49 sacrifice type-safety, so we keep bus-specific structures around.
  50
  51 Bus-specific drivers should include a generic struct device_driver in
  52 the definition of the bus-specific driver. Like this::
  53
  54   struct pci_driver {
  55          const struct pci_device_id *id_table;
  56          struct device_driver     driver;
  57   };
  58
  59 A definition that included bus-specific fields would look like
  60 (using the eepro100 driver again)::
  61
  62   static struct pci_driver eepro100_driver = {
  63          .id_table       = eepro100_pci_tbl,
  64          .driver               = {
  65                 .name           = "eepro100",
  66                 .bus            = &pci_bus_type,
  67                 .probe          = eepro100_probe,
  68                 .remove         = eepro100_remove,
  69                 .suspend        = eepro100_suspend,
  70                 .resume         = eepro100_resume,
  71          },
  72   };
  73
  74 Some may find the syntax of embedded struct initialization awkward or
  75 even a bit ugly. So far, it's the best way we've found to do what we want...
  76
  77 Registration
  78 ~~~~~~~~~~~~
  79
  80 ::
  81
  82   int driver_register(struct device_driver *drv);
  83
  84 The driver registers the structure on startup. For drivers that have
  85 no bus-specific fields (i.e. don't have a bus-specific driver
  86 structure), they would use driver_register and pass a pointer to their
  87 struct device_driver object.
  88
  89 Most drivers, however, will have a bus-specific structure and will
  90 need to register with the bus using something like pci_driver_register.
  91
  92 It is important that drivers register their driver structure as early as
  93 possible. Registration with the core initializes several fields in the
  94 struct device_driver object, including the reference count and the
  95 lock. These fields are assumed to be valid at all times and may be
  96 used by the device model core or the bus driver.
  97
  98
  99 Transition Bus Drivers
 100 ~~~~~~~~~~~~~~~~~~~~~~
 101
 102 By defining wrapper functions, the transition to the new model can be
 103 made easier. Drivers can ignore the generic structure altogether and
 104 let the bus wrapper fill in the fields. For the callbacks, the bus can
 105 define generic callbacks that forward the call to the bus-specific
 106 callbacks of the drivers.
 107
 108 This solution is intended to be only temporary. In order to get class
 109 information in the driver, the drivers must be modified anyway. Since
 110 converting drivers to the new model should reduce some infrastructural
 111 complexity and code size, it is recommended that they are converted as
 112 class information is added.
 113
 114 Access
 115 ~~~~~~
 116
 117 Once the object has been registered, it may access the common fields of
 118 the object, like the lock and the list of devices::
 119
 120   int driver_for_each_dev(struct device_driver *drv, void *data,
 121                           int (*callback)(struct device *dev, void *data));
 122
 123 The devices field is a list of all the devices that have been bound to
 124 the driver. The LDM core provides a helper function to operate on all
 125 the devices a driver controls. This helper locks the driver on each
 126 node access, and does proper reference counting on each device as it
 127 accesses it.
 128
 129
 130 sysfs
 131 ~~~~~
 132
 133 When a driver is registered, a sysfs directory is created in its
 134 bus's directory. In this directory, the driver can export an interface
 135 to userspace to control operation of the driver on a global basis;
 136 e.g. toggling debugging output in the driver.
 137
 138 A future feature of this directory will be a 'devices' directory. This
 139 directory will contain symlinks to the directories of devices it
 140 supports.
 141
 142
 143
 144 Callbacks
 145 ~~~~~~~~~
 146
 147 ::
 148
 149         int     (*probe)        (struct device *dev);
 150
 151 The probe() entry is called in task context, with the bus's rwsem locked
 152 and the driver partially bound to the device.  Drivers commonly use
 153 container_of() to convert "dev" to a bus-specific type, both in probe()
 154 and other routines.  That type often provides device resource data, such
 155 as pci_dev.resource[] or platform_device.resources, which is used in
 156 addition to dev->platform_data to initialize the driver.
 157
 158 This callback holds the driver-specific logic to bind the driver to a
 159 given device.  That includes verifying that the device is present, that
 160 it's a version the driver can handle, that driver data structures can
 161 be allocated and initialized, and that any hardware can be initialized.
 162 Drivers often store a pointer to their state with dev_set_drvdata().
 163 When the driver has successfully bound itself to that device, then probe()
 164 returns zero and the driver model code will finish its part of binding
 165 the driver to that device.
 166
 167 A driver's probe() may return a negative errno value to indicate that
 168 the driver did not bind to this device, in which case it should have
 169 released all resources it allocated.
 170
 171 Optionally, probe() may return -EPROBE_DEFER if the driver depends on
 172 resources that are not yet available (e.g., supplied by a driver that
 173 hasn't initialized yet).  The driver core will put the device onto the
 174 deferred probe list and will try to call it again later. If a driver
 175 must defer, it should return -EPROBE_DEFER as early as possible to
 176 reduce the amount of time spent on setup work that will need to be
 177 unwound and reexecuted at a later time.
 178
 179 .. warning::
 180       -EPROBE_DEFER must not be returned if probe() has already created
 181       child devices, even if those child devices are removed again
 182       in a cleanup path. If -EPROBE_DEFER is returned after a child
 183       device has been registered, it may result in an infinite loop of
 184       .probe() calls to the same driver.
 185
 186 ::
 187
 188         void    (*sync_state)   (struct device *dev);
 189
 190 sync_state is called only once for a device. It's called when all the consumer
 191 devices of the device have successfully probed. The list of consumers of the
 192 device is obtained by looking at the device links connecting that device to its
 193 consumer devices.
 194
 195 The first attempt to call sync_state() is made during late_initcall_sync() to
 196 give firmware and drivers time to link devices to each other. During the first
 197 attempt at calling sync_state(), if all the consumers of the device at that
 198 point in time have already probed successfully, sync_state() is called right
 199 away. If there are no consumers of the device during the first attempt, that
 200 too is considered as "all consumers of the device have probed" and sync_state()
 201 is called right away.
 202
 203 If during the first attempt at calling sync_state() for a device, there are
 204 still consumers that haven't probed successfully, the sync_state() call is
 205 postponed and reattempted in the future only when one or more consumers of the
 206 device probe successfully. If during the reattempt, the driver core finds that
 207 there are one or more consumers of the device that haven't probed yet, then
 208 sync_state() call is postponed again.
 209
 210 A typical use case for sync_state() is to have the kernel cleanly take over
 211 management of devices from the bootloader. For example, if a device is left on
 212 and at a particular hardware configuration by the bootloader, the device's
 213 driver might need to keep the device in the boot configuration until all the
 214 consumers of the device have probed. Once all the consumers of the device have
 215 probed, the device's driver can synchronize the hardware state of the device to
 216 match the aggregated software state requested by all the consumers. Hence the
 217 name sync_state().
 218
 219 While obvious examples of resources that can benefit from sync_state() include
 220 resources such as regulator, sync_state() can also be useful for complex
 221 resources like IOMMUs. For example, IOMMUs with multiple consumers (devices
 222 whose addresses are remapped by the IOMMU) might need to keep their mappings
 223 fixed at (or additive to) the boot configuration until all its consumers have
 224 probed.
 225
 226 While the typical use case for sync_state() is to have the kernel cleanly take
 227 over management of devices from the bootloader, the usage of sync_state() is
 228 not restricted to that. Use it whenever it makes sense to take an action after
 229 all the consumers of a device have probed::
 230
 231         int     (*remove)       (struct device *dev);
 232
 233 remove is called to unbind a driver from a device. This may be
 234 called if a device is physically removed from the system, if the
 235 driver module is being unloaded, during a reboot sequence, or
 236 in other cases.
 237
 238 It is up to the driver to determine if the device is present or
 239 not. It should free any resources allocated specifically for the
 240 device; i.e. anything in the device's driver_data field.
 241
 242 If the device is still present, it should quiesce the device and place
 243 it into a supported low-power state.
 244
 245 ::
 246
 247         int     (*suspend)      (struct device *dev, pm_message_t state);
 248
 249 suspend is called to put the device in a low power state.
 250
 251 ::
 252
 253         int     (*resume)       (struct device *dev);
 254
 255 Resume is used to bring a device back from a low power state.
 256
 257
 258 Attributes
 259 ~~~~~~~~~~
 260
 261 ::
 262
 263   struct driver_attribute {
 264           struct attribute        attr;
 265           ssize_t (*show)(struct device_driver *driver, char *buf);
 266           ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
 267   };
 268
 269 Device drivers can export attributes via their sysfs directories.
 270 Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
 271 macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
 272 macros.
 273
 274 Example::
 275
 276         DRIVER_ATTR_RW(debug);
 277
 278 This is equivalent to declaring::
 279
 280         struct driver_attribute driver_attr_debug;
 281
 282 This can then be used to add and remove the attribute from the
 283 driver's directory using::
 284
 285   int driver_create_file(struct device_driver *, const struct driver_attribute *);
 286   void driver_remove_file(struct device_driver *, const struct driver_attribute *);