Doug / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit 53471121a8aad3f0b590bfce7c95a1f5f52150f3

Authored by Randy Dunlap
Committed by Len Brown
1 parent a09a20b526
Exists in master and in 7 other branches imx_3.0.35_4.1.0, imx_3.10.17_1.0.1_ga, imx_3.10.53_1.1.0_ga, imx_3.14.28_1.0.0_ga, smarc-imx_3.10.53_1.1.0_ga, smarc-imx_3.14.28_1.0.0_ga, smarc-l5.0.0_1.0.0-ga

documentation: Move power-related files to Documentation/power/ 

Move 00-INDEX entries to power/00-INDEX (and add entry for
pm_qos_interface.txt).

Update references to moved filenames.

Fix some trailing whitespace.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Len Brown <len.brown@intel.com>

Showing 11 changed files with 494 additions and 492 deletions Side-by-side Diff

Documentation/00-INDEX
Diff comments   View file @ 5347112
... ... @@ -299,12 +299,8 @@
299 299 - info on the Linux PCMCIA driver.
300 300 pi-futex.txt
301 301 - documentation on lightweight PI-futexes.
302   -pm.txt
303   - - info on Linux power management support.
304 302 pnp.txt
305 303 - Linux Plug and Play documentation.
306   -power_supply_class.txt
307   - - Tells userspace about battery, UPS, AC or DC power supply properties
308 304 power/
309 305 - directory with info on Linux PCI power management.
310 306 powerpc/
Documentation/kernel-parameters.txt
Diff comments   View file @ 5347112
... ... @@ -138,7 +138,7 @@
138 138 strict -- Be less tolerant of platforms that are not
139 139 strictly ACPI specification compliant.
140 140  
141   - See also Documentation/pm.txt, pci=noacpi
  141 + See also Documentation/power/pm.txt, pci=noacpi
