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