TEXT   63

driver.txt

Guest on 25th July 2021 05:17:42 PM

  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 initalize 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 this are device ID structures. A driver
  67. typically defines an array of device IDs that it supports. The format
  68. of this structure and the semantics for comparing device IDs is
  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 something
  81. like (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 intialization 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 drivers 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. driverfs
  151. ~~~~~~~~
  152.  
  153. When a driver is registered, a driverfs 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 sucessfully 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 transition to verify
  209. that all devices can sucessfully 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 driverfs 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 *);

Raw Paste


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