142 142  
143 143 acpi_apic_instance= [ACPI, IOAPIC]
144 144 Format: <int>
Documentation/pm.txt
View file @ 5347112
1   - Linux Power Management Support
2   -
3   -This document briefly describes how to use power management with your
4   -Linux system and how to add power management support to Linux drivers.
5   -
6   -APM or ACPI?
7   -------------
8   -If you have a relatively recent x86 mobile, desktop, or server system,
9   -odds are it supports either Advanced Power Management (APM) or
10   -Advanced Configuration and Power Interface (ACPI). ACPI is the newer
11   -of the two technologies and puts power management in the hands of the
12   -operating system, allowing for more intelligent power management than
13   -is possible with BIOS controlled APM.
14   -
15   -The best way to determine which, if either, your system supports is to
16   -build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
17   -enabled by default). If a working ACPI implementation is found, the
18   -ACPI driver will override and disable APM, otherwise the APM driver
19   -will be used.
20   -
21   -No, sorry, you cannot have both ACPI and APM enabled and running at
22   -once. Some people with broken ACPI or broken APM implementations
23   -would like to use both to get a full set of working features, but you
24   -simply cannot mix and match the two. Only one power management
25   -interface can be in control of the machine at once. Think about it..
26   -
27   -User-space Daemons
28   -------------------
29   -Both APM and ACPI rely on user-space daemons, apmd and acpid
30   -respectively, to be completely functional. Obtain both of these
31   -daemons from your Linux distribution or from the Internet (see below)
32   -and be sure that they are started sometime in the system boot process.
33   -Go ahead and start both. If ACPI or APM is not available on your
34   -system the associated daemon will exit gracefully.
35   -
36   - apmd: http://worldvisions.ca/~apenwarr/apmd/
37   - acpid: http://acpid.sf.net/
38   -
39   -Driver Interface -- OBSOLETE, DO NOT USE!
40   -----------------*************************
41   -
42   -Note: pm_register(), pm_access(), pm_dev_idle() and friends are
43   -obsolete. Please do not use them. Instead you should properly hook
44   -your driver into the driver model, and use its suspend()/resume()
45   -callbacks to do this kind of stuff.
46   -
47   -If you are writing a new driver or maintaining an old driver, it
48   -should include power management support. Without power management
49   -support, a single driver may prevent a system with power management
50   -capabilities from ever being able to suspend (safely).
51   -
52   -Overview:
53   -1) Register each instance of a device with "pm_register"
54   -2) Call "pm_access" before accessing the hardware.
55   - (this will ensure that the hardware is awake and ready)
56   -3) Your "pm_callback" is called before going into a
57   - suspend state (ACPI D1-D3) or after resuming (ACPI D0)
58   - from a suspend.
59   -4) Call "pm_dev_idle" when the device is not being used
60   - (optional but will improve device idle detection)
61   -5) 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   - */
79   -struct 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   - */
87   -void 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   - */
97   -void 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   - */
124   -typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
125   -
126   -Driver Details
127   ---------------
128   -This is just a quick Q&A as a stopgap until a real driver writers'
129   -power management guide is available.
130   -
131   -Q: When is a device suspended?
132   -
133   -Devices can be suspended based on direct user request (eg. laptop lid
134   -closes), system power policy (eg. sleep after 30 minutes of console
135   -inactivity), or device power policy (eg. power down device after 5
136   -minutes of inactivity)
137   -
138   -Q: Must a driver honor a suspend request?
139   -
140   -No, a driver can return -EBUSY from a suspend request and this
141   -will stop the system from suspending. When a suspend request
142   -fails, all suspended devices are resumed and the system continues
143   -to run. Suspend can be retried at a later time.
144   -
145   -Q: Can the driver block suspend/resume requests?
146   -
147   -Yes, a driver can delay its return from a suspend or resume
148   -request until the device is ready to handle requests. It
149   -is advantageous to return as quickly as possible from a
150   -request as suspend/resume are done serially.
151   -
152   -Q: What context is a suspend/resume initiated from?
153   -
154   -A suspend or resume is initiated from a kernel thread context.
155   -It is safe to block, allocate memory, initiate requests
156   -or anything else you can do within the kernel.
157   -
158   -Q: Will requests continue to arrive after a suspend?
159   -
160   -Possibly. It is the driver's responsibility to queue(*),
161   -fail, or drop any requests that arrive after returning
162   -success to a suspend request. It is important that the
163   -driver not access its device until after it receives
164   -a resume request as the device's bus may no longer
165   -be 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   -
173   -Q: Do I have to manage bus-specific power management registers
174   -
175   -No. It is the responsibility of the bus driver to manage
176   -PCI, USB, etc. power management registers. The bus driver
177   -or the power management subsystem will also enable any
178   -wake-on functionality that the device has.
179   -
180   -Q: So, really, what do I need to do to support suspend/resume?
181   -
182   -You need to save any device context that would
183   -be lost if the device was powered off and then restore
184   -it at resume time. When ACPI is active, there are
185   -three levels of device suspend states; D1, D2, and D3.
186   -(The suspend state is passed as the "data" argument
187   -to the device callback.) With D3, the device is powered
188   -off and loses all context, D1 and D2 are shallower power
189   -states and require less device context to be saved. To
190   -play it safe, just save everything at suspend and restore
191   -everything at resume.
192   -
193   -Q: Where do I store device context for suspend?
194   -
195   -Anywhere in memory, kmalloc a buffer or store it
196   -in the device descriptor. You are guaranteed that the
197   -contents of memory will be restored and accessible
198   -before resume, even when the system suspends to disk.
199   -
200   -Q: What do I need to do for ACPI vs. APM vs. etc?
201   -
202   -Drivers need not be aware of the specific power management
203   -technology that is active. They just need to be aware
204   -of when the overlying power management system requests
205   -that they suspend or resume.
206   -
207   -Q: What about device dependencies?
208   -
209   -When a driver registers a device, the power management
210   -subsystem uses the information provided to build a
211   -tree of device dependencies (eg. USB device X is on
212   -USB controller Y which is on PCI bus Z) When power
213   -management wants to suspend a device, it first sends
214   -a suspend request to its driver, then the bus driver,
215   -and so on up to the system bus. Device resumes
216   -proceed in the opposite direction.
217   -
218   -Q: Who do I contact for additional information about
219   - enabling power management for my specific driver/device?
220   -
221   -ACPI Development mailing list: linux-acpi@vger.kernel.org
222   -
223   -System Interface -- OBSOLETE, DO NOT USE!
224   -----------------*************************
225   -If you are providing new power management support to Linux (ie.
226   -adding support for something like APM or ACPI), you should
227   -communicate with drivers through the existing generic power
228   -management 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   - */
246   -int 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   - */
257   -struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
Documentation/pm_qos_interface.txt
View file @ 5347112
1   -PM quality of Service interface.
2   -
3   -This interface provides a kernel and user mode interface for registering
4   -performance expectations by drivers, subsystems and user space applications on
5   -one of the parameters.
6   -
7   -Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
8   -initial set of pm_qos parameters.
9   -
10   -The infrastructure exposes multiple misc device nodes one per implemented
11   -parameter. The set of parameters implement is defined by pm_qos_power_init()
12   -and pm_qos_params.h. This is done because having the available parameters
13   -being runtime configurable or changeable from a driver was seen as too easy to
14   -abuse.
15   -
16   -For each parameter a list of performance requirements is maintained along with
17   -an aggregated target value. The aggregated target value is updated with
18   -changes to the requirement list or elements of the list. Typically the
19   -aggregated target value is simply the max or min of the requirement values held
20   -in the parameter list elements.
21   -
22   -From kernel mode the use of this interface is simple:
23   -pm_qos_add_requirement(param_id, name, target_value):
24   -Will insert a named element in the list for that identified PM_QOS parameter
25   -with the target value. Upon change to this list the new target is recomputed
26   -and any registered notifiers are called only if the target value is now
27   -different.
28   -
29   -pm_qos_update_requirement(param_id, name, new_target_value):
30   -Will search the list identified by the param_id for the named list element and
31   -then update its target value, calling the notification tree if the aggregated
32   -target is changed. with that name is already registered.
33   -
34   -pm_qos_remove_requirement(param_id, name):
35   -Will search the identified list for the named element and remove it, after
36   -removal it will update the aggregate target and call the notification tree if
37   -the target was changed as a result of removing the named requirement.
38   -
39   -
40   -From user mode:
41   -Only processes can register a pm_qos requirement. To provide for automatic
42   -cleanup for process the interface requires the process to register its
43   -parameter requirements in the following way:
44   -
45   -To register the default pm_qos target for the specific parameter, the process
46   -must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
47   -
48   -As long as the device node is held open that process has a registered
49   -requirement on the parameter. The name of the requirement is "process_<PID>"
50   -derived from the current->pid from within the open system call.
51   -
52   -To change the requested target value the process needs to write a s32 value to
53   -the open device node. This translates to a pm_qos_update_requirement call.
54   -
55   -To remove the user mode request for a target value simply close the device
56   -node.
Documentation/power/00-INDEX
Diff comments   View file @ 5347112
... ... @@ -14,6 +14,12 @@
14 14 - Registering suspend notifiers in device drivers
15 15 pci.txt
16 16 - How the PCI Subsystem Does Power Management
  17 +pm.txt
  18 + - info on Linux power management support.
  19 +pm_qos_interface.txt
  20 + - info on Linux PM Quality of Service interface
  21 +power_supply_class.txt
  22 + - Tells userspace about battery, UPS, AC or DC power supply properties
