aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/power
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/power')
-rw-r--r--Documentation/power/00-INDEX6
-rw-r--r--Documentation/power/pm.txt257
-rw-r--r--Documentation/power/pm_qos_interface.txt59
-rw-r--r--Documentation/power/power_supply_class.txt169
4 files changed, 491 insertions, 0 deletions
diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX
index 8db4e41a052d..a55d7f1c836d 100644
--- a/Documentation/power/00-INDEX
+++ b/Documentation/power/00-INDEX
@@ -14,6 +14,12 @@ notifiers.txt
14 - Registering suspend notifiers in device drivers 14 - Registering suspend notifiers in device drivers
15pci.txt 15pci.txt
16 - How the PCI Subsystem Does Power Management 16 - How the PCI Subsystem Does Power Management
17pm.txt
18 - info on Linux power management support.
19pm_qos_interface.txt
20 - info on Linux PM Quality of Service interface
21power_supply_class.txt
22 - Tells userspace about battery, UPS, AC or DC power supply properties
17s2ram.txt 23s2ram.txt
18 - How to get suspend to ram working (and debug it when it isn't) 24 - How to get suspend to ram working (and debug it when it isn't)
19states.txt 25states.txt
diff --git a/Documentation/power/pm.txt b/Documentation/power/pm.txt
new file mode 100644
index 000000000000..be841507e43f
--- /dev/null
+++ b/Documentation/power/pm.txt
@@ -0,0 +1,257 @@
1 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 cannot 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 cannot 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----------------*************************
41
42Note: pm_register(), pm_access(), pm_dev_idle() and friends are
43obsolete. Please do not use them. Instead you should properly hook
44your driver into the driver model, and use its suspend()/resume()
45callbacks to do this kind of stuff.
46
47If you are writing a new driver or maintaining an old driver, it
48should include power management support. Without power management
49support, a single driver may prevent a system with power management
50capabilities from ever being able to suspend (safely).
51
52Overview:
531) Register each instance of a device with "pm_register"
542) Call "pm_access" before accessing the hardware.
55 (this will ensure that the hardware is awake and ready)
563) Your "pm_callback" is called before going into a
57 suspend state (ACPI D1-D3) or after resuming (ACPI D0)
58 from a suspend.
594) Call "pm_dev_idle" when the device is not being used
60 (optional but will improve device idle detection)
615) When unloaded, unregister the device with "pm_unregister"
62
63/*
64 * Description: Register a device with the power-management subsystem
65 *
66 * Parameters:
67 * type - device type (PCI device, system device, ...)
68 * id - instance number or unique identifier
69 * cback - request handler callback (suspend, resume, ...)
70 *
71 * Returns: Registered PM device or NULL on error
72 *
73 * Examples:
74 * dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
75 *
76 * struct pci_dev *pci_dev = pci_find_dev(...);
77 * dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
78 */
79struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
80
81/*
82 * Description: Unregister a device with the power management subsystem
83 *
84 * Parameters:
85 * dev - PM device previously returned from pm_register
86 */
87void pm_unregister(struct pm_dev *dev);
88
89/*
90 * Description: Unregister all devices with a matching callback function
91 *
92 * Parameters:
93 * cback - previously registered request callback
94 *
95 * Notes: Provided for easier porting from old APM interface
96 */
97void pm_unregister_all(pm_callback cback);
98
99/*
100 * Power management request callback
101 *
102 * Parameters:
103 * dev - PM device previously returned from pm_register
104 * rqst - request type
105 * data - data, if any, associated with the request
106 *
107 * Returns: 0 if the request is successful
108 * EINVAL if the request is not supported
109 * EBUSY if the device is now busy and cannot handle the request
110 * ENOMEM if the device was unable to handle the request due to memory
111 *
112 * Details: The device request callback will be called before the
113 * device/system enters a suspend state (ACPI D1-D3) or
114 * or after the device/system resumes from suspend (ACPI D0).
115 * For PM_SUSPEND, the ACPI D-state being entered is passed
116 * as the "data" argument to the callback. The device
117 * driver should save (PM_SUSPEND) or restore (PM_RESUME)
118 * device context when the request callback is called.
119 *
120 * Once a driver returns 0 (success) from a suspend
121 * request, it should not process any further requests or
122 * access the device hardware until a call to "pm_access" is made.
123 */
124typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
125
126Driver Details
127--------------
128This is just a quick Q&A as a stopgap until a real driver writers'
129power management guide is available.
130
131Q: When is a device suspended?
132
133Devices can be suspended based on direct user request (eg. laptop lid
134closes), system power policy (eg. sleep after 30 minutes of console
135inactivity), or device power policy (eg. power down device after 5
136minutes of inactivity)
137
138Q: Must a driver honor a suspend request?
139
140No, a driver can return -EBUSY from a suspend request and this
141will stop the system from suspending. When a suspend request
142fails, all suspended devices are resumed and the system continues
143to run. Suspend can be retried at a later time.
144
145Q: Can the driver block suspend/resume requests?
146
147Yes, a driver can delay its return from a suspend or resume
148request until the device is ready to handle requests. It
149is advantageous to return as quickly as possible from a
150request as suspend/resume are done serially.
151
152Q: What context is a suspend/resume initiated from?
153
154A suspend or resume is initiated from a kernel thread context.
155It is safe to block, allocate memory, initiate requests
156or anything else you can do within the kernel.
157
158Q: Will requests continue to arrive after a suspend?
159
160Possibly. It is the driver's responsibility to queue(*),
161fail, or drop any requests that arrive after returning
162success to a suspend request. It is important that the
163driver not access its device until after it receives
164a resume request as the device's bus may no longer
165be active.
166
167(*) If a driver queues requests for processing after
168 resume be aware that the device, network, etc.
169 might be in a different state than at suspend time.
170 It's probably better to drop requests unless
171 the driver is a storage device.
172
173Q: Do I have to manage bus-specific power management registers
174
175No. It is the responsibility of the bus driver to manage
176PCI, USB, etc. power management registers. The bus driver
177or the power management subsystem will also enable any
178wake-on functionality that the device has.
179
180Q: So, really, what do I need to do to support suspend/resume?
181
182You need to save any device context that would
183be lost if the device was powered off and then restore
184it at resume time. When ACPI is active, there are
185three levels of device suspend states; D1, D2, and D3.
186(The suspend state is passed as the "data" argument
187to the device callback.) With D3, the device is powered
188off and loses all context, D1 and D2 are shallower power
189states and require less device context to be saved. To
190play it safe, just save everything at suspend and restore
191everything at resume.
192
193Q: Where do I store device context for suspend?
194
195Anywhere in memory, kmalloc a buffer or store it
196in the device descriptor. You are guaranteed that the
197contents of memory will be restored and accessible
198before resume, even when the system suspends to disk.
199
200Q: What do I need to do for ACPI vs. APM vs. etc?
201
202Drivers need not be aware of the specific power management
203technology that is active. They just need to be aware
204of when the overlying power management system requests
205that they suspend or resume.
206
207Q: What about device dependencies?
208
209When a driver registers a device, the power management
210subsystem uses the information provided to build a
211tree of device dependencies (eg. USB device X is on
212USB controller Y which is on PCI bus Z) When power
213management wants to suspend a device, it first sends
214a suspend request to its driver, then the bus driver,
215and so on up to the system bus. Device resumes
216proceed in the opposite direction.
217
218Q: Who do I contact for additional information about
219 enabling power management for my specific driver/device?
220
221ACPI Development mailing list: linux-acpi@vger.kernel.org
222
223System Interface -- OBSOLETE, DO NOT USE!
224----------------*************************
225If you are providing new power management support to Linux (ie.
226adding support for something like APM or ACPI), you should
227communicate with drivers through the existing generic power
228management interface.
229
230/*
231 * Send a request to all devices
232 *
233 * Parameters:
234 * rqst - request type
235 * data - data, if any, associated with the request
236 *
237 * Returns: 0 if the request is successful
238 * See "pm_callback" return for errors
239 *
240 * Details: Walk list of registered devices and call pm_send
241 * for each until complete or an error is encountered.
242 * If an error is encountered for a suspend request,
243 * return all devices to the state they were in before
244 * the suspend request.
245 */
246int pm_send_all(pm_request_t rqst, void *data);
247
248/*
249 * Find a matching device
250 *
251 * Parameters:
252 * type - device type (PCI device, system device, or 0 to match all devices)
253 * from - previous match or NULL to start from the beginning
254 *
255 * Returns: Matching device or NULL if none found
256 */
257struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.txt
new file mode 100644
index 000000000000..49adb1a33514
--- /dev/null
+++ b/Documentation/power/pm_qos_interface.txt
@@ -0,0 +1,59 @@
1PM quality of Service interface.
2
3This interface provides a kernel and user mode interface for registering
4performance expectations by drivers, subsystems and user space applications on
5one of the parameters.
6
7Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
8initial set of pm_qos parameters.
9
10The infrastructure exposes multiple misc device nodes one per implemented
11parameter. The set of parameters implement is defined by pm_qos_power_init()
12and pm_qos_params.h. This is done because having the available parameters
13being runtime configurable or changeable from a driver was seen as too easy to
14abuse.
15
16For each parameter a list of performance requirements is maintained along with
17an aggregated target value. The aggregated target value is updated with
18changes to the requirement list or elements of the list. Typically the
19aggregated target value is simply the max or min of the requirement values held
20in the parameter list elements.
21
22From kernel mode the use of this interface is simple:
23pm_qos_add_requirement(param_id, name, target_value):
24Will insert a named element in the list for that identified PM_QOS parameter
25with the target value. Upon change to this list the new target is recomputed
26and any registered notifiers are called only if the target value is now
27different.
28
29pm_qos_update_requirement(param_id, name, new_target_value):
30Will search the list identified by the param_id for the named list element and
31then update its target value, calling the notification tree if the aggregated
32target is changed. with that name is already registered.
33
34pm_qos_remove_requirement(param_id, name):
35Will search the identified list for the named element and remove it, after
36removal it will update the aggregate target and call the notification tree if
37the target was changed as a result of removing the named requirement.
38
39
40From user mode:
41Only processes can register a pm_qos requirement. To provide for automatic
42cleanup for process the interface requires the process to register its
43parameter requirements in the following way:
44
45To register the default pm_qos target for the specific parameter, the process
46must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
47
48As long as the device node is held open that process has a registered
49requirement on the parameter. The name of the requirement is "process_<PID>"
50derived from the current->pid from within the open system call.
51
52To change the requested target value the process needs to write a s32 value to
53the open device node. This translates to a pm_qos_update_requirement call.
54
55To remove the user mode request for a target value simply close the device
56node.
57
58
59
diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt
new file mode 100644
index 000000000000..a8686e5a6857
--- /dev/null
+++ b/Documentation/power/power_supply_class.txt
@@ -0,0 +1,169 @@
1Linux power supply class
2========================
3
4Synopsis
5~~~~~~~~
6Power supply class used to represent battery, UPS, AC or DC power supply
7properties to user-space.
8
9It defines core set of attributes, which should be applicable to (almost)
10every power supply out there. Attributes are available via sysfs and uevent
11interfaces.
12
13Each attribute has well defined meaning, up to unit of measure used. While
14the attributes provided are believed to be universally applicable to any
15power supply, specific monitoring hardware may not be able to provide them
16all, so any of them may be skipped.
17
18Power supply class is extensible, and allows to define drivers own attributes.
19The core attribute set is subject to the standard Linux evolution (i.e.
20if it will be found that some attribute is applicable to many power supply
21types or their drivers, it can be added to the core set).
22
23It also integrates with LED framework, for the purpose of providing
24typically expected feedback of battery charging/fully charged status and
25AC/USB power supply online status. (Note that specific details of the
26indication (including whether to use it at all) are fully controllable by
27user and/or specific machine defaults, per design principles of LED
28framework).
29
30
31Attributes/properties
32~~~~~~~~~~~~~~~~~~~~~
33Power supply class has predefined set of attributes, this eliminates code
34duplication across drivers. Power supply class insist on reusing its
35predefined attributes *and* their units.
36
37So, userspace gets predictable set of attributes and their units for any
38kind of power supply, and can process/present them to a user in consistent
39manner. Results for different power supplies and machines are also directly
40comparable.
41
42See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
43example how to declare and handle attributes.
44
45
46Units
47~~~~~
48Quoting include/linux/power_supply.h:
49
50 All voltages, currents, charges, energies, time and temperatures in µV,
51 µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
52 stated. It's driver's job to convert its raw values to units in which
53 this class operates.
54
55
56Attributes/properties detailed
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
60~ ~
61~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
62~ of battery, this class distinguish these terms. Don't mix them! ~
63~ ~
64~ CHARGE_* attributes represents capacity in µAh only. ~
65~ ENERGY_* attributes represents capacity in µWh only. ~
66~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~
67~ ~
68~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
69
70Postfixes:
71_AVG - *hardware* averaged value, use it if your hardware is really able to
72report averaged values.
73_NOW - momentary/instantaneous values.
74
75STATUS - this attribute represents operating status (charging, full,
76discharging (i.e. powering a load), etc.). This corresponds to
77BATTERY_STATUS_* values, as defined in battery.h.
78
79HEALTH - represents health of the battery, values corresponds to
80POWER_SUPPLY_HEALTH_*, defined in battery.h.
81
82VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
83minimal power supply voltages. Maximal/minimal means values of voltages
84when battery considered "full"/"empty" at normal conditions. Yes, there is
85no direct relation between voltage and battery capacity, but some dumb
86batteries use voltage for very approximated calculation of capacity.
87Battery driver also can use this attribute just to inform userspace
88about maximal and minimal voltage thresholds of a given battery.
89
90VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
91these ones should be used if hardware could only guess (measure and
92retain) the thresholds of a given power supply.
93
94CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
95battery considered full/empty.
96
97ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
98
99CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
100of charge when battery became full/empty". It also could mean "value of
101charge when battery considered full/empty at given conditions (temperature,
102age)". I.e. these attributes represents real thresholds, not design values.
103
104ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
105
106CAPACITY - capacity in percents.
107
108TEMP - temperature of the power supply.
109TEMP_AMBIENT - ambient temperature.
110
111TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
112while battery powers a load)
113TIME_TO_FULL - seconds left for battery to be considered full (i.e.
114while battery is charging)
115
116
117Battery <-> external power supply interaction
118~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119Often power supplies are acting as supplies and supplicants at the same
120time. Batteries are good example. So, batteries usually care if they're
121externally powered or not.
122
123For that case, power supply class implements notification mechanism for
124batteries.
125
126External power supply (AC) lists supplicants (batteries) names in
127"supplied_to" struct member, and each power_supply_changed() call
128issued by external power supply will notify supplicants via
129external_power_changed callback.
130
131
132QA
133~~
134Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
135A: If you cannot find attribute suitable for your driver needs, feel free
136 to add it and send patch along with your driver.
137
138 The attributes available currently are the ones currently provided by the
139 drivers written.
140
141 Good candidates to add in future: model/part#, cycle_time, manufacturer,
142 etc.
143
144
145Q: I have some very specific attribute (e.g. battery color), should I add
146 this attribute to standard ones?
147A: Most likely, no. Such attribute can be placed in the driver itself, if
148 it is useful. Of course, if the attribute in question applicable to
149 large set of batteries, provided by many drivers, and/or comes from
150 some general battery specification/standard, it may be a candidate to
151 be added to the core attribute set.
152
153
154Q: Suppose, my battery monitoring chip/firmware does not provides capacity
155 in percents, but provides charge_{now,full,empty}. Should I calculate
156 percentage capacity manually, inside the driver, and register CAPACITY
157 attribute? The same question about time_to_empty/time_to_full.
158A: Most likely, no. This class is designed to export properties which are
159 directly measurable by the specific hardware available.
160
161 Inferring not available properties using some heuristics or mathematical
162 model is not subject of work for a battery driver. Such functionality
163 should be factored out, and in fact, apm_power, the driver to serve
164 legacy APM API on top of power supply class, uses a simple heuristic of
165 approximating remaining battery capacity based on its charge, current,
166 voltage and so on. But full-fledged battery model is likely not subject
167 for kernel at all, as it would require floating point calculation to deal
168 with things like differential equations and Kalman filters. This is
169 better be handled by batteryd/libbattery, yet to be written.