TEXT   58

driver.txt

Guest on 1st August 2021 06:08:37 AM

  1.  
  2. Device Drivers
  3.  
  4. See the kerneldoc for the struct device_driver.
  5.  
  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. int driver_register(struct device_driver * drv);
  81.  
  82. The driver registers the structure on startup. For drivers that have
  83. no bus-specific fields (i.e. don't have a bus-specific driver
  84. structure), they would use driver_register and pass a pointer to their
  85. struct device_driver object.
  86.  
  87. Most drivers, however, will have a bus-specific structure and will
  88. need to register with the bus using something like pci_driver_register.
  89.  
  90. It is important that drivers register their driver structure as early as
  91. possible. Registration with the core initializes several fields in the
  92. struct device_driver object, including the reference count and the
  93. lock. These fields are assumed to be valid at all times and may be
  94. used by the device model core or the bus driver.
  95.  
  96.  
  97. Transition Bus Drivers
  98. ~~~~~~~~~~~~~~~~~~~~~~
  99.  
  100. By defining wrapper functions, the transition to the new model can be
  101. made easier. Drivers can ignore the generic structure altogether and
  102. let the bus wrapper fill in the fields. For the callbacks, the bus can
  103. define generic callbacks that forward the call to the bus-specific
  104. callbacks of the drivers.
  105.  
  106. This solution is intended to be only temporary. In order to get class
  107. information in the driver, the drivers must be modified anyway. Since
  108. converting drivers to the new model should reduce some infrastructural
  109. complexity and code size, it is recommended that they are converted as
  110. class information is added.
  111.  
  112. Access
  113. ~~~~~~
  114.  
  115. Once the object has been registered, it may access the common fields of
  116. the object, like the lock and the list of devices.
  117.  
  118. int driver_for_each_dev(struct device_driver * drv, void * data,
  119.                         int (*callback)(struct device * dev, void * data));
  120.  
  121. The devices field is a list of all the devices that have been bound to
  122. the driver. The LDM core provides a helper function to operate on all
  123. the devices a driver controls. This helper locks the driver on each
  124. node access, and does proper reference counting on each device as it
  125. accesses it.
  126.  
  127.  
  128. sysfs
  129. ~~~~~
  130.  
  131. When a driver is registered, a sysfs directory is created in its
  132. bus's directory. In this directory, the driver can export an interface
  133. to userspace to control operation of the driver on a global basis;
  134. e.g. toggling debugging output in the driver.
  135.  
  136. A future feature of this directory will be a 'devices' directory. This
  137. directory will contain symlinks to the directories of devices it
  138. supports.
  139.  
  140.  
  141.  
  142. Callbacks
  143. ~~~~~~~~~
  144.  
  145.         int     (*probe)        (struct device * dev);
  146.  
  147. The probe() entry is called in task context, with the bus's rwsem locked
  148. and the driver partially bound to the device.  Drivers commonly use
  149. container_of() to convert "dev" to a bus-specific type, both in probe()
  150. and other routines.  That type often provides device resource data, such
  151. as pci_dev.resource[] or platform_device.resources, which is used in
  152. addition to dev->platform_data to initialize the driver.
  153.  
  154. This callback holds the driver-specific logic to bind the driver to a
  155. given device.  That includes verifying that the device is present, that
  156. it's a version the driver can handle, that driver data structures can
  157. be allocated and initialized, and that any hardware can be initialized.
  158. Drivers often store a pointer to their state with dev_set_drvdata().
  159. When the driver has successfully bound itself to that device, then probe()
  160. returns zero and the driver model code will finish its part of binding
  161. the driver to that device.
  162.  
  163. A driver's probe() may return a negative errno value to indicate that
  164. the driver did not bind to this device, in which case it should have
  165. released all resources it allocated.
  166.  
  167.         int     (*remove)       (struct device * dev);
  168.  
  169. remove is called to unbind a driver from a device. This may be
  170. called if a device is physically removed from the system, if the
  171. driver module is being unloaded, during a reboot sequence, or
  172. in other cases.
  173.  
  174. It is up to the driver to determine if the device is present or
  175. not. It should free any resources allocated specifically for the
  176. device; i.e. anything in the device's driver_data field.
  177.  
  178. If the device is still present, it should quiesce the device and place
  179. it into a supported low-power state.
  180.  
  181.         int     (*suspend)      (struct device * dev, pm_message_t state);
  182.  
  183. suspend is called to put the device in a low power state.
  184.  
  185.         int     (*resume)       (struct device * dev);
  186.  
  187. Resume is used to bring a device back from a low power state.
  188.  
  189.  
  190. Attributes
  191. ~~~~~~~~~~
  192. struct driver_attribute {
  193.         struct attribute        attr;
  194.         ssize_t (*show)(struct device_driver *driver, char *buf);
  195.         ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
  196. };
  197.  
  198. Device drivers can export attributes via their sysfs directories.
  199. Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
  200. macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
  201. macros.
  202.  
  203. Example:
  204.  
  205. DRIVER_ATTR_RW(debug);
  206.  
  207. This is equivalent to declaring:
  208.  
  209. struct driver_attribute driver_attr_debug;
  210.  
  211. This can then be used to add and remove the attribute from the
  212. driver's directory using:
  213.  
  214. int driver_create_file(struct device_driver *, const struct driver_attribute *);
  215. void driver_remove_file(struct device_driver *, const struct driver_attribute *);

Raw Paste


Login or Register to edit or fork this paste. It's free.