17 23 s2ram.txt
18 24 - How to get suspend to ram working (and debug it when it isn't)
19 25 states.txt
Documentation/power/pm.txt
Diff comments   View file @ 5347112
  1 + Linux Power Management Support
  2 +
  3 +This document briefly describes how to use power management with your
  4 +Linux system and how to add power management support to Linux drivers.
  5 +
  6 +APM or ACPI?
  7 +------------
  8 +If you have a relatively recent x86 mobile, desktop, or server system,
  9 +odds are it supports either Advanced Power Management (APM) or
  10 +Advanced Configuration and Power Interface (ACPI). ACPI is the newer
  11 +of the two technologies and puts power management in the hands of the
  12 +operating system, allowing for more intelligent power management than
  13 +is possible with BIOS controlled APM.
  14 +
  15 +The best way to determine which, if either, your system supports is to
  16 +build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
  17 +enabled by default). If a working ACPI implementation is found, the
  18 +ACPI driver will override and disable APM, otherwise the APM driver
  19 +will be used.
  20 +
  21 +No, sorry, you cannot have both ACPI and APM enabled and running at
  22 +once. Some people with broken ACPI or broken APM implementations
  23 +would like to use both to get a full set of working features, but you
  24 +simply cannot mix and match the two. Only one power management
  25 +interface can be in control of the machine at once. Think about it..
  26 +
  27 +User-space Daemons
  28 +------------------
  29 +Both APM and ACPI rely on user-space daemons, apmd and acpid
  30 +respectively, to be completely functional. Obtain both of these
  31 +daemons from your Linux distribution or from the Internet (see below)
  32 +and be sure that they are started sometime in the system boot process.
  33 +Go ahead and start both. If ACPI or APM is not available on your
  34 +system the associated daemon will exit gracefully.
  35 +
  36 + apmd: http://worldvisions.ca/~apenwarr/apmd/
  37 + acpid: http://acpid.sf.net/
  38 +
  39 +Driver Interface -- OBSOLETE, DO NOT USE!
  40 +----------------*************************
  41 +
  42 +Note: pm_register(), pm_access(), pm_dev_idle() and friends are
  43 +obsolete. Please do not use them. Instead you should properly hook
  44 +your driver into the driver model, and use its suspend()/resume()
  45 +callbacks to do this kind of stuff.
  46 +
  47 +If you are writing a new driver or maintaining an old driver, it
  48 +should include power management support. Without power management
  49 +support, a single driver may prevent a system with power management
  50 +capabilities from ever being able to suspend (safely).
  51 +
  52 +Overview:
  53 +1) Register each instance of a device with "pm_register"
  54 +2) Call "pm_access" before accessing the hardware.
  55 + (this will ensure that the hardware is awake and ready)
  56 +3) Your "pm_callback" is called before going into a
  57 + suspend state (ACPI D1-D3) or after resuming (ACPI D0)
  58 + from a suspend.
  59 +4) Call "pm_dev_idle" when the device is not being used
  60 + (optional but will improve device idle detection)
  61 +5) 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 + */
  79 +struct 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 + */
  87 +void 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 + */
  97 +void 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 + */
  124 +typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
  125 +
  126 +Driver Details
  127 +--------------
  128 +This is just a quick Q&A as a stopgap until a real driver writers'
  129 +power management guide is available.
  130 +
  131 +Q: When is a device suspended?
  132 +
  133 +Devices can be suspended based on direct user request (eg. laptop lid
  134 +closes), system power policy (eg. sleep after 30 minutes of console
  135 +inactivity), or device power policy (eg. power down device after 5
  136 +minutes of inactivity)
  137 +
  138 +Q: Must a driver honor a suspend request?
  139 +
  140 +No, a driver can return -EBUSY from a suspend request and this
  141 +will stop the system from suspending. When a suspend request
  142 +fails, all suspended devices are resumed and the system continues
  143 +to run. Suspend can be retried at a later time.
  144 +
  145 +Q: Can the driver block suspend/resume requests?
  146 +
  147 +Yes, a driver can delay its return from a suspend or resume
  148 +request until the device is ready to handle requests. It
  149 +is advantageous to return as quickly as possible from a
  150 +request as suspend/resume are done serially.
  151 +
  152 +Q: What context is a suspend/resume initiated from?
  153 +
  154 +A suspend or resume is initiated from a kernel thread context.
  155 +It is safe to block, allocate memory, initiate requests
  156 +or anything else you can do within the kernel.
  157 +
  158 +Q: Will requests continue to arrive after a suspend?
  159 +
  160 +Possibly. It is the driver's responsibility to queue(*),
  161 +fail, or drop any requests that arrive after returning
  162 +success to a suspend request. It is important that the
  163 +driver not access its device until after it receives
  164 +a resume request as the device's bus may no longer
  165 +be 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 +
  173 +Q: Do I have to manage bus-specific power management registers
  174 +
  175 +No. It is the responsibility of the bus driver to manage
  176 +PCI, USB, etc. power management registers. The bus driver
  177 +or the power management subsystem will also enable any
  178 +wake-on functionality that the device has.
  179 +
  180 +Q: So, really, what do I need to do to support suspend/resume?
  181 +
  182 +You need to save any device context that would
  183 +be lost if the device was powered off and then restore
  184 +it at resume time. When ACPI is active, there are
  185 +three levels of device suspend states; D1, D2, and D3.
  186 +(The suspend state is passed as the "data" argument
  187 +to the device callback.) With D3, the device is powered
  188 +off and loses all context, D1 and D2 are shallower power
  189 +states and require less device context to be saved. To
  190 +play it safe, just save everything at suspend and restore
  191 +everything at resume.
  192 +
  193 +Q: Where do I store device context for suspend?
  194 +
  195 +Anywhere in memory, kmalloc a buffer or store it
  196 +in the device descriptor. You are guaranteed that the
  197 +contents of memory will be restored and accessible
  198 +before resume, even when the system suspends to disk.
  199 +
  200 +Q: What do I need to do for ACPI vs. APM vs. etc?
  201 +
  202 +Drivers need not be aware of the specific power management
  203 +technology that is active. They just need to be aware
  204 +of when the overlying power management system requests
  205 +that they suspend or resume.
  206 +
  207 +Q: What about device dependencies?
  208 +
  209 +When a driver registers a device, the power management
  210 +subsystem uses the information provided to build a
  211 +tree of device dependencies (eg. USB device X is on
  212 +USB controller Y which is on PCI bus Z) When power
  213 +management wants to suspend a device, it first sends
  214 +a suspend request to its driver, then the bus driver,
  215 +and so on up to the system bus. Device resumes
  216 +proceed in the opposite direction.
  217 +
  218 +Q: Who do I contact for additional information about
  219 + enabling power management for my specific driver/device?
  220 +
  221 +ACPI Development mailing list: linux-acpi@vger.kernel.org
  222 +
  223 +System Interface -- OBSOLETE, DO NOT USE!
  224 +----------------*************************
  225 +If you are providing new power management support to Linux (ie.
  226 +adding support for something like APM or ACPI), you should
  227 +communicate with drivers through the existing generic power
  228 +management 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 + */
  246 +int 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 + */
  257 +struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
