Documentation/driver-model/driver.txt

   1
   2 Device Drivers
   3
   4 struct device_driver {
   5         char                    * name;
   6         struct bus_type         * bus;
   7
   8         rwlock_t                lock;
   9         atomic_t                refcount;
  10
  11         list_t                  bus_list;
  12         list_t                  devices;
  13
  14         struct driver_dir_entry dir;
  15
  16         int     (*probe)        (struct device * dev);
  17         int     (*remove)       (struct device * dev);
  18
  19         int     (*suspend)      (struct device * dev, u32 state, u32 level);
  20         int     (*resume)       (struct device * dev, u32 level);
  21
  22         void    (*release)      (struct device_driver * drv);
  23 };
  24
  25
  26
  27 Allocation
  28 ~~~~~~~~~~
  29
  30 Device drivers are statically allocated structures. Though there may
  31 be multiple devices in a system that a driver supports, struct
  32 device_driver represents the driver as a whole (not a particular
  33 device instance).
  34
  35 Initialization
  36 ~~~~~~~~~~~~~~
  37
  38 The driver must initialize at least the name and bus fields. It should
  39 also initialize the devclass field (when it arrives), so it may obtain
  40 the proper linkage internally. It should also initialize as many of
  41 the callbacks as possible, though each is optional.
  42
  43 Declaration
  44 ~~~~~~~~~~~
  45
  46 As stated above, struct device_driver objects are statically
  47 allocated. Below is an example declaration of the eepro100
  48 driver. This declaration is hypothetical only; it relies on the driver
  49 being converted completely to the new model.
  50
  51 static struct device_driver eepro100_driver = {
  52        .name            = "eepro100",
  53        .bus             = &pci_bus_type,
  54        .devclass        = &ethernet_devclass,   /* when it's implemented */
  55
  56        .probe           = eepro100_probe,
  57        .remove          = eepro100_remove,
  58        .suspend         = eepro100_suspend,
  59        .resume          = eepro100_resume,
  60 };
  61
  62 Most drivers will not be able to be converted completely to the new
  63 model because the bus they belong to has a bus-specific structure with
  64 bus-specific fields that cannot be generalized.
  65
  66 The most common example of this are device ID structures. A driver
  67 typically defines an array of device IDs that it supports. The format
  68 of these structures and the semantics for comparing device IDs are
  69 completely bus-specific. Defining them as bus-specific entities would
  70 sacrifice type-safety, so we keep bus-specific structures around.
  71
  72 Bus-specific drivers should include a generic struct device_driver in
  73 the definition of the bus-specific driver. Like this:
  74
  75 struct pci_driver {
  76        const struct pci_device_id *id_table;
  77        struct device_driver       driver;
  78 };
  79
  80 A definition that included bus-specific fields would look like
  81 (using the eepro100 driver again):
  82
  83 static struct pci_driver eepro100_driver = {
  84        .id_table       = eepro100_pci_tbl,
  85        .driver         = {
  86                 .name           = "eepro100",
  87                 .bus            = &pci_bus_type,
  88                 .devclass       = &ethernet_devclass,   /* when it's implemented */
  89                 .probe          = eepro100_probe,
  90                 .remove         = eepro100_remove,
  91                 .suspend        = eepro100_suspend,
  92                 .resume         = eepro100_resume,
  93        },
  94 };
  95
  96 Some may find the syntax of embedded struct initialization awkward or
  97 even a bit ugly. So far, it's the best way we've found to do what we want...
  98
  99 Registration
 100 ~~~~~~~~~~~~
 101
 102 int driver_register(struct device_driver * drv);
 103
 104 The driver registers the structure on startup. For drivers that have
 105 no bus-specific fields (i.e. don't have a bus-specific driver
 106 structure), they would use driver_register and pass a pointer to their
 107 struct device_driver object.
 108
 109 Most drivers, however, will have a bus-specific structure and will
 110 need to register with the bus using something like pci_driver_register.
 111
 112 It is important that drivers register their driver structure as early as
 113 possible. Registration with the core initializes several fields in the
 114 struct device_driver object, including the reference count and the
 115 lock. These fields are assumed to be valid at all times and may be
 116 used by the device model core or the bus driver.
 117
 118
 119 Transition Bus Drivers
 120 ~~~~~~~~~~~~~~~~~~~~~~
 121
 122 By defining wrapper functions, the transition to the new model can be
 123 made easier. Drivers can ignore the generic structure altogether and
 124 let the bus wrapper fill in the fields. For the callbacks, the bus can
 125 define generic callbacks that forward the call to the bus-specific
 126 callbacks of the drivers.
 127
 128 This solution is intended to be only temporary. In order to get class
 129 information in the driver, the drivers must be modified anyway. Since
 130 converting drivers to the new model should reduce some infrastructural
 131 complexity and code size, it is recommended that they are converted as
 132 class information is added.
 133
 134 Access
 135 ~~~~~~
 136
 137 Once the object has been registered, it may access the common fields of
 138 the object, like the lock and the list of devices.
 139
 140 int driver_for_each_dev(struct device_driver * drv, void * data,
 141                         int (*callback)(struct device * dev, void * data));
 142
 143 The devices field is a list of all the devices that have been bound to
 144 the driver. The LDM core provides a helper function to operate on all
 145 the devices a driver controls. This helper locks the driver on each
 146 node access, and does proper reference counting on each device as it
 147 accesses it.
 148
 149
 150 sysfs
 151 ~~~~~
 152
 153 When a driver is registered, a sysfs directory is created in its
 154 bus's directory. In this directory, the driver can export an interface
 155 to userspace to control operation of the driver on a global basis;
 156 e.g. toggling debugging output in the driver.
 157
 158 A future feature of this directory will be a 'devices' directory. This
 159 directory will contain symlinks to the directories of devices it
 160 supports.
 161
 162
 163
 164 Callbacks
 165 ~~~~~~~~~
 166
 167         int     (*probe)        (struct device * dev);
 168
 169 probe is called to verify the existence of a certain type of
 170 hardware. This is called during the driver binding process, after the
 171 bus has verified that the device ID of a device matches one of the
 172 device IDs supported by the driver.
 173
 174 This callback only verifies that there actually is supported hardware
 175 present. It may allocate a driver-specific structure, but it should
 176 not do any initialization of the hardware itself. The device-specific
 177 structure may be stored in the device's driver_data field.
 178
 179         int     (*init)         (struct device * dev);
 180
 181 init is called during the binding stage. It is called after probe has
 182 successfully returned and the device has been registered with its
 183 class. It is responsible for initializing the hardware.
 184
 185         int     (*remove)       (struct device * dev);
 186
 187 remove is called to dissociate a driver with a device. This may be
 188 called if a device is physically removed from the system, if the
 189 driver module is being unloaded, or during a reboot sequence.
 190
 191 It is up to the driver to determine if the device is present or
 192 not. It should free any resources allocated specifically for the
 193 device; i.e. anything in the device's driver_data field.
 194
 195 If the device is still present, it should quiesce the device and place
 196 it into a supported low-power state.
 197
 198         int     (*suspend)      (struct device * dev, u32 state, u32 level);
 199
 200 suspend is called to put the device in a low power state. There are
 201 several stages to successfully suspending a device, which is denoted in
 202 the @level parameter. Breaking the suspend transition into several
 203 stages affords the platform flexibility in performing device power
 204 management based on the requirements of the system and the
 205 user-defined policy.
 206
 207 SUSPEND_NOTIFY notifies the device that a suspend transition is about
 208 to happen. This happens on system power state transitions to verify
 209 that all devices can successfully suspend.
 210
 211 A driver may choose to fail on this call, which should cause the
 212 entire suspend transition to fail. A driver should fail only if it
 213 knows that the device will not be able to be resumed properly when the
 214 system wakes up again. It could also fail if it somehow determines it
 215 is in the middle of an operation too important to stop.
 216
 217 SUSPEND_DISABLE tells the device to stop I/O transactions. When it
 218 stops transactions, or what it should do with unfinished transactions
 219 is a policy of the driver. After this call, the driver should not
 220 accept any other I/O requests.
 221
 222 SUSPEND_SAVE_STATE tells the device to save the context of the
 223 hardware. This includes any bus-specific hardware state and
 224 device-specific hardware state. A pointer to this saved state can be
 225 stored in the device's saved_state field.
 226
 227 SUSPEND_POWER_DOWN tells the driver to place the device in the low
 228 power state requested.
 229
 230 Whether suspend is called with a given level is a policy of the
 231 platform. Some levels may be omitted; drivers must not assume the
 232 reception of any level. However, all levels must be called in the
 233 order above; i.e. notification will always come before disabling;
 234 disabling the device will come before suspending the device.
 235
 236 All calls are made with interrupts enabled, except for the
 237 SUSPEND_POWER_DOWN level.
 238
 239         int     (*resume)       (struct device * dev, u32 level);
 240
 241 Resume is used to bring a device back from a low power state. Like the
 242 suspend transition, it happens in several stages.
 243
 244 RESUME_POWER_ON tells the driver to set the power state to the state
 245 before the suspend call (The device could have already been in a low
 246 power state before the suspend call to put in a lower power state).
 247
 248 RESUME_RESTORE_STATE tells the driver to restore the state saved by
 249 the SUSPEND_SAVE_STATE suspend call.
 250
 251 RESUME_ENABLE tells the driver to start accepting I/O transactions
 252 again. Depending on driver policy, the device may already have pending
 253 I/O requests.
 254
 255 RESUME_POWER_ON is called with interrupts disabled. The other resume
 256 levels are called with interrupts enabled.
 257
 258 As with the various suspend stages, the driver must not assume that
 259 any other resume calls have been or will be made. Each call should be
 260 self-contained and not dependent on any external state.
 261
 262
 263 Attributes
 264 ~~~~~~~~~~
 265 struct driver_attribute {
 266         struct attribute        attr;
 267         ssize_t (*show)(struct device_driver *, char * buf, size_t count, loff_t off);
 268         ssize_t (*store)(struct device_driver *, const char * buf, size_t count, loff_t off);
 269 };
 270
 271 Device drivers can export attributes via their sysfs directories.
 272 Drivers can declare attributes using a DRIVER_ATTR macro that works
 273 identically to the DEVICE_ATTR macro.
 274
 275 Example:
 276
 277 DRIVER_ATTR(debug,0644,show_debug,store_debug);
 278
 279 This is equivalent to declaring:
 280
 281 struct driver_attribute driver_attr_debug;
 282
 283 This can then be used to add and remove the attribute from the
 284 driver's directory using:
 285
 286 int driver_create_file(struct device_driver *, struct driver_attribute *);
 287 void driver_remove_file(struct device_driver *, struct driver_attribute *);