pm.txt 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257
  1. Linux Power Management Support
  2. This document briefly describes how to use power management with your
  3. Linux system and how to add power management support to Linux drivers.
  4. APM or ACPI?
  5. ------------
  6. If you have a relatively recent x86 mobile, desktop, or server system,
  7. odds are it supports either Advanced Power Management (APM) or
  8. Advanced Configuration and Power Interface (ACPI). ACPI is the newer
  9. of the two technologies and puts power management in the hands of the
  10. operating system, allowing for more intelligent power management than
  11. is possible with BIOS controlled APM.
  12. The best way to determine which, if either, your system supports is to
  13. build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
  14. enabled by default). If a working ACPI implementation is found, the
  15. ACPI driver will override and disable APM, otherwise the APM driver
  16. will be used.
  17. No, sorry, you cannot have both ACPI and APM enabled and running at
  18. once. Some people with broken ACPI or broken APM implementations
  19. would like to use both to get a full set of working features, but you
  20. simply cannot mix and match the two. Only one power management
  21. interface can be in control of the machine at once. Think about it..
  22. User-space Daemons
  23. ------------------
  24. Both APM and ACPI rely on user-space daemons, apmd and acpid
  25. respectively, to be completely functional. Obtain both of these
  26. daemons from your Linux distribution or from the Internet (see below)
  27. and be sure that they are started sometime in the system boot process.
  28. Go ahead and start both. If ACPI or APM is not available on your
  29. system the associated daemon will exit gracefully.
  30. apmd: http://worldvisions.ca/~apenwarr/apmd/
  31. acpid: http://acpid.sf.net/
  32. Driver Interface -- OBSOLETE, DO NOT USE!
  33. ----------------*************************
  34. Note: pm_register(), pm_access(), pm_dev_idle() and friends are
  35. obsolete. Please do not use them. Instead you should properly hook
  36. your driver into the driver model, and use its suspend()/resume()
  37. callbacks to do this kind of stuff.
  38. If you are writing a new driver or maintaining an old driver, it
  39. should include power management support. Without power management
  40. support, a single driver may prevent a system with power management
  41. capabilities from ever being able to suspend (safely).
  42. Overview:
  43. 1) Register each instance of a device with "pm_register"
  44. 2) Call "pm_access" before accessing the hardware.
  45. (this will ensure that the hardware is awake and ready)
  46. 3) Your "pm_callback" is called before going into a
  47. suspend state (ACPI D1-D3) or after resuming (ACPI D0)
  48. from a suspend.
  49. 4) Call "pm_dev_idle" when the device is not being used
  50. (optional but will improve device idle detection)
  51. 5) When unloaded, unregister the device with "pm_unregister"
  52. /*
  53. * Description: Register a device with the power-management subsystem
  54. *
  55. * Parameters:
  56. * type - device type (PCI device, system device, ...)
  57. * id - instance number or unique identifier
  58. * cback - request handler callback (suspend, resume, ...)
  59. *
  60. * Returns: Registered PM device or NULL on error
  61. *
  62. * Examples:
  63. * dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
  64. *
  65. * struct pci_dev *pci_dev = pci_find_dev(...);
  66. * dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
  67. */
  68. struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
  69. /*
  70. * Description: Unregister a device with the power management subsystem
  71. *
  72. * Parameters:
  73. * dev - PM device previously returned from pm_register
  74. */
  75. void pm_unregister(struct pm_dev *dev);
  76. /*
  77. * Description: Unregister all devices with a matching callback function
  78. *
  79. * Parameters:
  80. * cback - previously registered request callback
  81. *
  82. * Notes: Provided for easier porting from old APM interface
  83. */
  84. void pm_unregister_all(pm_callback cback);
  85. /*
  86. * Power management request callback
  87. *
  88. * Parameters:
  89. * dev - PM device previously returned from pm_register
  90. * rqst - request type
  91. * data - data, if any, associated with the request
  92. *
  93. * Returns: 0 if the request is successful
  94. * EINVAL if the request is not supported
  95. * EBUSY if the device is now busy and cannot handle the request
  96. * ENOMEM if the device was unable to handle the request due to memory
  97. *
  98. * Details: The device request callback will be called before the
  99. * device/system enters a suspend state (ACPI D1-D3) or
  100. * or after the device/system resumes from suspend (ACPI D0).
  101. * For PM_SUSPEND, the ACPI D-state being entered is passed
  102. * as the "data" argument to the callback. The device
  103. * driver should save (PM_SUSPEND) or restore (PM_RESUME)
  104. * device context when the request callback is called.
  105. *
  106. * Once a driver returns 0 (success) from a suspend
  107. * request, it should not process any further requests or
  108. * access the device hardware until a call to "pm_access" is made.
  109. */
  110. typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
  111. Driver Details
  112. --------------
  113. This is just a quick Q&A as a stopgap until a real driver writers'
  114. power management guide is available.
  115. Q: When is a device suspended?
  116. Devices can be suspended based on direct user request (eg. laptop lid
  117. closes), system power policy (eg. sleep after 30 minutes of console
  118. inactivity), or device power policy (eg. power down device after 5
  119. minutes of inactivity)
  120. Q: Must a driver honor a suspend request?
  121. No, a driver can return -EBUSY from a suspend request and this
  122. will stop the system from suspending. When a suspend request
  123. fails, all suspended devices are resumed and the system continues
  124. to run. Suspend can be retried at a later time.
  125. Q: Can the driver block suspend/resume requests?
  126. Yes, a driver can delay its return from a suspend or resume
  127. request until the device is ready to handle requests. It
  128. is advantageous to return as quickly as possible from a
  129. request as suspend/resume are done serially.
  130. Q: What context is a suspend/resume initiated from?
  131. A suspend or resume is initiated from a kernel thread context.
  132. It is safe to block, allocate memory, initiate requests
  133. or anything else you can do within the kernel.
  134. Q: Will requests continue to arrive after a suspend?
  135. Possibly. It is the driver's responsibility to queue(*),
  136. fail, or drop any requests that arrive after returning
  137. success to a suspend request. It is important that the
  138. driver not access its device until after it receives
  139. a resume request as the device's bus may no longer
  140. be active.
  141. (*) If a driver queues requests for processing after
  142. resume be aware that the device, network, etc.
  143. might be in a different state than at suspend time.
  144. It's probably better to drop requests unless
  145. the driver is a storage device.
  146. Q: Do I have to manage bus-specific power management registers
  147. No. It is the responsibility of the bus driver to manage
  148. PCI, USB, etc. power management registers. The bus driver
  149. or the power management subsystem will also enable any
  150. wake-on functionality that the device has.
  151. Q: So, really, what do I need to do to support suspend/resume?
  152. You need to save any device context that would
  153. be lost if the device was powered off and then restore
  154. it at resume time. When ACPI is active, there are
  155. three levels of device suspend states; D1, D2, and D3.
  156. (The suspend state is passed as the "data" argument
  157. to the device callback.) With D3, the device is powered
  158. off and loses all context, D1 and D2 are shallower power
  159. states and require less device context to be saved. To
  160. play it safe, just save everything at suspend and restore
  161. everything at resume.
  162. Q: Where do I store device context for suspend?
  163. Anywhere in memory, kmalloc a buffer or store it
  164. in the device descriptor. You are guaranteed that the
  165. contents of memory will be restored and accessible
  166. before resume, even when the system suspends to disk.
  167. Q: What do I need to do for ACPI vs. APM vs. etc?
  168. Drivers need not be aware of the specific power management
  169. technology that is active. They just need to be aware
  170. of when the overlying power management system requests
  171. that they suspend or resume.
  172. Q: What about device dependencies?
  173. When a driver registers a device, the power management
  174. subsystem uses the information provided to build a
  175. tree of device dependencies (eg. USB device X is on
  176. USB controller Y which is on PCI bus Z) When power
  177. management wants to suspend a device, it first sends
  178. a suspend request to its driver, then the bus driver,
  179. and so on up to the system bus. Device resumes
  180. proceed in the opposite direction.
  181. Q: Who do I contact for additional information about
  182. enabling power management for my specific driver/device?
  183. ACPI Development mailing list: linux-acpi@vger.kernel.org
  184. System Interface -- OBSOLETE, DO NOT USE!
  185. ----------------*************************
  186. If you are providing new power management support to Linux (ie.
  187. adding support for something like APM or ACPI), you should
  188. communicate with drivers through the existing generic power
  189. management interface.
  190. /*
  191. * Send a request to all devices
  192. *
  193. * Parameters:
  194. * rqst - request type
  195. * data - data, if any, associated with the request
  196. *
  197. * Returns: 0 if the request is successful
  198. * See "pm_callback" return for errors
  199. *
  200. * Details: Walk list of registered devices and call pm_send
  201. * for each until complete or an error is encountered.
  202. * If an error is encountered for a suspend request,
  203. * return all devices to the state they were in before
  204. * the suspend request.
  205. */
  206. int pm_send_all(pm_request_t rqst, void *data);
  207. /*
  208. * Find a matching device
  209. *
  210. * Parameters:
  211. * type - device type (PCI device, system device, or 0 to match all devices)
  212. * from - previous match or NULL to start from the beginning
  213. *
  214. * Returns: Matching device or NULL if none found
  215. */
  216. struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);