Documentation/power/pm_qos_interface.txt
Diff comments   View file @ 5347112
  1 +PM quality of Service interface.
  2 +
  3 +This interface provides a kernel and user mode interface for registering
  4 +performance expectations by drivers, subsystems and user space applications on
  5 +one of the parameters.
  6 +
  7 +Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
  8 +initial set of pm_qos parameters.
  9 +
  10 +The infrastructure exposes multiple misc device nodes one per implemented
  11 +parameter. The set of parameters implement is defined by pm_qos_power_init()
  12 +and pm_qos_params.h. This is done because having the available parameters
  13 +being runtime configurable or changeable from a driver was seen as too easy to
  14 +abuse.
  15 +
  16 +For each parameter a list of performance requirements is maintained along with
  17 +an aggregated target value. The aggregated target value is updated with
  18 +changes to the requirement list or elements of the list. Typically the
  19 +aggregated target value is simply the max or min of the requirement values held
  20 +in the parameter list elements.
  21 +
  22 +From kernel mode the use of this interface is simple:
  23 +pm_qos_add_requirement(param_id, name, target_value):
  24 +Will insert a named element in the list for that identified PM_QOS parameter
  25 +with the target value. Upon change to this list the new target is recomputed
  26 +and any registered notifiers are called only if the target value is now
  27 +different.
  28 +
  29 +pm_qos_update_requirement(param_id, name, new_target_value):
  30 +Will search the list identified by the param_id for the named list element and
  31 +then update its target value, calling the notification tree if the aggregated
  32 +target is changed. with that name is already registered.
  33 +
  34 +pm_qos_remove_requirement(param_id, name):
  35 +Will search the identified list for the named element and remove it, after
  36 +removal it will update the aggregate target and call the notification tree if
  37 +the target was changed as a result of removing the named requirement.
  38 +
  39 +
  40 +From user mode:
  41 +Only processes can register a pm_qos requirement. To provide for automatic
  42 +cleanup for process the interface requires the process to register its
  43 +parameter requirements in the following way:
  44 +
  45 +To register the default pm_qos target for the specific parameter, the process
  46 +must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
  47 +
  48 +As long as the device node is held open that process has a registered
  49 +requirement on the parameter. The name of the requirement is "process_<PID>"
  50 +derived from the current->pid from within the open system call.
  51 +
  52 +To change the requested target value the process needs to write a s32 value to
  53 +the open device node. This translates to a pm_qos_update_requirement call.
  54 +
  55 +To remove the user mode request for a target value simply close the device
  56 +node.
