/Documentation/power/devices.txt

https://bitbucket.org/evzijst/gittest · Plain Text · 319 lines · 242 code · 77 blank · 0 comment · 0 complexity · c958c72c105ee0dcbd0f4da3ecf08786 MD5 · raw file

  1. Device Power Management
  2. Device power management encompasses two areas - the ability to save
  3. state and transition a device to a low-power state when the system is
  4. entering a low-power state; and the ability to transition a device to
  5. a low-power state while the system is running (and independently of
  6. any other power management activity).
  7. Methods
  8. The methods to suspend and resume devices reside in struct bus_type:
  9. struct bus_type {
  10. ...
  11. int (*suspend)(struct device * dev, pm_message_t state);
  12. int (*resume)(struct device * dev);
  13. };
  14. Each bus driver is responsible implementing these methods, translating
  15. the call into a bus-specific request and forwarding the call to the
  16. bus-specific drivers. For example, PCI drivers implement suspend() and
  17. resume() methods in struct pci_driver. The PCI core is simply
  18. responsible for translating the pointers to PCI-specific ones and
  19. calling the low-level driver.
  20. This is done to a) ease transition to the new power management methods
  21. and leverage the existing PM code in various bus drivers; b) allow
  22. buses to implement generic and default PM routines for devices, and c)
  23. make the flow of execution obvious to the reader.
  24. System Power Management
  25. When the system enters a low-power state, the device tree is walked in
  26. a depth-first fashion to transition each device into a low-power
  27. state. The ordering of the device tree is guaranteed by the order in
  28. which devices get registered - children are never registered before
  29. their ancestors, and devices are placed at the back of the list when
  30. registered. By walking the list in reverse order, we are guaranteed to
  31. suspend devices in the proper order.
  32. Devices are suspended once with interrupts enabled. Drivers are
  33. expected to stop I/O transactions, save device state, and place the
  34. device into a low-power state. Drivers may sleep, allocate memory,
  35. etc. at will.
  36. Some devices are broken and will inevitably have problems powering
  37. down or disabling themselves with interrupts enabled. For these
  38. special cases, they may return -EAGAIN. This will put the device on a
  39. list to be taken care of later. When interrupts are disabled, before
  40. we enter the low-power state, their drivers are called again to put
  41. their device to sleep.
  42. On resume, the devices that returned -EAGAIN will be called to power
  43. themselves back on with interrupts disabled. Once interrupts have been
  44. re-enabled, the rest of the drivers will be called to resume their
  45. devices. On resume, a driver is responsible for powering back on each
  46. device, restoring state, and re-enabling I/O transactions for that
  47. device.
  48. System devices follow a slightly different API, which can be found in
  49. include/linux/sysdev.h
  50. drivers/base/sys.c
  51. System devices will only be suspended with interrupts disabled, and
  52. after all other devices have been suspended. On resume, they will be
  53. resumed before any other devices, and also with interrupts disabled.
  54. Runtime Power Management
  55. Many devices are able to dynamically power down while the system is
  56. still running. This feature is useful for devices that are not being
  57. used, and can offer significant power savings on a running system.
  58. In each device's directory, there is a 'power' directory, which
  59. contains at least a 'state' file. Reading from this file displays what
  60. power state the device is currently in. Writing to this file initiates
  61. a transition to the specified power state, which must be a decimal in
  62. the range 1-3, inclusive; or 0 for 'On'.
  63. The PM core will call the ->suspend() method in the bus_type object
  64. that the device belongs to if the specified state is not 0, or
  65. ->resume() if it is.
  66. Nothing will happen if the specified state is the same state the
  67. device is currently in.
  68. If the device is already in a low-power state, and the specified state
  69. is another, but different, low-power state, the ->resume() method will
  70. first be called to power the device back on, then ->suspend() will be
  71. called again with the new state.
  72. The driver is responsible for saving the working state of the device
  73. and putting it into the low-power state specified. If this was
  74. successful, it returns 0, and the device's power_state field is
  75. updated.
  76. The driver must take care to know whether or not it is able to
  77. properly resume the device, including all step of reinitialization
  78. necessary. (This is the hardest part, and the one most protected by
  79. NDA'd documents).
  80. The driver must also take care not to suspend a device that is
  81. currently in use. It is their responsibility to provide their own
  82. exclusion mechanisms.
  83. The runtime power transition happens with interrupts enabled. If a
  84. device cannot support being powered down with interrupts, it may
  85. return -EAGAIN (as it would during a system power management
  86. transition), but it will _not_ be called again, and the transaction
  87. will fail.
  88. There is currently no way to know what states a device or driver
  89. supports a priori. This will change in the future.
  90. pm_message_t meaning
  91. pm_message_t has two fields. event ("major"), and flags. If driver
  92. does not know event code, it aborts the request, returning error. Some
  93. drivers may need to deal with special cases based on the actual type
  94. of suspend operation being done at the system level. This is why
  95. there are flags.
  96. Event codes are:
  97. ON -- no need to do anything except special cases like broken
  98. HW.
  99. # NOTIFICATION -- pretty much same as ON?
  100. FREEZE -- stop DMA and interrupts, and be prepared to reinit HW from
  101. scratch. That probably means stop accepting upstream requests, the
  102. actual policy of what to do with them beeing specific to a given
  103. driver. It's acceptable for a network driver to just drop packets
  104. while a block driver is expected to block the queue so no request is
  105. lost. (Use IDE as an example on how to do that). FREEZE requires no
  106. power state change, and it's expected for drivers to be able to
  107. quickly transition back to operating state.
  108. SUSPEND -- like FREEZE, but also put hardware into low-power state. If
  109. there's need to distinguish several levels of sleep, additional flag
  110. is probably best way to do that.
  111. Transitions are only from a resumed state to a suspended state, never
  112. between 2 suspended states. (ON -> FREEZE or ON -> SUSPEND can happen,
  113. FREEZE -> SUSPEND or SUSPEND -> FREEZE can not).
  114. All events are:
  115. [NOTE NOTE NOTE: If you are driver author, you should not care; you
  116. should only look at event, and ignore flags.]
  117. #Prepare for suspend -- userland is still running but we are going to
  118. #enter suspend state. This gives drivers chance to load firmware from
  119. #disk and store it in memory, or do other activities taht require
  120. #operating userland, ability to kmalloc GFP_KERNEL, etc... All of these
  121. #are forbiden once the suspend dance is started.. event = ON, flags =
  122. #PREPARE_TO_SUSPEND
  123. Apm standby -- prepare for APM event. Quiesce devices to make life
  124. easier for APM BIOS. event = FREEZE, flags = APM_STANDBY
  125. Apm suspend -- same as APM_STANDBY, but it we should probably avoid
  126. spinning down disks. event = FREEZE, flags = APM_SUSPEND
  127. System halt, reboot -- quiesce devices to make life easier for BIOS. event
  128. = FREEZE, flags = SYSTEM_HALT or SYSTEM_REBOOT
  129. System shutdown -- at least disks need to be spun down, or data may be
  130. lost. Quiesce devices, just to make life easier for BIOS. event =
  131. FREEZE, flags = SYSTEM_SHUTDOWN
  132. Kexec -- turn off DMAs and put hardware into some state where new
  133. kernel can take over. event = FREEZE, flags = KEXEC
  134. Powerdown at end of swsusp -- very similar to SYSTEM_SHUTDOWN, except wake
  135. may need to be enabled on some devices. This actually has at least 3
  136. subtypes, system can reboot, enter S4 and enter S5 at the end of
  137. swsusp. event = FREEZE, flags = SWSUSP and one of SYSTEM_REBOOT,
  138. SYSTEM_SHUTDOWN, SYSTEM_S4
  139. Suspend to ram -- put devices into low power state. event = SUSPEND,
  140. flags = SUSPEND_TO_RAM
  141. Freeze for swsusp snapshot -- stop DMA and interrupts. No need to put
  142. devices into low power mode, but you must be able to reinitialize
  143. device from scratch in resume method. This has two flavors, its done
  144. once on suspending kernel, once on resuming kernel. event = FREEZE,
  145. flags = DURING_SUSPEND or DURING_RESUME
  146. Device detach requested from /sys -- deinitialize device; proably same as
  147. SYSTEM_SHUTDOWN, I do not understand this one too much. probably event
  148. = FREEZE, flags = DEV_DETACH.
  149. #These are not really events sent:
  150. #
  151. #System fully on -- device is working normally; this is probably never
  152. #passed to suspend() method... event = ON, flags = 0
  153. #
  154. #Ready after resume -- userland is now running, again. Time to free any
  155. #memory you ate during prepare to suspend... event = ON, flags =
  156. #READY_AFTER_RESUME
  157. #
  158. Driver Detach Power Management
  159. The kernel now supports the ability to place a device in a low-power
  160. state when it is detached from its driver, which happens when its
  161. module is removed.
  162. Each device contains a 'detach_state' file in its sysfs directory
  163. which can be used to control this state. Reading from this file
  164. displays what the current detach state is set to. This is 0 (On) by
  165. default. A user may write a positive integer value to this file in the
  166. range of 1-4 inclusive.
  167. A value of 1-3 will indicate the device should be placed in that
  168. low-power state, which will cause ->suspend() to be called for that
  169. device. A value of 4 indicates that the device should be shutdown, so
  170. ->shutdown() will be called for that device.
  171. The driver is responsible for reinitializing the device when the
  172. module is re-inserted during it's ->probe() (or equivalent) method.
  173. The driver core will not call any extra functions when binding the
  174. device to the driver.
  175. pm_message_t meaning
  176. pm_message_t has two fields. event ("major"), and flags. If driver
  177. does not know event code, it aborts the request, returning error. Some
  178. drivers may need to deal with special cases based on the actual type
  179. of suspend operation being done at the system level. This is why
  180. there are flags.
  181. Event codes are:
  182. ON -- no need to do anything except special cases like broken
  183. HW.
  184. # NOTIFICATION -- pretty much same as ON?
  185. FREEZE -- stop DMA and interrupts, and be prepared to reinit HW from
  186. scratch. That probably means stop accepting upstream requests, the
  187. actual policy of what to do with them being specific to a given
  188. driver. It's acceptable for a network driver to just drop packets
  189. while a block driver is expected to block the queue so no request is
  190. lost. (Use IDE as an example on how to do that). FREEZE requires no
  191. power state change, and it's expected for drivers to be able to
  192. quickly transition back to operating state.
  193. SUSPEND -- like FREEZE, but also put hardware into low-power state. If
  194. there's need to distinguish several levels of sleep, additional flag
  195. is probably best way to do that.
  196. Transitions are only from a resumed state to a suspended state, never
  197. between 2 suspended states. (ON -> FREEZE or ON -> SUSPEND can happen,
  198. FREEZE -> SUSPEND or SUSPEND -> FREEZE can not).
  199. All events are:
  200. [NOTE NOTE NOTE: If you are driver author, you should not care; you
  201. should only look at event, and ignore flags.]
  202. #Prepare for suspend -- userland is still running but we are going to
  203. #enter suspend state. This gives drivers chance to load firmware from
  204. #disk and store it in memory, or do other activities taht require
  205. #operating userland, ability to kmalloc GFP_KERNEL, etc... All of these
  206. #are forbiden once the suspend dance is started.. event = ON, flags =
  207. #PREPARE_TO_SUSPEND
  208. Apm standby -- prepare for APM event. Quiesce devices to make life
  209. easier for APM BIOS. event = FREEZE, flags = APM_STANDBY
  210. Apm suspend -- same as APM_STANDBY, but it we should probably avoid
  211. spinning down disks. event = FREEZE, flags = APM_SUSPEND
  212. System halt, reboot -- quiesce devices to make life easier for BIOS. event
  213. = FREEZE, flags = SYSTEM_HALT or SYSTEM_REBOOT
  214. System shutdown -- at least disks need to be spun down, or data may be
  215. lost. Quiesce devices, just to make life easier for BIOS. event =
  216. FREEZE, flags = SYSTEM_SHUTDOWN
  217. Kexec -- turn off DMAs and put hardware into some state where new
  218. kernel can take over. event = FREEZE, flags = KEXEC
  219. Powerdown at end of swsusp -- very similar to SYSTEM_SHUTDOWN, except wake
  220. may need to be enabled on some devices. This actually has at least 3
  221. subtypes, system can reboot, enter S4 and enter S5 at the end of
  222. swsusp. event = FREEZE, flags = SWSUSP and one of SYSTEM_REBOOT,
  223. SYSTEM_SHUTDOWN, SYSTEM_S4
  224. Suspend to ram -- put devices into low power state. event = SUSPEND,
  225. flags = SUSPEND_TO_RAM
  226. Freeze for swsusp snapshot -- stop DMA and interrupts. No need to put
  227. devices into low power mode, but you must be able to reinitialize
  228. device from scratch in resume method. This has two flavors, its done
  229. once on suspending kernel, once on resuming kernel. event = FREEZE,
  230. flags = DURING_SUSPEND or DURING_RESUME
  231. Device detach requested from /sys -- deinitialize device; proably same as
  232. SYSTEM_SHUTDOWN, I do not understand this one too much. probably event
  233. = FREEZE, flags = DEV_DETACH.
  234. #These are not really events sent:
  235. #
  236. #System fully on -- device is working normally; this is probably never
  237. #passed to suspend() method... event = ON, flags = 0
  238. #
  239. #Ready after resume -- userland is now running, again. Time to free any
  240. #memory you ate during prepare to suspend... event = ON, flags =
  241. #READY_AFTER_RESUME
  242. #