Documentation/power/power_supply_class.txt
Diff comments   View file @ 5347112
  1 +Linux power supply class
  2 +========================
  3 +
  4 +Synopsis
  5 +~~~~~~~~
  6 +Power supply class used to represent battery, UPS, AC or DC power supply
  7 +properties to user-space.
  8 +
  9 +It defines core set of attributes, which should be applicable to (almost)
  10 +every power supply out there. Attributes are available via sysfs and uevent
  11 +interfaces.
  12 +
  13 +Each attribute has well defined meaning, up to unit of measure used. While
  14 +the attributes provided are believed to be universally applicable to any
  15 +power supply, specific monitoring hardware may not be able to provide them
  16 +all, so any of them may be skipped.
  17 +
  18 +Power supply class is extensible, and allows to define drivers own attributes.
  19 +The core attribute set is subject to the standard Linux evolution (i.e.
  20 +if it will be found that some attribute is applicable to many power supply
  21 +types or their drivers, it can be added to the core set).
  22 +
  23 +It also integrates with LED framework, for the purpose of providing
  24 +typically expected feedback of battery charging/fully charged status and
  25 +AC/USB power supply online status. (Note that specific details of the
  26 +indication (including whether to use it at all) are fully controllable by
  27 +user and/or specific machine defaults, per design principles of LED
  28 +framework).
  29 +
  30 +
  31 +Attributes/properties
  32 +~~~~~~~~~~~~~~~~~~~~~
  33 +Power supply class has predefined set of attributes, this eliminates code
  34 +duplication across drivers. Power supply class insist on reusing its
  35 +predefined attributes *and* their units.
  36 +
  37 +So, userspace gets predictable set of attributes and their units for any
  38 +kind of power supply, and can process/present them to a user in consistent
  39 +manner. Results for different power supplies and machines are also directly
  40 +comparable.
  41 +
  42 +See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
  43 +example how to declare and handle attributes.
  44 +
  45 +
  46 +Units
  47 +~~~~~
  48 +Quoting 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 +
  56 +Attributes/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 +
  70 +Postfixes:
  71 +_AVG - *hardware* averaged value, use it if your hardware is really able to
  72 +report averaged values.
  73 +_NOW - momentary/instantaneous values.
  74 +
  75 +STATUS - this attribute represents operating status (charging, full,
  76 +discharging (i.e. powering a load), etc.). This corresponds to
  77 +BATTERY_STATUS_* values, as defined in battery.h.
  78 +
  79 +HEALTH - represents health of the battery, values corresponds to
  80 +POWER_SUPPLY_HEALTH_*, defined in battery.h.
  81 +
  82 +VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
  83 +minimal power supply voltages. Maximal/minimal means values of voltages
  84 +when battery considered "full"/"empty" at normal conditions. Yes, there is
  85 +no direct relation between voltage and battery capacity, but some dumb
  86 +batteries use voltage for very approximated calculation of capacity.
  87 +Battery driver also can use this attribute just to inform userspace
  88 +about maximal and minimal voltage thresholds of a given battery.
  89 +
  90 +VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
  91 +these ones should be used if hardware could only guess (measure and
  92 +retain) the thresholds of a given power supply.
  93 +
  94 +CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
  95 +battery considered full/empty.
  96 +
  97 +ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
  98 +
  99 +CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
  100 +of charge when battery became full/empty". It also could mean "value of
  101 +charge when battery considered full/empty at given conditions (temperature,
  102 +age)". I.e. these attributes represents real thresholds, not design values.
  103 +
  104 +ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
  105 +
  106 +CAPACITY - capacity in percents.
  107 +
  108 +TEMP - temperature of the power supply.
  109 +TEMP_AMBIENT - ambient temperature.
  110 +
  111 +TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
  112 +while battery powers a load)
  113 +TIME_TO_FULL - seconds left for battery to be considered full (i.e.
  114 +while battery is charging)
  115 +
  116 +
  117 +Battery <-> external power supply interaction
  118 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  119 +Often power supplies are acting as supplies and supplicants at the same
  120 +time. Batteries are good example. So, batteries usually care if they're
  121 +externally powered or not.
  122 +
  123 +For that case, power supply class implements notification mechanism for
  124 +batteries.
  125 +
  126 +External power supply (AC) lists supplicants (batteries) names in
  127 +"supplied_to" struct member, and each power_supply_changed() call
  128 +issued by external power supply will notify supplicants via
  129 +external_power_changed callback.
  130 +
  131 +
  132 +QA
  133 +~~
  134 +Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
  135 +A: 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 +
  145 +Q: I have some very specific attribute (e.g. battery color), should I add
  146 + this attribute to standard ones?
  147 +A: 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 +
  154 +Q: 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.
  158 +A: 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.
Documentation/power_supply_class.txt
View file @ 5347112
1   -Linux power supply class
2   -========================
3   -
4   -Synopsis
5   -~~~~~~~~
6   -Power supply class used to represent battery, UPS, AC or DC power supply
7   -properties to user-space.
8   -
9   -It defines core set of attributes, which should be applicable to (almost)
10   -every power supply out there. Attributes are available via sysfs and uevent
11   -interfaces.
12   -
13   -Each attribute has well defined meaning, up to unit of measure used. While
14   -the attributes provided are believed to be universally applicable to any
15   -power supply, specific monitoring hardware may not be able to provide them
16   -all, so any of them may be skipped.
17   -
18   -Power supply class is extensible, and allows to define drivers own attributes.
19   -The core attribute set is subject to the standard Linux evolution (i.e.
20   -if it will be found that some attribute is applicable to many power supply
21   -types or their drivers, it can be added to the core set).
22   -
23   -It also integrates with LED framework, for the purpose of providing
24   -typically expected feedback of battery charging/fully charged status and
25   -AC/USB power supply online status. (Note that specific details of the
26   -indication (including whether to use it at all) are fully controllable by
27   -user and/or specific machine defaults, per design principles of LED
28   -framework).
29   -
30   -
31   -Attributes/properties
32   -~~~~~~~~~~~~~~~~~~~~~
33   -Power supply class has predefined set of attributes, this eliminates code
34   -duplication across drivers. Power supply class insist on reusing its
35   -predefined attributes *and* their units.
36   -
37   -So, userspace gets predictable set of attributes and their units for any
38   -kind of power supply, and can process/present them to a user in consistent
39   -manner. Results for different power supplies and machines are also directly
40   -comparable.
41   -
42   -See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
43   -example how to declare and handle attributes.
44   -
45   -
46   -Units
47   -~~~~~
48   -Quoting 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   -
56   -Attributes/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   -
70   -Postfixes:
71   -_AVG - *hardware* averaged value, use it if your hardware is really able to
72   -report averaged values.
73   -_NOW - momentary/instantaneous values.
74   -
75   -STATUS - this attribute represents operating status (charging, full,
76   -discharging (i.e. powering a load), etc.). This corresponds to
77   -BATTERY_STATUS_* values, as defined in battery.h.
78   -
79   -HEALTH - represents health of the battery, values corresponds to
80   -POWER_SUPPLY_HEALTH_*, defined in battery.h.
81   -
82   -VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
83   -minimal power supply voltages. Maximal/minimal means values of voltages
84   -when battery considered "full"/"empty" at normal conditions. Yes, there is
85   -no direct relation between voltage and battery capacity, but some dumb
86   -batteries use voltage for very approximated calculation of capacity.
87   -Battery driver also can use this attribute just to inform userspace
88   -about maximal and minimal voltage thresholds of a given battery.
89   -
90   -VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
91   -these ones should be used if hardware could only guess (measure and
92   -retain) the thresholds of a given power supply.
93   -
94   -CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
95   -battery considered full/empty.
96   -
97   -ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
98   -
99   -CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
100   -of charge when battery became full/empty". It also could mean "value of
101   -charge when battery considered full/empty at given conditions (temperature,
102   -age)". I.e. these attributes represents real thresholds, not design values.
103   -
104   -ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
105   -
106   -CAPACITY - capacity in percents.
107   -
108   -TEMP - temperature of the power supply.
109   -TEMP_AMBIENT - ambient temperature.
110   -
111   -TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
112   -while battery powers a load)
113   -TIME_TO_FULL - seconds left for battery to be considered full (i.e.
114   -while battery is charging)
115   -
116   -
117   -Battery <-> external power supply interaction
118   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119   -Often power supplies are acting as supplies and supplicants at the same
120   -time. Batteries are good example. So, batteries usually care if they're
121   -externally powered or not.
122   -
123   -For that case, power supply class implements notification mechanism for
124   -batteries.
125   -
126   -External power supply (AC) lists supplicants (batteries) names in
127   -"supplied_to" struct member, and each power_supply_changed() call
128   -issued by external power supply will notify supplicants via
129   -external_power_changed callback.
130   -
131   -
132   -QA
133   -~~
134   -Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
135   -A: 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   -
145   -Q: I have some very specific attribute (e.g. battery color), should I add
146   - this attribute to standard ones?
147   -A: 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   -
154   -Q: 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.
158   -A: 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.
... ... @@ -1259,7 +1259,7 @@
1259 1259 machines with more than one CPU.
1260 1260  
1261 1261 In order to use APM, you will need supporting software. For location
1262   - and more information, read <file:Documentation/pm.txt> and the
  1262 + and more information, read <file:Documentation/power/pm.txt> and the
1263 1263 Battery Powered Linux mini-HOWTO, available from
1264 1264 <http://www.tldp.org/docs.html#howto>.
1265 1265  
kernel/power/Kconfig
Diff comments   View file @ 5347112
... ... @@ -190,7 +190,7 @@
190 190 notification of APM "events" (e.g. battery status change).
191 191  
192 192 In order to use APM, you will need supporting software. For location
193   - and more information, read <file:Documentation/pm.txt> and the
  193 + and more information, read <file:Documentation/power/pm.txt> and the
194 194 Battery Powered Linux mini-HOWTO, available from
195 195 <http://www.tldp.org/docs.html#howto>.
196 196