[PATCH] doc/power: move power-related files to Documentation/power/

[PATCH] doc/power: move power-related files to Documentation/power/

[Randy Dunlap]

From: Randy Dunlap <randy.dunlap@oracle.com>

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>
---
 Documentation/00-INDEX                     |    4 
 Documentation/kernel-parameters.txt        |    2 
 Documentation/pm.txt                       |  257 -------------------
 Documentation/pm_qos_interface.txt         |   59 ----
 Documentation/power/00-INDEX               |    6 
 Documentation/power/pm.txt                 |  257 +++++++++++++++++++
 Documentation/power/pm_qos_interface.txt   |   59 ++++
 Documentation/power/power_supply_class.txt |  169 ++++++++++++
 Documentation/power_supply_class.txt       |  169 ------------
 arch/x86/Kconfig                           |    2 
 kernel/power/Kconfig                       |    2 
 11 files changed, 494 insertions(+), 492 deletions(-)

--- linux-2.6.25-rc3-git6.orig/Documentation/00-INDEX
+++ linux-2.6.25-rc3-git6/Documentation/00-INDEX
@@ -303,12 +303,8 @@ pcmcia/
 	- info on the Linux PCMCIA driver.
 pi-futex.txt
 	- documentation on lightweight PI-futexes.
-pm.txt
-	- info on Linux power management support.
 pnp.txt
 	- Linux Plug and Play documentation.
-power_supply_class.txt
-	- Tells userspace about battery, UPS, AC or DC power supply properties
 power/
 	- directory with info on Linux PCI power management.
 powerpc/
--- linux-2.6.25-rc3-git6.orig/Documentation/power/00-INDEX
+++ linux-2.6.25-rc3-git6/Documentation/power/00-INDEX
@@ -14,6 +14,12 @@ notifiers.txt
 	- Registering suspend notifiers in device drivers
 pci.txt
 	- How the PCI Subsystem Does Power Management
+pm.txt
+	- info on Linux power management support.
+pm_qos_interface.txt
+	- info on Linux PM Quality of Service interface
+power_supply_class.txt
+	- Tells userspace about battery, UPS, AC or DC power supply properties
 s2ram.txt
 	- How to get suspend to ram working (and debug it when it isn't)
 states.txt
--- linux-2.6.25-rc3-git6.orig/Documentation/pm.txt
+++ /dev/null
@@ -1,257 +0,0 @@
-               Linux Power Management Support
-
-This document briefly describes how to use power management with your
-Linux system and how to add power management support to Linux drivers.
-
-APM or ACPI?
-------------
-If you have a relatively recent x86 mobile, desktop, or server system,
-odds are it supports either Advanced Power Management (APM) or
-Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
-of the two technologies and puts power management in the hands of the
-operating system, allowing for more intelligent power management than
-is possible with BIOS controlled APM.
-
-The best way to determine which, if either, your system supports is to
-build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
-enabled by default).  If a working ACPI implementation is found, the
-ACPI driver will override and disable APM, otherwise the APM driver
-will be used.
-
-No, sorry, you cannot have both ACPI and APM enabled and running at
-once.  Some people with broken ACPI or broken APM implementations
-would like to use both to get a full set of working features, but you
-simply cannot mix and match the two.  Only one power management
-interface can be in control of the machine at once.  Think about it..
-
-User-space Daemons
-------------------
-Both APM and ACPI rely on user-space daemons, apmd and acpid
-respectively, to be completely functional.  Obtain both of these
-daemons from your Linux distribution or from the Internet (see below)
-and be sure that they are started sometime in the system boot process.
-Go ahead and start both.  If ACPI or APM is not available on your
-system the associated daemon will exit gracefully.
-
-  apmd:   http://worldvisions.ca/~apenwarr/apmd/
-  acpid:  http://acpid.sf.net/
-
-Driver Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-
-Note: pm_register(), pm_access(), pm_dev_idle() and friends are
-obsolete. Please do not use them. Instead you should properly hook
-your driver into the driver model, and use its suspend()/resume()
-callbacks to do this kind of stuff.
-
-If you are writing a new driver or maintaining an old driver, it
-should include power management support.  Without power management
-support, a single driver may prevent a system with power management
-capabilities from ever being able to suspend (safely).
-
-Overview:
-1) Register each instance of a device with "pm_register"
-2) Call "pm_access" before accessing the hardware.
-   (this will ensure that the hardware is awake and ready)
-3) Your "pm_callback" is called before going into a
-   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
-   from a suspend.
-4) Call "pm_dev_idle" when the device is not being used
-   (optional but will improve device idle detection)
-5) When unloaded, unregister the device with "pm_unregister"
-
-/*
- * Description: Register a device with the power-management subsystem
- *
- * Parameters:
- *   type - device type (PCI device, system device, ...)
- *   id - instance number or unique identifier
- *   cback - request handler callback (suspend, resume, ...)
- *
- * Returns: Registered PM device or NULL on error
- *
- * Examples:
- *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
- *
- *   struct pci_dev *pci_dev = pci_find_dev(...);
- *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
- */
-struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
-
-/*
- * Description: Unregister a device with the power management subsystem
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- */
-void pm_unregister(struct pm_dev *dev);
-
-/*
- * Description: Unregister all devices with a matching callback function
- *
- * Parameters:
- *   cback - previously registered request callback
- *
- * Notes: Provided for easier porting from old APM interface
- */
-void pm_unregister_all(pm_callback cback);
-
-/*
- * Power management request callback
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          EINVAL if the request is not supported
- *          EBUSY if the device is now busy and cannot handle the request
- *          ENOMEM if the device was unable to handle the request due to memory
- *          
- * Details: The device request callback will be called before the
- *          device/system enters a suspend state (ACPI D1-D3) or
- *          or after the device/system resumes from suspend (ACPI D0).
- *          For PM_SUSPEND, the ACPI D-state being entered is passed
- *          as the "data" argument to the callback.  The device
- *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
- *          device context when the request callback is called.
- *
- *          Once a driver returns 0 (success) from a suspend
- *          request, it should not process any further requests or
- *          access the device hardware until a call to "pm_access" is made.
- */
-typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
-
-Driver Details
---------------
-This is just a quick Q&A as a stopgap until a real driver writers'
-power management guide is available.
-
-Q: When is a device suspended?
-
-Devices can be suspended based on direct user request (eg. laptop lid
-closes), system power policy (eg.  sleep after 30 minutes of console
-inactivity), or device power policy (eg. power down device after 5
-minutes of inactivity)
-
-Q: Must a driver honor a suspend request?
-
-No, a driver can return -EBUSY from a suspend request and this
-will stop the system from suspending.  When a suspend request
-fails, all suspended devices are resumed and the system continues
-to run.  Suspend can be retried at a later time.
-
-Q: Can the driver block suspend/resume requests?
-
-Yes, a driver can delay its return from a suspend or resume
-request until the device is ready to handle requests.  It
-is advantageous to return as quickly as possible from a
-request as suspend/resume are done serially.
-
-Q: What context is a suspend/resume initiated from?
-
-A suspend or resume is initiated from a kernel thread context.
-It is safe to block, allocate memory, initiate requests
-or anything else you can do within the kernel.
-
-Q: Will requests continue to arrive after a suspend?
-
-Possibly.  It is the driver's responsibility to queue(*),
-fail, or drop any requests that arrive after returning
-success to a suspend request.  It is important that the
-driver not access its device until after it receives
-a resume request as the device's bus may no longer
-be active.
-
-(*) If a driver queues requests for processing after
-    resume be aware that the device, network, etc.
-    might be in a different state than at suspend time.
-    It's probably better to drop requests unless
-    the driver is a storage device.
-
-Q: Do I have to manage bus-specific power management registers
-
-No.  It is the responsibility of the bus driver to manage
-PCI, USB, etc. power management registers.  The bus driver
-or the power management subsystem will also enable any
-wake-on functionality that the device has.
-
-Q: So, really, what do I need to do to support suspend/resume?
-
-You need to save any device context that would
-be lost if the device was powered off and then restore
-it at resume time.  When ACPI is active, there are
-three levels of device suspend states; D1, D2, and D3.
-(The suspend state is passed as the "data" argument
-to the device callback.)  With D3, the device is powered
-off and loses all context, D1 and D2 are shallower power
-states and require less device context to be saved.  To
-play it safe, just save everything at suspend and restore
-everything at resume.
-
-Q: Where do I store device context for suspend?
-
-Anywhere in memory, kmalloc a buffer or store it
-in the device descriptor.  You are guaranteed that the
-contents of memory will be restored and accessible
-before resume, even when the system suspends to disk.
-
-Q: What do I need to do for ACPI vs. APM vs. etc?
-
-Drivers need not be aware of the specific power management
-technology that is active.  They just need to be aware
-of when the overlying power management system requests
-that they suspend or resume.
-
-Q: What about device dependencies?
-
-When a driver registers a device, the power management
-subsystem uses the information provided to build a
-tree of device dependencies (eg. USB device X is on
-USB controller Y which is on PCI bus Z)  When power
-management wants to suspend a device, it first sends
-a suspend request to its driver, then the bus driver,
-and so on up to the system bus.  Device resumes
-proceed in the opposite direction.
-
-Q: Who do I contact for additional information about
-   enabling power management for my specific driver/device?
-
-ACPI Development mailing list: linux-acpi@vger.kernel.org
-
-System Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-If you are providing new power management support to Linux (ie.
-adding support for something like APM or ACPI), you should
-communicate with drivers through the existing generic power
-management interface.
-
-/*
- * Send a request to all devices
- *
- * Parameters:
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          See "pm_callback" return for errors
- *
- * Details: Walk list of registered devices and call pm_send
- *          for each until complete or an error is encountered.
- *          If an error is encountered for a suspend request,
- *          return all devices to the state they were in before
- *          the suspend request.
- */
-int pm_send_all(pm_request_t rqst, void *data);
-
-/*
- * Find a matching device
- *
- * Parameters:
- *   type - device type (PCI device, system device, or 0 to match all devices)
- *   from - previous match or NULL to start from the beginning
- *
- * Returns: Matching device or NULL if none found
- */
-struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- /dev/null
+++ linux-2.6.25-rc3-git6/Documentation/power/pm.txt
@@ -0,0 +1,257 @@
+               Linux Power Management Support
+
+This document briefly describes how to use power management with your
+Linux system and how to add power management support to Linux drivers.
+
+APM or ACPI?
+------------
+If you have a relatively recent x86 mobile, desktop, or server system,
+odds are it supports either Advanced Power Management (APM) or
+Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
+of the two technologies and puts power management in the hands of the
+operating system, allowing for more intelligent power management than
+is possible with BIOS controlled APM.
+
+The best way to determine which, if either, your system supports is to
+build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
+enabled by default).  If a working ACPI implementation is found, the
+ACPI driver will override and disable APM, otherwise the APM driver
+will be used.
+
+No, sorry, you cannot have both ACPI and APM enabled and running at
+once.  Some people with broken ACPI or broken APM implementations
+would like to use both to get a full set of working features, but you
+simply cannot mix and match the two.  Only one power management
+interface can be in control of the machine at once.  Think about it..
+
+User-space Daemons
+------------------
+Both APM and ACPI rely on user-space daemons, apmd and acpid
+respectively, to be completely functional.  Obtain both of these
+daemons from your Linux distribution or from the Internet (see below)
+and be sure that they are started sometime in the system boot process.
+Go ahead and start both.  If ACPI or APM is not available on your
+system the associated daemon will exit gracefully.
+
+  apmd:   http://worldvisions.ca/~apenwarr/apmd/
+  acpid:  http://acpid.sf.net/
+
+Driver Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+
+Note: pm_register(), pm_access(), pm_dev_idle() and friends are
+obsolete. Please do not use them. Instead you should properly hook
+your driver into the driver model, and use its suspend()/resume()
+callbacks to do this kind of stuff.
+
+If you are writing a new driver or maintaining an old driver, it
+should include power management support.  Without power management
+support, a single driver may prevent a system with power management
+capabilities from ever being able to suspend (safely).
+
+Overview:
+1) Register each instance of a device with "pm_register"
+2) Call "pm_access" before accessing the hardware.
+   (this will ensure that the hardware is awake and ready)
+3) Your "pm_callback" is called before going into a
+   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
+   from a suspend.
+4) Call "pm_dev_idle" when the device is not being used
+   (optional but will improve device idle detection)
+5) When unloaded, unregister the device with "pm_unregister"
+
+/*
+ * Description: Register a device with the power-management subsystem
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, ...)
+ *   id - instance number or unique identifier
+ *   cback - request handler callback (suspend, resume, ...)
+ *
+ * Returns: Registered PM device or NULL on error
+ *
+ * Examples:
+ *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
+ *
+ *   struct pci_dev *pci_dev = pci_find_dev(...);
+ *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
+ */
+struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
+
+/*
+ * Description: Unregister a device with the power management subsystem
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ */
+void pm_unregister(struct pm_dev *dev);
+
+/*
+ * Description: Unregister all devices with a matching callback function
+ *
+ * Parameters:
+ *   cback - previously registered request callback
+ *
+ * Notes: Provided for easier porting from old APM interface
+ */
+void pm_unregister_all(pm_callback cback);
+
+/*
+ * Power management request callback
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          EINVAL if the request is not supported
+ *          EBUSY if the device is now busy and cannot handle the request
+ *          ENOMEM if the device was unable to handle the request due to memory
+ *
+ * Details: The device request callback will be called before the
+ *          device/system enters a suspend state (ACPI D1-D3) or
+ *          or after the device/system resumes from suspend (ACPI D0).
+ *          For PM_SUSPEND, the ACPI D-state being entered is passed
+ *          as the "data" argument to the callback.  The device
+ *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
+ *          device context when the request callback is called.
+ *
+ *          Once a driver returns 0 (success) from a suspend
+ *          request, it should not process any further requests or
+ *          access the device hardware until a call to "pm_access" is made.
+ */
+typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
+
+Driver Details
+--------------
+This is just a quick Q&A as a stopgap until a real driver writers'
+power management guide is available.
+
+Q: When is a device suspended?
+
+Devices can be suspended based on direct user request (eg. laptop lid
+closes), system power policy (eg.  sleep after 30 minutes of console
+inactivity), or device power policy (eg. power down device after 5
+minutes of inactivity)
+
+Q: Must a driver honor a suspend request?
+
+No, a driver can return -EBUSY from a suspend request and this
+will stop the system from suspending.  When a suspend request
+fails, all suspended devices are resumed and the system continues
+to run.  Suspend can be retried at a later time.
+
+Q: Can the driver block suspend/resume requests?
+
+Yes, a driver can delay its return from a suspend or resume
+request until the device is ready to handle requests.  It
+is advantageous to return as quickly as possible from a
+request as suspend/resume are done serially.
+
+Q: What context is a suspend/resume initiated from?
+
+A suspend or resume is initiated from a kernel thread context.
+It is safe to block, allocate memory, initiate requests
+or anything else you can do within the kernel.
+
+Q: Will requests continue to arrive after a suspend?
+
+Possibly.  It is the driver's responsibility to queue(*),
+fail, or drop any requests that arrive after returning
+success to a suspend request.  It is important that the
+driver not access its device until after it receives
+a resume request as the device's bus may no longer
+be active.
+
+(*) If a driver queues requests for processing after
+    resume be aware that the device, network, etc.
+    might be in a different state than at suspend time.
+    It's probably better to drop requests unless
+    the driver is a storage device.
+
+Q: Do I have to manage bus-specific power management registers
+
+No.  It is the responsibility of the bus driver to manage
+PCI, USB, etc. power management registers.  The bus driver
+or the power management subsystem will also enable any
+wake-on functionality that the device has.
+
+Q: So, really, what do I need to do to support suspend/resume?
+
+You need to save any device context that would
+be lost if the device was powered off and then restore
+it at resume time.  When ACPI is active, there are
+three levels of device suspend states; D1, D2, and D3.
+(The suspend state is passed as the "data" argument
+to the device callback.)  With D3, the device is powered
+off and loses all context, D1 and D2 are shallower power
+states and require less device context to be saved.  To
+play it safe, just save everything at suspend and restore
+everything at resume.
+
+Q: Where do I store device context for suspend?
+
+Anywhere in memory, kmalloc a buffer or store it
+in the device descriptor.  You are guaranteed that the
+contents of memory will be restored and accessible
+before resume, even when the system suspends to disk.
+
+Q: What do I need to do for ACPI vs. APM vs. etc?
+
+Drivers need not be aware of the specific power management
+technology that is active.  They just need to be aware
+of when the overlying power management system requests
+that they suspend or resume.
+
+Q: What about device dependencies?
+
+When a driver registers a device, the power management
+subsystem uses the information provided to build a
+tree of device dependencies (eg. USB device X is on
+USB controller Y which is on PCI bus Z)  When power
+management wants to suspend a device, it first sends
+a suspend request to its driver, then the bus driver,
+and so on up to the system bus.  Device resumes
+proceed in the opposite direction.
+
+Q: Who do I contact for additional information about
+   enabling power management for my specific driver/device?
+
+ACPI Development mailing list: linux-acpi@vger.kernel.org
+
+System Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+If you are providing new power management support to Linux (ie.
+adding support for something like APM or ACPI), you should
+communicate with drivers through the existing generic power
+management interface.
+
+/*
+ * Send a request to all devices
+ *
+ * Parameters:
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          See "pm_callback" return for errors
+ *
+ * Details: Walk list of registered devices and call pm_send
+ *          for each until complete or an error is encountered.
+ *          If an error is encountered for a suspend request,
+ *          return all devices to the state they were in before
+ *          the suspend request.
+ */
+int pm_send_all(pm_request_t rqst, void *data);
+
+/*
+ * Find a matching device
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, or 0 to match all devices)
+ *   from - previous match or NULL to start from the beginning
+ *
+ * Returns: Matching device or NULL if none found
+ */
+struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- linux-2.6.25-rc3-git6.orig/Documentation/pm_qos_interface.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-PM quality of Service interface.
-
-This interface provides a kernel and user mode interface for registering
-performance expectations by drivers, subsystems and user space applications on
-one of the parameters.
-
-Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
-initial set of pm_qos parameters.
-
-The infrastructure exposes multiple misc device nodes one per implemented
-parameter.  The set of parameters implement is defined by pm_qos_power_init()
-and pm_qos_params.h.  This is done because having the available parameters
-being runtime configurable or changeable from a driver was seen as too easy to
-abuse.
-
-For each parameter a list of performance requirements is maintained along with
-an aggregated target value.  The aggregated target value is updated with
-changes to the requirement list or elements of the list.  Typically the
-aggregated target value is simply the max or min of the requirement values held
-in the parameter list elements.
-
-From kernel mode the use of this interface is simple:
-pm_qos_add_requirement(param_id, name, target_value):
-Will insert a named element in the list for that identified PM_QOS parameter
-with the target value.  Upon change to this list the new target is recomputed
-and any registered notifiers are called only if the target value is now
-different.
-
-pm_qos_update_requirement(param_id, name, new_target_value):
-Will search the list identified by the param_id for the named list element and
-then update its target value, calling the notification tree if the aggregated
-target is changed.  with that name is already registered.
-
-pm_qos_remove_requirement(param_id, name):
-Will search the identified list for the named element and remove it, after
-removal it will update the aggregate target and call the notification tree if
-the target was changed as a result of removing the named requirement.
-
-
-From user mode:
-Only processes can register a pm_qos requirement.  To provide for automatic
-cleanup for process the interface requires the process to register its
-parameter requirements in the following way:
-
-To register the default pm_qos target for the specific parameter, the process
-must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
-
-As long as the device node is held open that process has a registered
-requirement on the parameter.  The name of the requirement is "process_<PID>"
-derived from the current->pid from within the open system call.
-
-To change the requested target value the process needs to write a s32 value to
-the open device node.  This translates to a pm_qos_update_requirement call.
-
-To remove the user mode request for a target value simply close the device
-node.
-
-
-
--- /dev/null
+++ linux-2.6.25-rc3-git6/Documentation/power/pm_qos_interface.txt
@@ -0,0 +1,59 @@
+PM quality of Service interface.
+
+This interface provides a kernel and user mode interface for registering
+performance expectations by drivers, subsystems and user space applications on
+one of the parameters.
+
+Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
+initial set of pm_qos parameters.
+
+The infrastructure exposes multiple misc device nodes one per implemented
+parameter.  The set of parameters implement is defined by pm_qos_power_init()
+and pm_qos_params.h.  This is done because having the available parameters
+being runtime configurable or changeable from a driver was seen as too easy to
+abuse.
+
+For each parameter a list of performance requirements is maintained along with
+an aggregated target value.  The aggregated target value is updated with
+changes to the requirement list or elements of the list.  Typically the
+aggregated target value is simply the max or min of the requirement values held
+in the parameter list elements.
+
+From kernel mode the use of this interface is simple:
+pm_qos_add_requirement(param_id, name, target_value):
+Will insert a named element in the list for that identified PM_QOS parameter
+with the target value.  Upon change to this list the new target is recomputed
+and any registered notifiers are called only if the target value is now
+different.
+
+pm_qos_update_requirement(param_id, name, new_target_value):
+Will search the list identified by the param_id for the named list element and
+then update its target value, calling the notification tree if the aggregated
+target is changed.  with that name is already registered.
+
+pm_qos_remove_requirement(param_id, name):
+Will search the identified list for the named element and remove it, after
+removal it will update the aggregate target and call the notification tree if
+the target was changed as a result of removing the named requirement.
+
+
+From user mode:
+Only processes can register a pm_qos requirement.  To provide for automatic
+cleanup for process the interface requires the process to register its
+parameter requirements in the following way:
+
+To register the default pm_qos target for the specific parameter, the process
+must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
+
+As long as the device node is held open that process has a registered
+requirement on the parameter.  The name of the requirement is "process_<PID>"
+derived from the current->pid from within the open system call.
+
+To change the requested target value the process needs to write a s32 value to
+the open device node.  This translates to a pm_qos_update_requirement call.
+
+To remove the user mode request for a target value simply close the device
+node.
+
+
+
--- /dev/null
+++ linux-2.6.25-rc3-git6/Documentation/power/power_supply_class.txt
@@ -0,0 +1,169 @@
+Linux power supply class
+========================
+
+Synopsis
+~~~~~~~~
+Power supply class used to represent battery, UPS, AC or DC power supply
+properties to user-space.
+
+It defines core set of attributes, which should be applicable to (almost)
+every power supply out there. Attributes are available via sysfs and uevent
+interfaces.
+
+Each attribute has well defined meaning, up to unit of measure used. While
+the attributes provided are believed to be universally applicable to any
+power supply, specific monitoring hardware may not be able to provide them
+all, so any of them may be skipped.
+
+Power supply class is extensible, and allows to define drivers own attributes.
+The core attribute set is subject to the standard Linux evolution (i.e.
+if it will be found that some attribute is applicable to many power supply
+types or their drivers, it can be added to the core set).
+
+It also integrates with LED framework, for the purpose of providing
+typically expected feedback of battery charging/fully charged status and
+AC/USB power supply online status. (Note that specific details of the
+indication (including whether to use it at all) are fully controllable by
+user and/or specific machine defaults, per design principles of LED
+framework).
+
+
+Attributes/properties
+~~~~~~~~~~~~~~~~~~~~~
+Power supply class has predefined set of attributes, this eliminates code
+duplication across drivers. Power supply class insist on reusing its
+predefined attributes *and* their units.
+
+So, userspace gets predictable set of attributes and their units for any
+kind of power supply, and can process/present them to a user in consistent
+manner. Results for different power supplies and machines are also directly
+comparable.
+
+See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
+example how to declare and handle attributes.
+
+
+Units
+~~~~~
+Quoting include/linux/power_supply.h:
+
+  All voltages, currents, charges, energies, time and temperatures in µV,
+  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
+  stated. It's driver's job to convert its raw values to units in which
+  this class operates.
+
+
+Attributes/properties detailed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
+~                                                                       ~
+~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
+~ of battery, this class distinguish these terms. Don't mix them!       ~
+~                                                                       ~
+~ CHARGE_* attributes represents capacity in µAh only.                  ~
+~ ENERGY_* attributes represents capacity in µWh only.                  ~
+~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
+~                                                                       ~
+~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+
+Postfixes:
+_AVG - *hardware* averaged value, use it if your hardware is really able to
+report averaged values.
+_NOW - momentary/instantaneous values.
+
+STATUS - this attribute represents operating status (charging, full,
+discharging (i.e. powering a load), etc.). This corresponds to
+BATTERY_STATUS_* values, as defined in battery.h.
+
+HEALTH - represents health of the battery, values corresponds to
+POWER_SUPPLY_HEALTH_*, defined in battery.h.
+
+VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
+minimal power supply voltages. Maximal/minimal means values of voltages
+when battery considered "full"/"empty" at normal conditions. Yes, there is
+no direct relation between voltage and battery capacity, but some dumb
+batteries use voltage for very approximated calculation of capacity.
+Battery driver also can use this attribute just to inform userspace
+about maximal and minimal voltage thresholds of a given battery.
+
+VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
+these ones should be used if hardware could only guess (measure and
+retain) the thresholds of a given power supply.
+
+CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
+battery considered full/empty.
+
+ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
+
+CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
+of charge when battery became full/empty". It also could mean "value of
+charge when battery considered full/empty at given conditions (temperature,
+age)". I.e. these attributes represents real thresholds, not design values.
+
+ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
+
+CAPACITY - capacity in percents.
+
+TEMP - temperature of the power supply.
+TEMP_AMBIENT - ambient temperature.
+
+TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
+while battery powers a load)
+TIME_TO_FULL - seconds left for battery to be considered full (i.e.
+while battery is charging)
+
+
+Battery <-> external power supply interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Often power supplies are acting as supplies and supplicants at the same
+time. Batteries are good example. So, batteries usually care if they're
+externally powered or not.
+
+For that case, power supply class implements notification mechanism for
+batteries.
+
+External power supply (AC) lists supplicants (batteries) names in
+"supplied_to" struct member, and each power_supply_changed() call
+issued by external power supply will notify supplicants via
+external_power_changed callback.
+
+
+QA
+~~
+Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
+A: If you cannot find attribute suitable for your driver needs, feel free
+   to add it and send patch along with your driver.
+
+   The attributes available currently are the ones currently provided by the
+   drivers written.
+
+   Good candidates to add in future: model/part#, cycle_time, manufacturer,
+   etc.
+
+
+Q: I have some very specific attribute (e.g. battery color), should I add
+   this attribute to standard ones?
+A: Most likely, no. Such attribute can be placed in the driver itself, if
+   it is useful. Of course, if the attribute in question applicable to
+   large set of batteries, provided by many drivers, and/or comes from
+   some general battery specification/standard, it may be a candidate to
+   be added to the core attribute set.
+
+
+Q: Suppose, my battery monitoring chip/firmware does not provides capacity
+   in percents, but provides charge_{now,full,empty}. Should I calculate
+   percentage capacity manually, inside the driver, and register CAPACITY
+   attribute? The same question about time_to_empty/time_to_full.
+A: Most likely, no. This class is designed to export properties which are
+   directly measurable by the specific hardware available.
+
+   Inferring not available properties using some heuristics or mathematical
+   model is not subject of work for a battery driver. Such functionality
+   should be factored out, and in fact, apm_power, the driver to serve
+   legacy APM API on top of power supply class, uses a simple heuristic of
+   approximating remaining battery capacity based on its charge, current,
+   voltage and so on. But full-fledged battery model is likely not subject
+   for kernel at all, as it would require floating point calculation to deal
+   with things like differential equations and Kalman filters. This is
+   better be handled by batteryd/libbattery, yet to be written.
--- linux-2.6.25-rc3-git6.orig/Documentation/power_supply_class.txt
+++ /dev/null
@@ -1,169 +0,0 @@
-Linux power supply class
-========================
-
-Synopsis
-~~~~~~~~
-Power supply class used to represent battery, UPS, AC or DC power supply
-properties to user-space.
-
-It defines core set of attributes, which should be applicable to (almost)
-every power supply out there. Attributes are available via sysfs and uevent
-interfaces.
-
-Each attribute has well defined meaning, up to unit of measure used. While
-the attributes provided are believed to be universally applicable to any
-power supply, specific monitoring hardware may not be able to provide them
-all, so any of them may be skipped.
-
-Power supply class is extensible, and allows to define drivers own attributes.
-The core attribute set is subject to the standard Linux evolution (i.e.
-if it will be found that some attribute is applicable to many power supply
-types or their drivers, it can be added to the core set).
-
-It also integrates with LED framework, for the purpose of providing
-typically expected feedback of battery charging/fully charged status and
-AC/USB power supply online status. (Note that specific details of the
-indication (including whether to use it at all) are fully controllable by
-user and/or specific machine defaults, per design principles of LED
-framework).
-
-
-Attributes/properties
-~~~~~~~~~~~~~~~~~~~~~
-Power supply class has predefined set of attributes, this eliminates code
-duplication across drivers. Power supply class insist on reusing its
-predefined attributes *and* their units.
-
-So, userspace gets predictable set of attributes and their units for any
-kind of power supply, and can process/present them to a user in consistent
-manner. Results for different power supplies and machines are also directly
-comparable.
-
-See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
-example how to declare and handle attributes.
-
-
-Units
-~~~~~
-Quoting include/linux/power_supply.h:
-
-  All voltages, currents, charges, energies, time and temperatures in µV,
-  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
-  stated. It's driver's job to convert its raw values to units in which
-  this class operates.
-
-
-Attributes/properties detailed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
-~                                                                       ~
-~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
-~ of battery, this class distinguish these terms. Don't mix them!       ~
-~                                                                       ~
-~ CHARGE_* attributes represents capacity in µAh only.                  ~
-~ ENERGY_* attributes represents capacity in µWh only.                  ~
-~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
-~                                                                       ~
-~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
-
-Postfixes:
-_AVG - *hardware* averaged value, use it if your hardware is really able to
-report averaged values.
-_NOW - momentary/instantaneous values.
-
-STATUS - this attribute represents operating status (charging, full,
-discharging (i.e. powering a load), etc.). This corresponds to
-BATTERY_STATUS_* values, as defined in battery.h.
-
-HEALTH - represents health of the battery, values corresponds to
-POWER_SUPPLY_HEALTH_*, defined in battery.h.
-
-VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
-minimal power supply voltages. Maximal/minimal means values of voltages
-when battery considered "full"/"empty" at normal conditions. Yes, there is
-no direct relation between voltage and battery capacity, but some dumb
-batteries use voltage for very approximated calculation of capacity.
-Battery driver also can use this attribute just to inform userspace
-about maximal and minimal voltage thresholds of a given battery.
-
-VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
-these ones should be used if hardware could only guess (measure and
-retain) the thresholds of a given power supply.
-
-CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
-battery considered full/empty.
-
-ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
-
-CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
-of charge when battery became full/empty". It also could mean "value of
-charge when battery considered full/empty at given conditions (temperature,
-age)". I.e. these attributes represents real thresholds, not design values.
-
-ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
-
-CAPACITY - capacity in percents.
-
-TEMP - temperature of the power supply.
-TEMP_AMBIENT - ambient temperature.
-
-TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
-while battery powers a load)
-TIME_TO_FULL - seconds left for battery to be considered full (i.e.
-while battery is charging)
-
-
-Battery <-> external power supply interaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Often power supplies are acting as supplies and supplicants at the same
-time. Batteries are good example. So, batteries usually care if they're
-externally powered or not.
-
-For that case, power supply class implements notification mechanism for
-batteries.
-
-External power supply (AC) lists supplicants (batteries) names in
-"supplied_to" struct member, and each power_supply_changed() call
-issued by external power supply will notify supplicants via
-external_power_changed callback.
-
-
-QA
-~~
-Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
-A: If you cannot find attribute suitable for your driver needs, feel free
-   to add it and send patch along with your driver.
-
-   The attributes available currently are the ones currently provided by the
-   drivers written.
-
-   Good candidates to add in future: model/part#, cycle_time, manufacturer,
-   etc.
-
-
-Q: I have some very specific attribute (e.g. battery color), should I add
-   this attribute to standard ones?
-A: Most likely, no. Such attribute can be placed in the driver itself, if
-   it is useful. Of course, if the attribute in question applicable to
-   large set of batteries, provided by many drivers, and/or comes from
-   some general battery specification/standard, it may be a candidate to
-   be added to the core attribute set.
-
-
-Q: Suppose, my battery monitoring chip/firmware does not provides capacity
-   in percents, but provides charge_{now,full,empty}. Should I calculate
-   percentage capacity manually, inside the driver, and register CAPACITY
-   attribute? The same question about time_to_empty/time_to_full.
-A: Most likely, no. This class is designed to export properties which are
-   directly measurable by the specific hardware available.
-
-   Inferring not available properties using some heuristics or mathematical
-   model is not subject of work for a battery driver. Such functionality
-   should be factored out, and in fact, apm_power, the driver to serve
-   legacy APM API on top of power supply class, uses a simple heuristic of
-   approximating remaining battery capacity based on its charge, current,
-   voltage and so on. But full-fledged battery model is likely not subject
-   for kernel at all, as it would require floating point calculation to deal
-   with things like differential equations and Kalman filters. This is
-   better be handled by batteryd/libbattery, yet to be written.
--- linux-2.6.25-rc3-git6.orig/arch/x86/Kconfig
+++ linux-2.6.25-rc3-git6/arch/x86/Kconfig
@@ -1261,7 +1261,7 @@ menuconfig APM
 	  machines with more than one CPU.
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- linux-2.6.25-rc3-git6.orig/kernel/power/Kconfig
+++ linux-2.6.25-rc3-git6/kernel/power/Kconfig
@@ -190,7 +190,7 @@ config APM_EMULATION
 	  notification of APM "events" (e.g. battery status change).
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- linux-2.6.25-rc3-git6.orig/Documentation/kernel-parameters.txt
+++ linux-2.6.25-rc3-git6/Documentation/kernel-parameters.txt
@@ -138,7 +138,7 @@ and is between 256 and 4096 characters. 
 			strict -- Be less tolerant of platforms that are not
 				strictly ACPI specification compliant.
 
-			See also Documentation/pm.txt, pci=noacpi
+			See also Documentation/power/pm.txt, pci=noacpi
 
 	acpi_apic_instance=	[ACPI, IOAPIC]
 			Format: <int>
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc/power: move power-related files to Documentation/power/

[Rafael J. Wysocki]

On Tuesday, 4 of March 2008, Randy Dunlap wrote:
> From: Randy Dunlap <randy.dunlap@oracle.com>
> 
> 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>

ACK in general, although some of these files look pretty old ...

Len, can you pick it up, please?

Thanks,
Rafael

> ---
>  Documentation/00-INDEX                     |    4 
>  Documentation/kernel-parameters.txt        |    2 
>  Documentation/pm.txt                       |  257 -------------------
>  Documentation/pm_qos_interface.txt         |   59 ----
>  Documentation/power/00-INDEX               |    6 
>  Documentation/power/pm.txt                 |  257 +++++++++++++++++++
>  Documentation/power/pm_qos_interface.txt   |   59 ++++
>  Documentation/power/power_supply_class.txt |  169 ++++++++++++
>  Documentation/power_supply_class.txt       |  169 ------------
>  arch/x86/Kconfig                           |    2 
>  kernel/power/Kconfig                       |    2 
>  11 files changed, 494 insertions(+), 492 deletions(-)
> 
> --- linux-2.6.25-rc3-git6.orig/Documentation/00-INDEX
> +++ linux-2.6.25-rc3-git6/Documentation/00-INDEX
> @@ -303,12 +303,8 @@ pcmcia/
>  	- info on the Linux PCMCIA driver.
>  pi-futex.txt
>  	- documentation on lightweight PI-futexes.
> -pm.txt
> -	- info on Linux power management support.
>  pnp.txt
>  	- Linux Plug and Play documentation.
> -power_supply_class.txt
> -	- Tells userspace about battery, UPS, AC or DC power supply properties
>  power/
>  	- directory with info on Linux PCI power management.
>  powerpc/
> --- linux-2.6.25-rc3-git6.orig/Documentation/power/00-INDEX
> +++ linux-2.6.25-rc3-git6/Documentation/power/00-INDEX
> @@ -14,6 +14,12 @@ notifiers.txt
>  	- Registering suspend notifiers in device drivers
>  pci.txt
>  	- How the PCI Subsystem Does Power Management
> +pm.txt
> +	- info on Linux power management support.
> +pm_qos_interface.txt
> +	- info on Linux PM Quality of Service interface
> +power_supply_class.txt
> +	- Tells userspace about battery, UPS, AC or DC power supply properties
>  s2ram.txt
>  	- How to get suspend to ram working (and debug it when it isn't)
>  states.txt
> --- linux-2.6.25-rc3-git6.orig/Documentation/pm.txt
> +++ /dev/null
> @@ -1,257 +0,0 @@
> -               Linux Power Management Support
> -
> -This document briefly describes how to use power management with your
> -Linux system and how to add power management support to Linux drivers.
> -
> -APM or ACPI?
> -------------
> -If you have a relatively recent x86 mobile, desktop, or server system,
> -odds are it supports either Advanced Power Management (APM) or
> -Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
> -of the two technologies and puts power management in the hands of the
> -operating system, allowing for more intelligent power management than
> -is possible with BIOS controlled APM.
> -
> -The best way to determine which, if either, your system supports is to
> -build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
> -enabled by default).  If a working ACPI implementation is found, the
> -ACPI driver will override and disable APM, otherwise the APM driver
> -will be used.
> -
> -No, sorry, you cannot have both ACPI and APM enabled and running at
> -once.  Some people with broken ACPI or broken APM implementations
> -would like to use both to get a full set of working features, but you
> -simply cannot mix and match the two.  Only one power management
> -interface can be in control of the machine at once.  Think about it..
> -
> -User-space Daemons
> -------------------
> -Both APM and ACPI rely on user-space daemons, apmd and acpid
> -respectively, to be completely functional.  Obtain both of these
> -daemons from your Linux distribution or from the Internet (see below)
> -and be sure that they are started sometime in the system boot process.
> -Go ahead and start both.  If ACPI or APM is not available on your
> -system the associated daemon will exit gracefully.
> -
> -  apmd:   http://worldvisions.ca/~apenwarr/apmd/
> -  acpid:  http://acpid.sf.net/
> -
> -Driver Interface -- OBSOLETE, DO NOT USE!
> -----------------*************************
> -
> -Note: pm_register(), pm_access(), pm_dev_idle() and friends are
> -obsolete. Please do not use them. Instead you should properly hook
> -your driver into the driver model, and use its suspend()/resume()
> -callbacks to do this kind of stuff.
> -
> -If you are writing a new driver or maintaining an old driver, it
> -should include power management support.  Without power management
> -support, a single driver may prevent a system with power management
> -capabilities from ever being able to suspend (safely).
> -
> -Overview:
> -1) Register each instance of a device with "pm_register"
> -2) Call "pm_access" before accessing the hardware.
> -   (this will ensure that the hardware is awake and ready)
> -3) Your "pm_callback" is called before going into a
> -   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
> -   from a suspend.
> -4) Call "pm_dev_idle" when the device is not being used
> -   (optional but will improve device idle detection)
> -5) When unloaded, unregister the device with "pm_unregister"
> -
> -/*
> - * Description: Register a device with the power-management subsystem
> - *
> - * Parameters:
> - *   type - device type (PCI device, system device, ...)
> - *   id - instance number or unique identifier
> - *   cback - request handler callback (suspend, resume, ...)
> - *
> - * Returns: Registered PM device or NULL on error
> - *
> - * Examples:
> - *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
> - *
> - *   struct pci_dev *pci_dev = pci_find_dev(...);
> - *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
> - */
> -struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
> -
> -/*
> - * Description: Unregister a device with the power management subsystem
> - *
> - * Parameters:
> - *   dev - PM device previously returned from pm_register
> - */
> -void pm_unregister(struct pm_dev *dev);
> -
> -/*
> - * Description: Unregister all devices with a matching callback function
> - *
> - * Parameters:
> - *   cback - previously registered request callback
> - *
> - * Notes: Provided for easier porting from old APM interface
> - */
> -void pm_unregister_all(pm_callback cback);
> -
> -/*
> - * Power management request callback
> - *
> - * Parameters:
> - *   dev - PM device previously returned from pm_register
> - *   rqst - request type
> - *   data - data, if any, associated with the request
> - *
> - * Returns: 0 if the request is successful
> - *          EINVAL if the request is not supported
> - *          EBUSY if the device is now busy and cannot handle the request
> - *          ENOMEM if the device was unable to handle the request due to memory
> - *          
> - * Details: The device request callback will be called before the
> - *          device/system enters a suspend state (ACPI D1-D3) or
> - *          or after the device/system resumes from suspend (ACPI D0).
> - *          For PM_SUSPEND, the ACPI D-state being entered is passed
> - *          as the "data" argument to the callback.  The device
> - *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
> - *          device context when the request callback is called.
> - *
> - *          Once a driver returns 0 (success) from a suspend
> - *          request, it should not process any further requests or
> - *          access the device hardware until a call to "pm_access" is made.
> - */
> -typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
> -
> -Driver Details
> ---------------
> -This is just a quick Q&A as a stopgap until a real driver writers'
> -power management guide is available.
> -
> -Q: When is a device suspended?
> -
> -Devices can be suspended based on direct user request (eg. laptop lid
> -closes), system power policy (eg.  sleep after 30 minutes of console
> -inactivity), or device power policy (eg. power down device after 5
> -minutes of inactivity)
> -
> -Q: Must a driver honor a suspend request?
> -
> -No, a driver can return -EBUSY from a suspend request and this
> -will stop the system from suspending.  When a suspend request
> -fails, all suspended devices are resumed and the system continues
> -to run.  Suspend can be retried at a later time.
> -
> -Q: Can the driver block suspend/resume requests?
> -
> -Yes, a driver can delay its return from a suspend or resume
> -request until the device is ready to handle requests.  It
> -is advantageous to return as quickly as possible from a
> -request as suspend/resume are done serially.
> -
> -Q: What context is a suspend/resume initiated from?
> -
> -A suspend or resume is initiated from a kernel thread context.
> -It is safe to block, allocate memory, initiate requests
> -or anything else you can do within the kernel.
> -
> -Q: Will requests continue to arrive after a suspend?
> -
> -Possibly.  It is the driver's responsibility to queue(*),
> -fail, or drop any requests that arrive after returning
> -success to a suspend request.  It is important that the
> -driver not access its device until after it receives
> -a resume request as the device's bus may no longer
> -be active.
> -
> -(*) If a driver queues requests for processing after
> -    resume be aware that the device, network, etc.
> -    might be in a different state than at suspend time.
> -    It's probably better to drop requests unless
> -    the driver is a storage device.
> -
> -Q: Do I have to manage bus-specific power management registers
> -
> -No.  It is the responsibility of the bus driver to manage
> -PCI, USB, etc. power management registers.  The bus driver
> -or the power management subsystem will also enable any
> -wake-on functionality that the device has.
> -
> -Q: So, really, what do I need to do to support suspend/resume?
> -
> -You need to save any device context that would
> -be lost if the device was powered off and then restore
> -it at resume time.  When ACPI is active, there are
> -three levels of device suspend states; D1, D2, and D3.
> -(The suspend state is passed as the "data" argument
> -to the device callback.)  With D3, the device is powered
> -off and loses all context, D1 and D2 are shallower power
> -states and require less device context to be saved.  To
> -play it safe, just save everything at suspend and restore
> -everything at resume.
> -
> -Q: Where do I store device context for suspend?
> -
> -Anywhere in memory, kmalloc a buffer or store it
> -in the device descriptor.  You are guaranteed that the
> -contents of memory will be restored and accessible
> -before resume, even when the system suspends to disk.
> -
> -Q: What do I need to do for ACPI vs. APM vs. etc?
> -
> -Drivers need not be aware of the specific power management
> -technology that is active.  They just need to be aware
> -of when the overlying power management system requests
> -that they suspend or resume.
> -
> -Q: What about device dependencies?
> -
> -When a driver registers a device, the power management
> -subsystem uses the information provided to build a
> -tree of device dependencies (eg. USB device X is on
> -USB controller Y which is on PCI bus Z)  When power
> -management wants to suspend a device, it first sends
> -a suspend request to its driver, then the bus driver,
> -and so on up to the system bus.  Device resumes
> -proceed in the opposite direction.
> -
> -Q: Who do I contact for additional information about
> -   enabling power management for my specific driver/device?
> -
> -ACPI Development mailing list: linux-acpi@vger.kernel.org
> -
> -System Interface -- OBSOLETE, DO NOT USE!
> -----------------*************************
> -If you are providing new power management support to Linux (ie.
> -adding support for something like APM or ACPI), you should
> -communicate with drivers through the existing generic power
> -management interface.
> -
> -/*
> - * Send a request to all devices
> - *
> - * Parameters:
> - *   rqst - request type
> - *   data - data, if any, associated with the request
> - *
> - * Returns: 0 if the request is successful
> - *          See "pm_callback" return for errors
> - *
> - * Details: Walk list of registered devices and call pm_send
> - *          for each until complete or an error is encountered.
> - *          If an error is encountered for a suspend request,
> - *          return all devices to the state they were in before
> - *          the suspend request.
> - */
> -int pm_send_all(pm_request_t rqst, void *data);
> -
> -/*
> - * Find a matching device
> - *
> - * Parameters:
> - *   type - device type (PCI device, system device, or 0 to match all devices)
> - *   from - previous match or NULL to start from the beginning
> - *
> - * Returns: Matching device or NULL if none found
> - */
> -struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
> --- /dev/null
> +++ linux-2.6.25-rc3-git6/Documentation/power/pm.txt
> @@ -0,0 +1,257 @@
> +               Linux Power Management Support
> +
> +This document briefly describes how to use power management with your
> +Linux system and how to add power management support to Linux drivers.
> +
> +APM or ACPI?
> +------------
> +If you have a relatively recent x86 mobile, desktop, or server system,
> +odds are it supports either Advanced Power Management (APM) or
> +Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
> +of the two technologies and puts power management in the hands of the
> +operating system, allowing for more intelligent power management than
> +is possible with BIOS controlled APM.
> +
> +The best way to determine which, if either, your system supports is to
> +build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
> +enabled by default).  If a working ACPI implementation is found, the
> +ACPI driver will override and disable APM, otherwise the APM driver
> +will be used.
> +
> +No, sorry, you cannot have both ACPI and APM enabled and running at
> +once.  Some people with broken ACPI or broken APM implementations
> +would like to use both to get a full set of working features, but you
> +simply cannot mix and match the two.  Only one power management
> +interface can be in control of the machine at once.  Think about it..
> +
> +User-space Daemons
> +------------------
> +Both APM and ACPI rely on user-space daemons, apmd and acpid
> +respectively, to be completely functional.  Obtain both of these
> +daemons from your Linux distribution or from the Internet (see below)
> +and be sure that they are started sometime in the system boot process.
> +Go ahead and start both.  If ACPI or APM is not available on your
> +system the associated daemon will exit gracefully.
> +
> +  apmd:   http://worldvisions.ca/~apenwarr/apmd/
> +  acpid:  http://acpid.sf.net/
> +
> +Driver Interface -- OBSOLETE, DO NOT USE!
> +----------------*************************
> +
> +Note: pm_register(), pm_access(), pm_dev_idle() and friends are
> +obsolete. Please do not use them. Instead you should properly hook
> +your driver into the driver model, and use its suspend()/resume()
> +callbacks to do this kind of stuff.
> +
> +If you are writing a new driver or maintaining an old driver, it
> +should include power management support.  Without power management
> +support, a single driver may prevent a system with power management
> +capabilities from ever being able to suspend (safely).
> +
> +Overview:
> +1) Register each instance of a device with "pm_register"
> +2) Call "pm_access" before accessing the hardware.
> +   (this will ensure that the hardware is awake and ready)
> +3) Your "pm_callback" is called before going into a
> +   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
> +   from a suspend.
> +4) Call "pm_dev_idle" when the device is not being used
> +   (optional but will improve device idle detection)
> +5) When unloaded, unregister the device with "pm_unregister"
> +
> +/*
> + * Description: Register a device with the power-management subsystem
> + *
> + * Parameters:
> + *   type - device type (PCI device, system device, ...)
> + *   id - instance number or unique identifier
> + *   cback - request handler callback (suspend, resume, ...)
> + *
> + * Returns: Registered PM device or NULL on error
> + *
> + * Examples:
> + *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
> + *
> + *   struct pci_dev *pci_dev = pci_find_dev(...);
> + *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
> + */
> +struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
> +
> +/*
> + * Description: Unregister a device with the power management subsystem
> + *
> + * Parameters:
> + *   dev - PM device previously returned from pm_register
> + */
> +void pm_unregister(struct pm_dev *dev);
> +
> +/*
> + * Description: Unregister all devices with a matching callback function
> + *
> + * Parameters:
> + *   cback - previously registered request callback
> + *
> + * Notes: Provided for easier porting from old APM interface
> + */
> +void pm_unregister_all(pm_callback cback);
> +
> +/*
> + * Power management request callback
> + *
> + * Parameters:
> + *   dev - PM device previously returned from pm_register
> + *   rqst - request type
> + *   data - data, if any, associated with the request
> + *
> + * Returns: 0 if the request is successful
> + *          EINVAL if the request is not supported
> + *          EBUSY if the device is now busy and cannot handle the request
> + *          ENOMEM if the device was unable to handle the request due to memory
> + *
> + * Details: The device request callback will be called before the
> + *          device/system enters a suspend state (ACPI D1-D3) or
> + *          or after the device/system resumes from suspend (ACPI D0).
> + *          For PM_SUSPEND, the ACPI D-state being entered is passed
> + *          as the "data" argument to the callback.  The device
> + *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
> + *          device context when the request callback is called.
> + *
> + *          Once a driver returns 0 (success) from a suspend
> + *          request, it should not process any further requests or
> + *          access the device hardware until a call to "pm_access" is made.
> + */
> +typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
> +
> +Driver Details
> +--------------
> +This is just a quick Q&A as a stopgap until a real driver writers'
> +power management guide is available.
> +
> +Q: When is a device suspended?
> +
> +Devices can be suspended based on direct user request (eg. laptop lid
> +closes), system power policy (eg.  sleep after 30 minutes of console
> +inactivity), or device power policy (eg. power down device after 5
> +minutes of inactivity)
> +
> +Q: Must a driver honor a suspend request?
> +
> +No, a driver can return -EBUSY from a suspend request and this
> +will stop the system from suspending.  When a suspend request
> +fails, all suspended devices are resumed and the system continues
> +to run.  Suspend can be retried at a later time.
> +
> +Q: Can the driver block suspend/resume requests?
> +
> +Yes, a driver can delay its return from a suspend or resume
> +request until the device is ready to handle requests.  It
> +is advantageous to return as quickly as possible from a
> +request as suspend/resume are done serially.
> +
> +Q: What context is a suspend/resume initiated from?
> +
> +A suspend or resume is initiated from a kernel thread context.
> +It is safe to block, allocate memory, initiate requests
> +or anything else you can do within the kernel.
> +
> +Q: Will requests continue to arrive after a suspend?
> +
> +Possibly.  It is the driver's responsibility to queue(*),
> +fail, or drop any requests that arrive after returning
> +success to a suspend request.  It is important that the
> +driver not access its device until after it receives
> +a resume request as the device's bus may no longer
> +be active.
> +
> +(*) If a driver queues requests for processing after
> +    resume be aware that the device, network, etc.
> +    might be in a different state than at suspend time.
> +    It's probably better to drop requests unless
> +    the driver is a storage device.
> +
> +Q: Do I have to manage bus-specific power management registers
> +
> +No.  It is the responsibility of the bus driver to manage
> +PCI, USB, etc. power management registers.  The bus driver
> +or the power management subsystem will also enable any
> +wake-on functionality that the device has.
> +
> +Q: So, really, what do I need to do to support suspend/resume?
> +
> +You need to save any device context that would
> +be lost if the device was powered off and then restore
> +it at resume time.  When ACPI is active, there are
> +three levels of device suspend states; D1, D2, and D3.
> +(The suspend state is passed as the "data" argument
> +to the device callback.)  With D3, the device is powered
> +off and loses all context, D1 and D2 are shallower power
> +states and require less device context to be saved.  To
> +play it safe, just save everything at suspend and restore
> +everything at resume.
> +
> +Q: Where do I store device context for suspend?
> +
> +Anywhere in memory, kmalloc a buffer or store it
> +in the device descriptor.  You are guaranteed that the
> +contents of memory will be restored and accessible
> +before resume, even when the system suspends to disk.
> +
> +Q: What do I need to do for ACPI vs. APM vs. etc?
> +
> +Drivers need not be aware of the specific power management
> +technology that is active.  They just need to be aware
> +of when the overlying power management system requests
> +that they suspend or resume.
> +
> +Q: What about device dependencies?
> +
> +When a driver registers a device, the power management
> +subsystem uses the information provided to build a
> +tree of device dependencies (eg. USB device X is on
> +USB controller Y which is on PCI bus Z)  When power
> +management wants to suspend a device, it first sends
> +a suspend request to its driver, then the bus driver,
> +and so on up to the system bus.  Device resumes
> +proceed in the opposite direction.
> +
> +Q: Who do I contact for additional information about
> +   enabling power management for my specific driver/device?
> +
> +ACPI Development mailing list: linux-acpi@vger.kernel.org
> +
> +System Interface -- OBSOLETE, DO NOT USE!
> +----------------*************************
> +If you are providing new power management support to Linux (ie.
> +adding support for something like APM or ACPI), you should
> +communicate with drivers through the existing generic power
> +management interface.
> +
> +/*
> + * Send a request to all devices
> + *
> + * Parameters:
> + *   rqst - request type
> + *   data - data, if any, associated with the request
> + *
> + * Returns: 0 if the request is successful
> + *          See "pm_callback" return for errors
> + *
> + * Details: Walk list of registered devices and call pm_send
> + *          for each until complete or an error is encountered.
> + *          If an error is encountered for a suspend request,
> + *          return all devices to the state they were in before
> + *          the suspend request.
> + */
> +int pm_send_all(pm_request_t rqst, void *data);
> +
> +/*
> + * Find a matching device
> + *
> + * Parameters:
> + *   type - device type (PCI device, system device, or 0 to match all devices)
> + *   from - previous match or NULL to start from the beginning
> + *
> + * Returns: Matching device or NULL if none found
> + */
> +struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
> --- linux-2.6.25-rc3-git6.orig/Documentation/pm_qos_interface.txt
> +++ /dev/null
> @@ -1,59 +0,0 @@
> -PM quality of Service interface.
> -
> -This interface provides a kernel and user mode interface for registering
> -performance expectations by drivers, subsystems and user space applications on
> -one of the parameters.
> -
> -Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
> -initial set of pm_qos parameters.
> -
> -The infrastructure exposes multiple misc device nodes one per implemented
> -parameter.  The set of parameters implement is defined by pm_qos_power_init()
> -and pm_qos_params.h.  This is done because having the available parameters
> -being runtime configurable or changeable from a driver was seen as too easy to
> -abuse.
> -
> -For each parameter a list of performance requirements is maintained along with
> -an aggregated target value.  The aggregated target value is updated with
> -changes to the requirement list or elements of the list.  Typically the
> -aggregated target value is simply the max or min of the requirement values held
> -in the parameter list elements.
> -
> -From kernel mode the use of this interface is simple:
> -pm_qos_add_requirement(param_id, name, target_value):
> -Will insert a named element in the list for that identified PM_QOS parameter
> -with the target value.  Upon change to this list the new target is recomputed
> -and any registered notifiers are called only if the target value is now
> -different.
> -
> -pm_qos_update_requirement(param_id, name, new_target_value):
> -Will search the list identified by the param_id for the named list element and
> -then update its target value, calling the notification tree if the aggregated
> -target is changed.  with that name is already registered.
> -
> -pm_qos_remove_requirement(param_id, name):
> -Will search the identified list for the named element and remove it, after
> -removal it will update the aggregate target and call the notification tree if
> -the target was changed as a result of removing the named requirement.
> -
> -
> -From user mode:
> -Only processes can register a pm_qos requirement.  To provide for automatic
> -cleanup for process the interface requires the process to register its
> -parameter requirements in the following way:
> -
> -To register the default pm_qos target for the specific parameter, the process
> -must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
> -
> -As long as the device node is held open that process has a registered
> -requirement on the parameter.  The name of the requirement is "process_<PID>"
> -derived from the current->pid from within the open system call.
> -
> -To change the requested target value the process needs to write a s32 value to
> -the open device node.  This translates to a pm_qos_update_requirement call.
> -
> -To remove the user mode request for a target value simply close the device
> -node.
> -
> -
> -
> --- /dev/null
> +++ linux-2.6.25-rc3-git6/Documentation/power/pm_qos_interface.txt
> @@ -0,0 +1,59 @@
> +PM quality of Service interface.
> +
> +This interface provides a kernel and user mode interface for registering
> +performance expectations by drivers, subsystems and user space applications on
> +one of the parameters.
> +
> +Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
> +initial set of pm_qos parameters.
> +
> +The infrastructure exposes multiple misc device nodes one per implemented
> +parameter.  The set of parameters implement is defined by pm_qos_power_init()
> +and pm_qos_params.h.  This is done because having the available parameters
> +being runtime configurable or changeable from a driver was seen as too easy to
> +abuse.
> +
> +For each parameter a list of performance requirements is maintained along with
> +an aggregated target value.  The aggregated target value is updated with
> +changes to the requirement list or elements of the list.  Typically the
> +aggregated target value is simply the max or min of the requirement values held
> +in the parameter list elements.
> +
> +From kernel mode the use of this interface is simple:
> +pm_qos_add_requirement(param_id, name, target_value):
> +Will insert a named element in the list for that identified PM_QOS parameter
> +with the target value.  Upon change to this list the new target is recomputed
> +and any registered notifiers are called only if the target value is now
> +different.
> +
> +pm_qos_update_requirement(param_id, name, new_target_value):
> +Will search the list identified by the param_id for the named list element and
> +then update its target value, calling the notification tree if the aggregated
> +target is changed.  with that name is already registered.
> +
> +pm_qos_remove_requirement(param_id, name):
> +Will search the identified list for the named element and remove it, after
> +removal it will update the aggregate target and call the notification tree if
> +the target was changed as a result of removing the named requirement.
> +
> +
> +From user mode:
> +Only processes can register a pm_qos requirement.  To provide for automatic
> +cleanup for process the interface requires the process to register its
> +parameter requirements in the following way:
> +
> +To register the default pm_qos target for the specific parameter, the process
> +must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
> +
> +As long as the device node is held open that process has a registered
> +requirement on the parameter.  The name of the requirement is "process_<PID>"
> +derived from the current->pid from within the open system call.
> +
> +To change the requested target value the process needs to write a s32 value to
> +the open device node.  This translates to a pm_qos_update_requirement call.
> +
> +To remove the user mode request for a target value simply close the device
> +node.
> +
> +
> +
> --- /dev/null
> +++ linux-2.6.25-rc3-git6/Documentation/power/power_supply_class.txt
> @@ -0,0 +1,169 @@
> +Linux power supply class
> +========================
> +
> +Synopsis
> +~~~~~~~~
> +Power supply class used to represent battery, UPS, AC or DC power supply
> +properties to user-space.
> +
> +It defines core set of attributes, which should be applicable to (almost)
> +every power supply out there. Attributes are available via sysfs and uevent
> +interfaces.
> +
> +Each attribute has well defined meaning, up to unit of measure used. While
> +the attributes provided are believed to be universally applicable to any
> +power supply, specific monitoring hardware may not be able to provide them
> +all, so any of them may be skipped.
> +
> +Power supply class is extensible, and allows to define drivers own attributes.
> +The core attribute set is subject to the standard Linux evolution (i.e.
> +if it will be found that some attribute is applicable to many power supply
> +types or their drivers, it can be added to the core set).
> +
> +It also integrates with LED framework, for the purpose of providing
> +typically expected feedback of battery charging/fully charged status and
> +AC/USB power supply online status. (Note that specific details of the
> +indication (including whether to use it at all) are fully controllable by
> +user and/or specific machine defaults, per design principles of LED
> +framework).
> +
> +
> +Attributes/properties
> +~~~~~~~~~~~~~~~~~~~~~
> +Power supply class has predefined set of attributes, this eliminates code
> +duplication across drivers. Power supply class insist on reusing its
> +predefined attributes *and* their units.
> +
> +So, userspace gets predictable set of attributes and their units for any
> +kind of power supply, and can process/present them to a user in consistent
> +manner. Results for different power supplies and machines are also directly
> +comparable.
> +
> +See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
> +example how to declare and handle attributes.
> +
> +
> +Units
> +~~~~~
> +Quoting include/linux/power_supply.h:
> +
> +  All voltages, currents, charges, energies, time and temperatures in µV,
> +  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
> +  stated. It's driver's job to convert its raw values to units in which
> +  this class operates.
> +
> +
> +Attributes/properties detailed
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
> +~                                                                       ~
> +~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
> +~ of battery, this class distinguish these terms. Don't mix them!       ~
> +~                                                                       ~
> +~ CHARGE_* attributes represents capacity in µAh only.                  ~
> +~ ENERGY_* attributes represents capacity in µWh only.                  ~
> +~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
> +~                                                                       ~
> +~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
> +
> +Postfixes:
> +_AVG - *hardware* averaged value, use it if your hardware is really able to
> +report averaged values.
> +_NOW - momentary/instantaneous values.
> +
> +STATUS - this attribute represents operating status (charging, full,
> +discharging (i.e. powering a load), etc.). This corresponds to
> +BATTERY_STATUS_* values, as defined in battery.h.
> +
> +HEALTH - represents health of the battery, values corresponds to
> +POWER_SUPPLY_HEALTH_*, defined in battery.h.
> +
> +VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
> +minimal power supply voltages. Maximal/minimal means values of voltages
> +when battery considered "full"/"empty" at normal conditions. Yes, there is
> +no direct relation between voltage and battery capacity, but some dumb
> +batteries use voltage for very approximated calculation of capacity.
> +Battery driver also can use this attribute just to inform userspace
> +about maximal and minimal voltage thresholds of a given battery.
> +
> +VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
> +these ones should be used if hardware could only guess (measure and
> +retain) the thresholds of a given power supply.
> +
> +CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
> +battery considered full/empty.
> +
> +ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
> +
> +CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
> +of charge when battery became full/empty". It also could mean "value of
> +charge when battery considered full/empty at given conditions (temperature,
> +age)". I.e. these attributes represents real thresholds, not design values.
> +
> +ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
> +
> +CAPACITY - capacity in percents.
> +
> +TEMP - temperature of the power supply.
> +TEMP_AMBIENT - ambient temperature.
> +
> +TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
> +while battery powers a load)
> +TIME_TO_FULL - seconds left for battery to be considered full (i.e.
> +while battery is charging)
> +
> +
> +Battery <-> external power supply interaction
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Often power supplies are acting as supplies and supplicants at the same
> +time. Batteries are good example. So, batteries usually care if they're
> +externally powered or not.
> +
> +For that case, power supply class implements notification mechanism for
> +batteries.
> +
> +External power supply (AC) lists supplicants (batteries) names in
> +"supplied_to" struct member, and each power_supply_changed() call
> +issued by external power supply will notify supplicants via
> +external_power_changed callback.
> +
> +
> +QA
> +~~
> +Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
> +A: If you cannot find attribute suitable for your driver needs, feel free
> +   to add it and send patch along with your driver.
> +
> +   The attributes available currently are the ones currently provided by the
> +   drivers written.
> +
> +   Good candidates to add in future: model/part#, cycle_time, manufacturer,
> +   etc.
> +
> +
> +Q: I have some very specific attribute (e.g. battery color), should I add
> +   this attribute to standard ones?
> +A: Most likely, no. Such attribute can be placed in the driver itself, if
> +   it is useful. Of course, if the attribute in question applicable to
> +   large set of batteries, provided by many drivers, and/or comes from
> +   some general battery specification/standard, it may be a candidate to
> +   be added to the core attribute set.
> +
> +
> +Q: Suppose, my battery monitoring chip/firmware does not provides capacity
> +   in percents, but provides charge_{now,full,empty}. Should I calculate
> +   percentage capacity manually, inside the driver, and register CAPACITY
> +   attribute? The same question about time_to_empty/time_to_full.
> +A: Most likely, no. This class is designed to export properties which are
> +   directly measurable by the specific hardware available.
> +
> +   Inferring not available properties using some heuristics or mathematical
> +   model is not subject of work for a battery driver. Such functionality
> +   should be factored out, and in fact, apm_power, the driver to serve
> +   legacy APM API on top of power supply class, uses a simple heuristic of
> +   approximating remaining battery capacity based on its charge, current,
> +   voltage and so on. But full-fledged battery model is likely not subject
> +   for kernel at all, as it would require floating point calculation to deal
> +   with things like differential equations and Kalman filters. This is
> +   better be handled by batteryd/libbattery, yet to be written.
> --- linux-2.6.25-rc3-git6.orig/Documentation/power_supply_class.txt
> +++ /dev/null
> @@ -1,169 +0,0 @@
> -Linux power supply class
> -========================
> -
> -Synopsis
> -~~~~~~~~
> -Power supply class used to represent battery, UPS, AC or DC power supply
> -properties to user-space.
> -
> -It defines core set of attributes, which should be applicable to (almost)
> -every power supply out there. Attributes are available via sysfs and uevent
> -interfaces.
> -
> -Each attribute has well defined meaning, up to unit of measure used. While
> -the attributes provided are believed to be universally applicable to any
> -power supply, specific monitoring hardware may not be able to provide them
> -all, so any of them may be skipped.
> -
> -Power supply class is extensible, and allows to define drivers own attributes.
> -The core attribute set is subject to the standard Linux evolution (i.e.
> -if it will be found that some attribute is applicable to many power supply
> -types or their drivers, it can be added to the core set).
> -
> -It also integrates with LED framework, for the purpose of providing
> -typically expected feedback of battery charging/fully charged status and
> -AC/USB power supply online status. (Note that specific details of the
> -indication (including whether to use it at all) are fully controllable by
> -user and/or specific machine defaults, per design principles of LED
> -framework).
> -
> -
> -Attributes/properties
> -~~~~~~~~~~~~~~~~~~~~~
> -Power supply class has predefined set of attributes, this eliminates code
> -duplication across drivers. Power supply class insist on reusing its
> -predefined attributes *and* their units.
> -
> -So, userspace gets predictable set of attributes and their units for any
> -kind of power supply, and can process/present them to a user in consistent
> -manner. Results for different power supplies and machines are also directly
> -comparable.
> -
> -See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
> -example how to declare and handle attributes.
> -
> -
> -Units
> -~~~~~
> -Quoting include/linux/power_supply.h:
> -
> -  All voltages, currents, charges, energies, time and temperatures in µV,
> -  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
> -  stated. It's driver's job to convert its raw values to units in which
> -  this class operates.
> -
> -
> -Attributes/properties detailed
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
> -~                                                                       ~
> -~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
> -~ of battery, this class distinguish these terms. Don't mix them!       ~
> -~                                                                       ~
> -~ CHARGE_* attributes represents capacity in µAh only.                  ~
> -~ ENERGY_* attributes represents capacity in µWh only.                  ~
> -~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
> -~                                                                       ~
> -~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
> -
> -Postfixes:
> -_AVG - *hardware* averaged value, use it if your hardware is really able to
> -report averaged values.
> -_NOW - momentary/instantaneous values.
> -
> -STATUS - this attribute represents operating status (charging, full,
> -discharging (i.e. powering a load), etc.). This corresponds to
> -BATTERY_STATUS_* values, as defined in battery.h.
> -
> -HEALTH - represents health of the battery, values corresponds to
> -POWER_SUPPLY_HEALTH_*, defined in battery.h.
> -
> -VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
> -minimal power supply voltages. Maximal/minimal means values of voltages
> -when battery considered "full"/"empty" at normal conditions. Yes, there is
> -no direct relation between voltage and battery capacity, but some dumb
> -batteries use voltage for very approximated calculation of capacity.
> -Battery driver also can use this attribute just to inform userspace
> -about maximal and minimal voltage thresholds of a given battery.
> -
> -VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
> -these ones should be used if hardware could only guess (measure and
> -retain) the thresholds of a given power supply.
> -
> -CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
> -battery considered full/empty.
> -
> -ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
> -
> -CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
> -of charge when battery became full/empty". It also could mean "value of
> -charge when battery considered full/empty at given conditions (temperature,
> -age)". I.e. these attributes represents real thresholds, not design values.
> -
> -ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
> -
> -CAPACITY - capacity in percents.
> -
> -TEMP - temperature of the power supply.
> -TEMP_AMBIENT - ambient temperature.
> -
> -TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
> -while battery powers a load)
> -TIME_TO_FULL - seconds left for battery to be considered full (i.e.
> -while battery is charging)
> -
> -
> -Battery <-> external power supply interaction
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -Often power supplies are acting as supplies and supplicants at the same
> -time. Batteries are good example. So, batteries usually care if they're
> -externally powered or not.
> -
> -For that case, power supply class implements notification mechanism for
> -batteries.
> -
> -External power supply (AC) lists supplicants (batteries) names in
> -"supplied_to" struct member, and each power_supply_changed() call
> -issued by external power supply will notify supplicants via
> -external_power_changed callback.
> -
> -
> -QA
> -~~
> -Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
> -A: If you cannot find attribute suitable for your driver needs, feel free
> -   to add it and send patch along with your driver.
> -
> -   The attributes available currently are the ones currently provided by the
> -   drivers written.
> -
> -   Good candidates to add in future: model/part#, cycle_time, manufacturer,
> -   etc.
> -
> -
> -Q: I have some very specific attribute (e.g. battery color), should I add
> -   this attribute to standard ones?
> -A: Most likely, no. Such attribute can be placed in the driver itself, if
> -   it is useful. Of course, if the attribute in question applicable to
> -   large set of batteries, provided by many drivers, and/or comes from
> -   some general battery specification/standard, it may be a candidate to
> -   be added to the core attribute set.
> -
> -
> -Q: Suppose, my battery monitoring chip/firmware does not provides capacity
> -   in percents, but provides charge_{now,full,empty}. Should I calculate
> -   percentage capacity manually, inside the driver, and register CAPACITY
> -   attribute? The same question about time_to_empty/time_to_full.
> -A: Most likely, no. This class is designed to export properties which are
> -   directly measurable by the specific hardware available.
> -
> -   Inferring not available properties using some heuristics or mathematical
> -   model is not subject of work for a battery driver. Such functionality
> -   should be factored out, and in fact, apm_power, the driver to serve
> -   legacy APM API on top of power supply class, uses a simple heuristic of
> -   approximating remaining battery capacity based on its charge, current,
> -   voltage and so on. But full-fledged battery model is likely not subject
> -   for kernel at all, as it would require floating point calculation to deal
> -   with things like differential equations and Kalman filters. This is
> -   better be handled by batteryd/libbattery, yet to be written.
> --- linux-2.6.25-rc3-git6.orig/arch/x86/Kconfig
> +++ linux-2.6.25-rc3-git6/arch/x86/Kconfig
> @@ -1261,7 +1261,7 @@ menuconfig APM
>  	  machines with more than one CPU.
>  
>  	  In order to use APM, you will need supporting software. For location
> -	  and more information, read <file:Documentation/pm.txt> and the
> +	  and more information, read <file:Documentation/power/pm.txt> and the
>  	  Battery Powered Linux mini-HOWTO, available from
>  	  <http://www.tldp.org/docs.html#howto>.
>  
> --- linux-2.6.25-rc3-git6.orig/kernel/power/Kconfig
> +++ linux-2.6.25-rc3-git6/kernel/power/Kconfig
> @@ -190,7 +190,7 @@ config APM_EMULATION
>  	  notification of APM "events" (e.g. battery status change).
>  
>  	  In order to use APM, you will need supporting software. For location
> -	  and more information, read <file:Documentation/pm.txt> and the
> +	  and more information, read <file:Documentation/power/pm.txt> and the
>  	  Battery Powered Linux mini-HOWTO, available from
>  	  <http://www.tldp.org/docs.html#howto>.
>  
> --- linux-2.6.25-rc3-git6.orig/Documentation/kernel-parameters.txt
> +++ linux-2.6.25-rc3-git6/Documentation/kernel-parameters.txt
> @@ -138,7 +138,7 @@ and is between 256 and 4096 characters. 
>  			strict -- Be less tolerant of platforms that are not
>  				strictly ACPI specification compliant.
>  
> -			See also Documentation/pm.txt, pci=noacpi
> +			See also Documentation/power/pm.txt, pci=noacpi
>  
>  	acpi_apic_instance=	[ACPI, IOAPIC]
>  			Format: <int>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 



-- 
"Premature optimization is the root of all evil." - Donald Knuth
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc/power: move power-related files to Documentation/power/

[Len Brown]

On Tuesday 04 March 2008, Randy Dunlap wrote:
> From: Randy Dunlap <randy.dunlap@oracle.com>
> 
> 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>
> ---
>  Documentation/00-INDEX                     |    4 
>  Documentation/kernel-parameters.txt        |    2 
>  Documentation/pm.txt                       |  257 -------------------
>  Documentation/pm_qos_interface.txt         |   59 ----
>  Documentation/power/00-INDEX               |    6 
>  Documentation/power/pm.txt                 |  257 +++++++++++++++++++
>  Documentation/power/pm_qos_interface.txt   |   59 ++++
>  Documentation/power/power_supply_class.txt |  169 ++++++++++++
>  Documentation/power_supply_class.txt       |  169 ------------
>  arch/x86/Kconfig                           |    2 
>  kernel/power/Kconfig                       |    2 
>  11 files changed, 494 insertions(+), 492 deletions(-)

Randy,
This one doesn't apply any more.
somebody already remove the power_supply_class.txt file?

-Len

Re: [PATCH] doc/power: move power-related files to Documentation/power/

[Randy Dunlap]

On Wed, 12 Mar 2008 02:47:27 -0400 Len Brown wrote:

> On Tuesday 04 March 2008, Randy Dunlap wrote:
> > From: Randy Dunlap <randy.dunlap@oracle.com>
> > 
> > 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>
> > ---
> >  Documentation/00-INDEX                     |    4 
> >  Documentation/kernel-parameters.txt        |    2 
> >  Documentation/pm.txt                       |  257 -------------------
> >  Documentation/pm_qos_interface.txt         |   59 ----
> >  Documentation/power/00-INDEX               |    6 
> >  Documentation/power/pm.txt                 |  257 +++++++++++++++++++
> >  Documentation/power/pm_qos_interface.txt   |   59 ++++
> >  Documentation/power/power_supply_class.txt |  169 ++++++++++++
> >  Documentation/power_supply_class.txt       |  169 ------------
> >  arch/x86/Kconfig                           |    2 
> >  kernel/power/Kconfig                       |    2 
> >  11 files changed, 494 insertions(+), 492 deletions(-)
> 
> Randy,
> This one doesn't apply any more.
> somebody already remove the power_supply_class.txt file?

Don't think so, but I can't reproduce the problem.
What kernel tree are you applying it to?

---
~Randy

Re: [PATCH] doc/power: move power-related files to Documentation/power/

[Len Brown]

On Wednesday 12 March 2008, Randy Dunlap wrote:
> On Wed, 12 Mar 2008 02:47:27 -0400 Len Brown wrote:
> 
> > On Tuesday 04 March 2008, Randy Dunlap wrote:
> > > From: Randy Dunlap <randy.dunlap@oracle.com>
> > > 
> > > 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>
> > > ---
> > >  Documentation/00-INDEX                     |    4 
> > >  Documentation/kernel-parameters.txt        |    2 
> > >  Documentation/pm.txt                       |  257 -------------------
> > >  Documentation/pm_qos_interface.txt         |   59 ----
> > >  Documentation/power/00-INDEX               |    6 
> > >  Documentation/power/pm.txt                 |  257 +++++++++++++++++++
> > >  Documentation/power/pm_qos_interface.txt   |   59 ++++
> > >  Documentation/power/power_supply_class.txt |  169 ++++++++++++
> > >  Documentation/power_supply_class.txt       |  169 ------------
> > >  arch/x86/Kconfig                           |    2 
> > >  kernel/power/Kconfig                       |    2 
> > >  11 files changed, 494 insertions(+), 492 deletions(-)
> > 
> > Randy,
> > This one doesn't apply any more.
> > somebody already remove the power_supply_class.txt file?
> 
> Don't think so, but I can't reproduce the problem.
> What kernel tree are you applying it to?
> 

linus top of tree.  i was wrong that it was already gone,
i guess i assumed that since it had 1 hunk and patch
told me the hunk was reversed i assumed that part
had been applied already.

[lenb@t61 linus (master)]$ patch -Np1 --dry-run <  ~/Documents/doc1.patch
patching file Documentation/00-INDEX
Hunk #1 succeeded at 301 (offset -2 lines).
patching file Documentation/power/00-INDEX
patching file Documentation/pm.txt
patching file Documentation/power/pm.txt
patching file Documentation/pm_qos_interface.txt
patching file Documentation/power/pm_qos_interface.txt
patching file Documentation/power/power_supply_class.txt
patching file Documentation/power_supply_class.txt
Reversed (or previously applied) patch detected!  Skipping patch.
1 out of 1 hunk ignored -- saving rejects to file Documentation/power_supply_class.txt.rej
patching file arch/x86/Kconfig
Hunk #1 succeeded at 1259 (offset -2 lines).
patching file kernel/power/Kconfig
patching file Documentation/kernel-parameters.txt


git-am didn't do any better:

Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all y
Applying doc/power: move power-related files to Documentation/power/
error: patch failed: Documentation/power_supply_class.txt:1
error: Documentation/power_supply_class.txt: patch does not apply
fatal: sha1 information is lacking or useless (Documentation/00-INDEX).
Repository lacks necessary blobs to fall back on 3-way merge.
Cannot fall back to three-way merge.
Patch failed at 0001.
When you have resolved this problem run "git-am -i -3 --resolved".
If you would prefer to skip this patch, instead run "git-am -i -3 --skip".
                 

Re: [linux-pm] [PATCH] doc/power: move power-related files to Documentation/power/

[Randy Dunlap]

On Wed, 12 Mar 2008 16:00:45 -0400 Len Brown wrote:

> linus top of tree.  i was wrong that it was already gone,
> i guess i assumed that since it had 1 hunk and patch
> told me the hunk was reversed i assumed that part
> had been applied already.

Can you try the patch below?
It works_for_me but that doesn't give me lots of confidence.

---
From: Randy Dunlap <randy.dunlap@oracle.com>

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>
---
 Documentation/00-INDEX                     |    4 
 Documentation/kernel-parameters.txt        |    2 
 Documentation/pm.txt                       |  257 -------------------
 Documentation/pm_qos_interface.txt         |   59 ----
 Documentation/power/00-INDEX               |    6 
 Documentation/power/pm.txt                 |  257 +++++++++++++++++++
 Documentation/power/pm_qos_interface.txt   |   59 ++++
 Documentation/power/power_supply_class.txt |  169 ++++++++++++
 Documentation/power_supply_class.txt       |  169 ------------
 arch/x86/Kconfig                           |    2 
 kernel/power/Kconfig                       |    2 
 11 files changed, 494 insertions(+), 492 deletions(-)

--- lin2625-rc5g2-kdoc.orig/Documentation/00-INDEX
+++ lin2625-rc5g2-kdoc/Documentation/00-INDEX
@@ -301,12 +301,8 @@ pcmcia/
 	- info on the Linux PCMCIA driver.
 pi-futex.txt
 	- documentation on lightweight PI-futexes.
-pm.txt
-	- info on Linux power management support.
 pnp.txt
 	- Linux Plug and Play documentation.
-power_supply_class.txt
-	- Tells userspace about battery, UPS, AC or DC power supply properties
 power/
 	- directory with info on Linux PCI power management.
 powerpc/
--- lin2625-rc5g2-kdoc.orig/Documentation/power/00-INDEX
+++ lin2625-rc5g2-kdoc/Documentation/power/00-INDEX
@@ -14,6 +14,12 @@ notifiers.txt
 	- Registering suspend notifiers in device drivers
 pci.txt
 	- How the PCI Subsystem Does Power Management
+pm.txt
+	- info on Linux power management support.
+pm_qos_interface.txt
+	- info on Linux PM Quality of Service interface
+power_supply_class.txt
+	- Tells userspace about battery, UPS, AC or DC power supply properties
 s2ram.txt
 	- How to get suspend to ram working (and debug it when it isn't)
 states.txt
--- lin2625-rc5g2-kdoc.orig/Documentation/pm.txt
+++ /dev/null
@@ -1,257 +0,0 @@
-               Linux Power Management Support
-
-This document briefly describes how to use power management with your
-Linux system and how to add power management support to Linux drivers.
-
-APM or ACPI?
-------------
-If you have a relatively recent x86 mobile, desktop, or server system,
-odds are it supports either Advanced Power Management (APM) or
-Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
-of the two technologies and puts power management in the hands of the
-operating system, allowing for more intelligent power management than
-is possible with BIOS controlled APM.
-
-The best way to determine which, if either, your system supports is to
-build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
-enabled by default).  If a working ACPI implementation is found, the
-ACPI driver will override and disable APM, otherwise the APM driver
-will be used.
-
-No, sorry, you cannot have both ACPI and APM enabled and running at
-once.  Some people with broken ACPI or broken APM implementations
-would like to use both to get a full set of working features, but you
-simply cannot mix and match the two.  Only one power management
-interface can be in control of the machine at once.  Think about it..
-
-User-space Daemons
-------------------
-Both APM and ACPI rely on user-space daemons, apmd and acpid
-respectively, to be completely functional.  Obtain both of these
-daemons from your Linux distribution or from the Internet (see below)
-and be sure that they are started sometime in the system boot process.
-Go ahead and start both.  If ACPI or APM is not available on your
-system the associated daemon will exit gracefully.
-
-  apmd:   http://worldvisions.ca/~apenwarr/apmd/
-  acpid:  http://acpid.sf.net/
-
-Driver Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-
-Note: pm_register(), pm_access(), pm_dev_idle() and friends are
-obsolete. Please do not use them. Instead you should properly hook
-your driver into the driver model, and use its suspend()/resume()
-callbacks to do this kind of stuff.
-
-If you are writing a new driver or maintaining an old driver, it
-should include power management support.  Without power management
-support, a single driver may prevent a system with power management
-capabilities from ever being able to suspend (safely).
-
-Overview:
-1) Register each instance of a device with "pm_register"
-2) Call "pm_access" before accessing the hardware.
-   (this will ensure that the hardware is awake and ready)
-3) Your "pm_callback" is called before going into a
-   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
-   from a suspend.
-4) Call "pm_dev_idle" when the device is not being used
-   (optional but will improve device idle detection)
-5) When unloaded, unregister the device with "pm_unregister"
-
-/*
- * Description: Register a device with the power-management subsystem
- *
- * Parameters:
- *   type - device type (PCI device, system device, ...)
- *   id - instance number or unique identifier
- *   cback - request handler callback (suspend, resume, ...)
- *
- * Returns: Registered PM device or NULL on error
- *
- * Examples:
- *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
- *
- *   struct pci_dev *pci_dev = pci_find_dev(...);
- *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
- */
-struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
-
-/*
- * Description: Unregister a device with the power management subsystem
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- */
-void pm_unregister(struct pm_dev *dev);
-
-/*
- * Description: Unregister all devices with a matching callback function
- *
- * Parameters:
- *   cback - previously registered request callback
- *
- * Notes: Provided for easier porting from old APM interface
- */
-void pm_unregister_all(pm_callback cback);
-
-/*
- * Power management request callback
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          EINVAL if the request is not supported
- *          EBUSY if the device is now busy and cannot handle the request
- *          ENOMEM if the device was unable to handle the request due to memory
- *          
- * Details: The device request callback will be called before the
- *          device/system enters a suspend state (ACPI D1-D3) or
- *          or after the device/system resumes from suspend (ACPI D0).
- *          For PM_SUSPEND, the ACPI D-state being entered is passed
- *          as the "data" argument to the callback.  The device
- *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
- *          device context when the request callback is called.
- *
- *          Once a driver returns 0 (success) from a suspend
- *          request, it should not process any further requests or
- *          access the device hardware until a call to "pm_access" is made.
- */
-typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
-
-Driver Details
---------------
-This is just a quick Q&A as a stopgap until a real driver writers'
-power management guide is available.
-
-Q: When is a device suspended?
-
-Devices can be suspended based on direct user request (eg. laptop lid
-closes), system power policy (eg.  sleep after 30 minutes of console
-inactivity), or device power policy (eg. power down device after 5
-minutes of inactivity)
-
-Q: Must a driver honor a suspend request?
-
-No, a driver can return -EBUSY from a suspend request and this
-will stop the system from suspending.  When a suspend request
-fails, all suspended devices are resumed and the system continues
-to run.  Suspend can be retried at a later time.
-
-Q: Can the driver block suspend/resume requests?
-
-Yes, a driver can delay its return from a suspend or resume
-request until the device is ready to handle requests.  It
-is advantageous to return as quickly as possible from a
-request as suspend/resume are done serially.
-
-Q: What context is a suspend/resume initiated from?
-
-A suspend or resume is initiated from a kernel thread context.
-It is safe to block, allocate memory, initiate requests
-or anything else you can do within the kernel.
-
-Q: Will requests continue to arrive after a suspend?
-
-Possibly.  It is the driver's responsibility to queue(*),
-fail, or drop any requests that arrive after returning
-success to a suspend request.  It is important that the
-driver not access its device until after it receives
-a resume request as the device's bus may no longer
-be active.
-
-(*) If a driver queues requests for processing after
-    resume be aware that the device, network, etc.
-    might be in a different state than at suspend time.
-    It's probably better to drop requests unless
-    the driver is a storage device.
-
-Q: Do I have to manage bus-specific power management registers
-
-No.  It is the responsibility of the bus driver to manage
-PCI, USB, etc. power management registers.  The bus driver
-or the power management subsystem will also enable any
-wake-on functionality that the device has.
-
-Q: So, really, what do I need to do to support suspend/resume?
-
-You need to save any device context that would
-be lost if the device was powered off and then restore
-it at resume time.  When ACPI is active, there are
-three levels of device suspend states; D1, D2, and D3.
-(The suspend state is passed as the "data" argument
-to the device callback.)  With D3, the device is powered
-off and loses all context, D1 and D2 are shallower power
-states and require less device context to be saved.  To
-play it safe, just save everything at suspend and restore
-everything at resume.
-
-Q: Where do I store device context for suspend?
-
-Anywhere in memory, kmalloc a buffer or store it
-in the device descriptor.  You are guaranteed that the
-contents of memory will be restored and accessible
-before resume, even when the system suspends to disk.
-
-Q: What do I need to do for ACPI vs. APM vs. etc?
-
-Drivers need not be aware of the specific power management
-technology that is active.  They just need to be aware
-of when the overlying power management system requests
-that they suspend or resume.
-
-Q: What about device dependencies?
-
-When a driver registers a device, the power management
-subsystem uses the information provided to build a
-tree of device dependencies (eg. USB device X is on
-USB controller Y which is on PCI bus Z)  When power
-management wants to suspend a device, it first sends
-a suspend request to its driver, then the bus driver,
-and so on up to the system bus.  Device resumes
-proceed in the opposite direction.
-
-Q: Who do I contact for additional information about
-   enabling power management for my specific driver/device?
-
-ACPI Development mailing list: linux-acpi@vger.kernel.org
-
-System Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-If you are providing new power management support to Linux (ie.
-adding support for something like APM or ACPI), you should
-communicate with drivers through the existing generic power
-management interface.
-
-/*
- * Send a request to all devices
- *
- * Parameters:
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          See "pm_callback" return for errors
- *
- * Details: Walk list of registered devices and call pm_send
- *          for each until complete or an error is encountered.
- *          If an error is encountered for a suspend request,
- *          return all devices to the state they were in before
- *          the suspend request.
- */
-int pm_send_all(pm_request_t rqst, void *data);
-
-/*
- * Find a matching device
- *
- * Parameters:
- *   type - device type (PCI device, system device, or 0 to match all devices)
- *   from - previous match or NULL to start from the beginning
- *
- * Returns: Matching device or NULL if none found
- */
-struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/pm.txt
@@ -0,0 +1,257 @@
+               Linux Power Management Support
+
+This document briefly describes how to use power management with your
+Linux system and how to add power management support to Linux drivers.
+
+APM or ACPI?
+------------
+If you have a relatively recent x86 mobile, desktop, or server system,
+odds are it supports either Advanced Power Management (APM) or
+Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
+of the two technologies and puts power management in the hands of the
+operating system, allowing for more intelligent power management than
+is possible with BIOS controlled APM.
+
+The best way to determine which, if either, your system supports is to
+build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
+enabled by default).  If a working ACPI implementation is found, the
+ACPI driver will override and disable APM, otherwise the APM driver
+will be used.
+
+No, sorry, you cannot have both ACPI and APM enabled and running at
+once.  Some people with broken ACPI or broken APM implementations
+would like to use both to get a full set of working features, but you
+simply cannot mix and match the two.  Only one power management
+interface can be in control of the machine at once.  Think about it..
+
+User-space Daemons
+------------------
+Both APM and ACPI rely on user-space daemons, apmd and acpid
+respectively, to be completely functional.  Obtain both of these
+daemons from your Linux distribution or from the Internet (see below)
+and be sure that they are started sometime in the system boot process.
+Go ahead and start both.  If ACPI or APM is not available on your
+system the associated daemon will exit gracefully.
+
+  apmd:   http://worldvisions.ca/~apenwarr/apmd/
+  acpid:  http://acpid.sf.net/
+
+Driver Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+
+Note: pm_register(), pm_access(), pm_dev_idle() and friends are
+obsolete. Please do not use them. Instead you should properly hook
+your driver into the driver model, and use its suspend()/resume()
+callbacks to do this kind of stuff.
+
+If you are writing a new driver or maintaining an old driver, it
+should include power management support.  Without power management
+support, a single driver may prevent a system with power management
+capabilities from ever being able to suspend (safely).
+
+Overview:
+1) Register each instance of a device with "pm_register"
+2) Call "pm_access" before accessing the hardware.
+   (this will ensure that the hardware is awake and ready)
+3) Your "pm_callback" is called before going into a
+   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
+   from a suspend.
+4) Call "pm_dev_idle" when the device is not being used
+   (optional but will improve device idle detection)
+5) When unloaded, unregister the device with "pm_unregister"
+
+/*
+ * Description: Register a device with the power-management subsystem
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, ...)
+ *   id - instance number or unique identifier
+ *   cback - request handler callback (suspend, resume, ...)
+ *
+ * Returns: Registered PM device or NULL on error
+ *
+ * Examples:
+ *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
+ *
+ *   struct pci_dev *pci_dev = pci_find_dev(...);
+ *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
+ */
+struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
+
+/*
+ * Description: Unregister a device with the power management subsystem
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ */
+void pm_unregister(struct pm_dev *dev);
+
+/*
+ * Description: Unregister all devices with a matching callback function
+ *
+ * Parameters:
+ *   cback - previously registered request callback
+ *
+ * Notes: Provided for easier porting from old APM interface
+ */
+void pm_unregister_all(pm_callback cback);
+
+/*
+ * Power management request callback
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          EINVAL if the request is not supported
+ *          EBUSY if the device is now busy and cannot handle the request
+ *          ENOMEM if the device was unable to handle the request due to memory
+ *
+ * Details: The device request callback will be called before the
+ *          device/system enters a suspend state (ACPI D1-D3) or
+ *          or after the device/system resumes from suspend (ACPI D0).
+ *          For PM_SUSPEND, the ACPI D-state being entered is passed
+ *          as the "data" argument to the callback.  The device
+ *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
+ *          device context when the request callback is called.
+ *
+ *          Once a driver returns 0 (success) from a suspend
+ *          request, it should not process any further requests or
+ *          access the device hardware until a call to "pm_access" is made.
+ */
+typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
+
+Driver Details
+--------------
+This is just a quick Q&A as a stopgap until a real driver writers'
+power management guide is available.
+
+Q: When is a device suspended?
+
+Devices can be suspended based on direct user request (eg. laptop lid
+closes), system power policy (eg.  sleep after 30 minutes of console
+inactivity), or device power policy (eg. power down device after 5
+minutes of inactivity)
+
+Q: Must a driver honor a suspend request?
+
+No, a driver can return -EBUSY from a suspend request and this
+will stop the system from suspending.  When a suspend request
+fails, all suspended devices are resumed and the system continues
+to run.  Suspend can be retried at a later time.
+
+Q: Can the driver block suspend/resume requests?
+
+Yes, a driver can delay its return from a suspend or resume
+request until the device is ready to handle requests.  It
+is advantageous to return as quickly as possible from a
+request as suspend/resume are done serially.
+
+Q: What context is a suspend/resume initiated from?
+
+A suspend or resume is initiated from a kernel thread context.
+It is safe to block, allocate memory, initiate requests
+or anything else you can do within the kernel.
+
+Q: Will requests continue to arrive after a suspend?
+
+Possibly.  It is the driver's responsibility to queue(*),
+fail, or drop any requests that arrive after returning
+success to a suspend request.  It is important that the
+driver not access its device until after it receives
+a resume request as the device's bus may no longer
+be active.
+
+(*) If a driver queues requests for processing after
+    resume be aware that the device, network, etc.
+    might be in a different state than at suspend time.
+    It's probably better to drop requests unless
+    the driver is a storage device.
+
+Q: Do I have to manage bus-specific power management registers
+
+No.  It is the responsibility of the bus driver to manage
+PCI, USB, etc. power management registers.  The bus driver
+or the power management subsystem will also enable any
+wake-on functionality that the device has.
+
+Q: So, really, what do I need to do to support suspend/resume?
+
+You need to save any device context that would
+be lost if the device was powered off and then restore
+it at resume time.  When ACPI is active, there are
+three levels of device suspend states; D1, D2, and D3.
+(The suspend state is passed as the "data" argument
+to the device callback.)  With D3, the device is powered
+off and loses all context, D1 and D2 are shallower power
+states and require less device context to be saved.  To
+play it safe, just save everything at suspend and restore
+everything at resume.
+
+Q: Where do I store device context for suspend?
+
+Anywhere in memory, kmalloc a buffer or store it
+in the device descriptor.  You are guaranteed that the
+contents of memory will be restored and accessible
+before resume, even when the system suspends to disk.
+
+Q: What do I need to do for ACPI vs. APM vs. etc?
+
+Drivers need not be aware of the specific power management
+technology that is active.  They just need to be aware
+of when the overlying power management system requests
+that they suspend or resume.
+
+Q: What about device dependencies?
+
+When a driver registers a device, the power management
+subsystem uses the information provided to build a
+tree of device dependencies (eg. USB device X is on
+USB controller Y which is on PCI bus Z)  When power
+management wants to suspend a device, it first sends
+a suspend request to its driver, then the bus driver,
+and so on up to the system bus.  Device resumes
+proceed in the opposite direction.
+
+Q: Who do I contact for additional information about
+   enabling power management for my specific driver/device?
+
+ACPI Development mailing list: linux-acpi@vger.kernel.org
+
+System Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+If you are providing new power management support to Linux (ie.
+adding support for something like APM or ACPI), you should
+communicate with drivers through the existing generic power
+management interface.
+
+/*
+ * Send a request to all devices
+ *
+ * Parameters:
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          See "pm_callback" return for errors
+ *
+ * Details: Walk list of registered devices and call pm_send
+ *          for each until complete or an error is encountered.
+ *          If an error is encountered for a suspend request,
+ *          return all devices to the state they were in before
+ *          the suspend request.
+ */
+int pm_send_all(pm_request_t rqst, void *data);
+
+/*
+ * Find a matching device
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, or 0 to match all devices)
+ *   from - previous match or NULL to start from the beginning
+ *
+ * Returns: Matching device or NULL if none found
+ */
+struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- lin2625-rc5g2-kdoc.orig/Documentation/pm_qos_interface.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-PM quality of Service interface.
-
-This interface provides a kernel and user mode interface for registering
-performance expectations by drivers, subsystems and user space applications on
-one of the parameters.
-
-Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
-initial set of pm_qos parameters.
-
-The infrastructure exposes multiple misc device nodes one per implemented
-parameter.  The set of parameters implement is defined by pm_qos_power_init()
-and pm_qos_params.h.  This is done because having the available parameters
-being runtime configurable or changeable from a driver was seen as too easy to
-abuse.
-
-For each parameter a list of performance requirements is maintained along with
-an aggregated target value.  The aggregated target value is updated with
-changes to the requirement list or elements of the list.  Typically the
-aggregated target value is simply the max or min of the requirement values held
-in the parameter list elements.
-
-From kernel mode the use of this interface is simple:
-pm_qos_add_requirement(param_id, name, target_value):
-Will insert a named element in the list for that identified PM_QOS parameter
-with the target value.  Upon change to this list the new target is recomputed
-and any registered notifiers are called only if the target value is now
-different.
-
-pm_qos_update_requirement(param_id, name, new_target_value):
-Will search the list identified by the param_id for the named list element and
-then update its target value, calling the notification tree if the aggregated
-target is changed.  with that name is already registered.
-
-pm_qos_remove_requirement(param_id, name):
-Will search the identified list for the named element and remove it, after
-removal it will update the aggregate target and call the notification tree if
-the target was changed as a result of removing the named requirement.
-
-
-From user mode:
-Only processes can register a pm_qos requirement.  To provide for automatic
-cleanup for process the interface requires the process to register its
-parameter requirements in the following way:
-
-To register the default pm_qos target for the specific parameter, the process
-must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
-
-As long as the device node is held open that process has a registered
-requirement on the parameter.  The name of the requirement is "process_<PID>"
-derived from the current->pid from within the open system call.
-
-To change the requested target value the process needs to write a s32 value to
-the open device node.  This translates to a pm_qos_update_requirement call.
-
-To remove the user mode request for a target value simply close the device
-node.
-
-
-
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/pm_qos_interface.txt
@@ -0,0 +1,59 @@
+PM quality of Service interface.
+
+This interface provides a kernel and user mode interface for registering
+performance expectations by drivers, subsystems and user space applications on
+one of the parameters.
+
+Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
+initial set of pm_qos parameters.
+
+The infrastructure exposes multiple misc device nodes one per implemented
+parameter.  The set of parameters implement is defined by pm_qos_power_init()
+and pm_qos_params.h.  This is done because having the available parameters
+being runtime configurable or changeable from a driver was seen as too easy to
+abuse.
+
+For each parameter a list of performance requirements is maintained along with
+an aggregated target value.  The aggregated target value is updated with
+changes to the requirement list or elements of the list.  Typically the
+aggregated target value is simply the max or min of the requirement values held
+in the parameter list elements.
+
+From kernel mode the use of this interface is simple:
+pm_qos_add_requirement(param_id, name, target_value):
+Will insert a named element in the list for that identified PM_QOS parameter
+with the target value.  Upon change to this list the new target is recomputed
+and any registered notifiers are called only if the target value is now
+different.
+
+pm_qos_update_requirement(param_id, name, new_target_value):
+Will search the list identified by the param_id for the named list element and
+then update its target value, calling the notification tree if the aggregated
+target is changed.  with that name is already registered.
+
+pm_qos_remove_requirement(param_id, name):
+Will search the identified list for the named element and remove it, after
+removal it will update the aggregate target and call the notification tree if
+the target was changed as a result of removing the named requirement.
+
+
+From user mode:
+Only processes can register a pm_qos requirement.  To provide for automatic
+cleanup for process the interface requires the process to register its
+parameter requirements in the following way:
+
+To register the default pm_qos target for the specific parameter, the process
+must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
+
+As long as the device node is held open that process has a registered
+requirement on the parameter.  The name of the requirement is "process_<PID>"
+derived from the current->pid from within the open system call.
+
+To change the requested target value the process needs to write a s32 value to
+the open device node.  This translates to a pm_qos_update_requirement call.
+
+To remove the user mode request for a target value simply close the device
+node.
+
+
+
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/power_supply_class.txt
@@ -0,0 +1,169 @@
+Linux power supply class
+========================
+
+Synopsis
+~~~~~~~~
+Power supply class used to represent battery, UPS, AC or DC power supply
+properties to user-space.
+
+It defines core set of attributes, which should be applicable to (almost)
+every power supply out there. Attributes are available via sysfs and uevent
+interfaces.
+
+Each attribute has well defined meaning, up to unit of measure used. While
+the attributes provided are believed to be universally applicable to any
+power supply, specific monitoring hardware may not be able to provide them
+all, so any of them may be skipped.
+
+Power supply class is extensible, and allows to define drivers own attributes.
+The core attribute set is subject to the standard Linux evolution (i.e.
+if it will be found that some attribute is applicable to many power supply
+types or their drivers, it can be added to the core set).
+
+It also integrates with LED framework, for the purpose of providing
+typically expected feedback of battery charging/fully charged status and
+AC/USB power supply online status. (Note that specific details of the
+indication (including whether to use it at all) are fully controllable by
+user and/or specific machine defaults, per design principles of LED
+framework).
+
+
+Attributes/properties
+~~~~~~~~~~~~~~~~~~~~~
+Power supply class has predefined set of attributes, this eliminates code
+duplication across drivers. Power supply class insist on reusing its
+predefined attributes *and* their units.
+
+So, userspace gets predictable set of attributes and their units for any
+kind of power supply, and can process/present them to a user in consistent
+manner. Results for different power supplies and machines are also directly
+comparable.
+
+See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
+example how to declare and handle attributes.
+
+
+Units
+~~~~~
+Quoting include/linux/power_supply.h:
+
+  All voltages, currents, charges, energies, time and temperatures in µV,
+  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
+  stated. It's driver's job to convert its raw values to units in which
+  this class operates.
+
+
+Attributes/properties detailed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
+~                                                                       ~
+~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
+~ of battery, this class distinguish these terms. Don't mix them!       ~
+~                                                                       ~
+~ CHARGE_* attributes represents capacity in µAh only.                  ~
+~ ENERGY_* attributes represents capacity in µWh only.                  ~
+~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
+~                                                                       ~
+~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+
+Postfixes:
+_AVG - *hardware* averaged value, use it if your hardware is really able to
+report averaged values.
+_NOW - momentary/instantaneous values.
+
+STATUS - this attribute represents operating status (charging, full,
+discharging (i.e. powering a load), etc.). This corresponds to
+BATTERY_STATUS_* values, as defined in battery.h.
+
+HEALTH - represents health of the battery, values corresponds to
+POWER_SUPPLY_HEALTH_*, defined in battery.h.
+
+VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
+minimal power supply voltages. Maximal/minimal means values of voltages
+when battery considered "full"/"empty" at normal conditions. Yes, there is
+no direct relation between voltage and battery capacity, but some dumb
+batteries use voltage for very approximated calculation of capacity.
+Battery driver also can use this attribute just to inform userspace
+about maximal and minimal voltage thresholds of a given battery.
+
+VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
+these ones should be used if hardware could only guess (measure and
+retain) the thresholds of a given power supply.
+
+CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
+battery considered full/empty.
+
+ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
+
+CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
+of charge when battery became full/empty". It also could mean "value of
+charge when battery considered full/empty at given conditions (temperature,
+age)". I.e. these attributes represents real thresholds, not design values.
+
+ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
+
+CAPACITY - capacity in percents.
+
+TEMP - temperature of the power supply.
+TEMP_AMBIENT - ambient temperature.
+
+TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
+while battery powers a load)
+TIME_TO_FULL - seconds left for battery to be considered full (i.e.
+while battery is charging)
+
+
+Battery <-> external power supply interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Often power supplies are acting as supplies and supplicants at the same
+time. Batteries are good example. So, batteries usually care if they're
+externally powered or not.
+
+For that case, power supply class implements notification mechanism for
+batteries.
+
+External power supply (AC) lists supplicants (batteries) names in
+"supplied_to" struct member, and each power_supply_changed() call
+issued by external power supply will notify supplicants via
+external_power_changed callback.
+
+
+QA
+~~
+Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
+A: If you cannot find attribute suitable for your driver needs, feel free
+   to add it and send patch along with your driver.
+
+   The attributes available currently are the ones currently provided by the
+   drivers written.
+
+   Good candidates to add in future: model/part#, cycle_time, manufacturer,
+   etc.
+
+
+Q: I have some very specific attribute (e.g. battery color), should I add
+   this attribute to standard ones?
+A: Most likely, no. Such attribute can be placed in the driver itself, if
+   it is useful. Of course, if the attribute in question applicable to
+   large set of batteries, provided by many drivers, and/or comes from
+   some general battery specification/standard, it may be a candidate to
+   be added to the core attribute set.
+
+
+Q: Suppose, my battery monitoring chip/firmware does not provides capacity
+   in percents, but provides charge_{now,full,empty}. Should I calculate
+   percentage capacity manually, inside the driver, and register CAPACITY
+   attribute? The same question about time_to_empty/time_to_full.
+A: Most likely, no. This class is designed to export properties which are
+   directly measurable by the specific hardware available.
+
+   Inferring not available properties using some heuristics or mathematical
+   model is not subject of work for a battery driver. Such functionality
+   should be factored out, and in fact, apm_power, the driver to serve
+   legacy APM API on top of power supply class, uses a simple heuristic of
+   approximating remaining battery capacity based on its charge, current,
+   voltage and so on. But full-fledged battery model is likely not subject
+   for kernel at all, as it would require floating point calculation to deal
+   with things like differential equations and Kalman filters. This is
+   better be handled by batteryd/libbattery, yet to be written.
--- lin2625-rc5g2-kdoc.orig/Documentation/power_supply_class.txt
+++ /dev/null
@@ -1,169 +0,0 @@
-Linux power supply class
-========================
-
-Synopsis
-~~~~~~~~
-Power supply class used to represent battery, UPS, AC or DC power supply
-properties to user-space.
-
-It defines core set of attributes, which should be applicable to (almost)
-every power supply out there. Attributes are available via sysfs and uevent
-interfaces.
-
-Each attribute has well defined meaning, up to unit of measure used. While
-the attributes provided are believed to be universally applicable to any
-power supply, specific monitoring hardware may not be able to provide them
-all, so any of them may be skipped.
-
-Power supply class is extensible, and allows to define drivers own attributes.
-The core attribute set is subject to the standard Linux evolution (i.e.
-if it will be found that some attribute is applicable to many power supply
-types or their drivers, it can be added to the core set).
-
-It also integrates with LED framework, for the purpose of providing
-typically expected feedback of battery charging/fully charged status and
-AC/USB power supply online status. (Note that specific details of the
-indication (including whether to use it at all) are fully controllable by
-user and/or specific machine defaults, per design principles of LED
-framework).
-
-
-Attributes/properties
-~~~~~~~~~~~~~~~~~~~~~
-Power supply class has predefined set of attributes, this eliminates code
-duplication across drivers. Power supply class insist on reusing its
-predefined attributes *and* their units.
-
-So, userspace gets predictable set of attributes and their units for any
-kind of power supply, and can process/present them to a user in consistent
-manner. Results for different power supplies and machines are also directly
-comparable.
-
-See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
-example how to declare and handle attributes.
-
-
-Units
-~~~~~
-Quoting include/linux/power_supply.h:
-
-  All voltages, currents, charges, energies, time and temperatures in µV,
-  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
-  stated. It's driver's job to convert its raw values to units in which
-  this class operates.
-
-
-Attributes/properties detailed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
-~                                                                       ~
-~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
-~ of battery, this class distinguish these terms. Don't mix them!       ~
-~                                                                       ~
-~ CHARGE_* attributes represents capacity in µAh only.                  ~
-~ ENERGY_* attributes represents capacity in µWh only.                  ~
-~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
-~                                                                       ~
-~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
-
-Postfixes:
-_AVG - *hardware* averaged value, use it if your hardware is really able to
-report averaged values.
-_NOW - momentary/instantaneous values.
-
-STATUS - this attribute represents operating status (charging, full,
-discharging (i.e. powering a load), etc.). This corresponds to
-BATTERY_STATUS_* values, as defined in battery.h.
-
-HEALTH - represents health of the battery, values corresponds to
-POWER_SUPPLY_HEALTH_*, defined in battery.h.
-
-VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
-minimal power supply voltages. Maximal/minimal means values of voltages
-when battery considered "full"/"empty" at normal conditions. Yes, there is
-no direct relation between voltage and battery capacity, but some dumb
-batteries use voltage for very approximated calculation of capacity.
-Battery driver also can use this attribute just to inform userspace
-about maximal and minimal voltage thresholds of a given battery.
-
-VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
-these ones should be used if hardware could only guess (measure and
-retain) the thresholds of a given power supply.
-
-CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
-battery considered full/empty.
-
-ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
-
-CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
-of charge when battery became full/empty". It also could mean "value of
-charge when battery considered full/empty at given conditions (temperature,
-age)". I.e. these attributes represents real thresholds, not design values.
-
-ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
-
-CAPACITY - capacity in percents.
-
-TEMP - temperature of the power supply.
-TEMP_AMBIENT - ambient temperature.
-
-TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
-while battery powers a load)
-TIME_TO_FULL - seconds left for battery to be considered full (i.e.
-while battery is charging)
-
-
-Battery <-> external power supply interaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Often power supplies are acting as supplies and supplicants at the same
-time. Batteries are good example. So, batteries usually care if they're
-externally powered or not.
-
-For that case, power supply class implements notification mechanism for
-batteries.
-
-External power supply (AC) lists supplicants (batteries) names in
-"supplied_to" struct member, and each power_supply_changed() call
-issued by external power supply will notify supplicants via
-external_power_changed callback.
-
-
-QA
-~~
-Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
-A: If you cannot find attribute suitable for your driver needs, feel free
-   to add it and send patch along with your driver.
-
-   The attributes available currently are the ones currently provided by the
-   drivers written.
-
-   Good candidates to add in future: model/part#, cycle_time, manufacturer,
-   etc.
-
-
-Q: I have some very specific attribute (e.g. battery color), should I add
-   this attribute to standard ones?
-A: Most likely, no. Such attribute can be placed in the driver itself, if
-   it is useful. Of course, if the attribute in question applicable to
-   large set of batteries, provided by many drivers, and/or comes from
-   some general battery specification/standard, it may be a candidate to
-   be added to the core attribute set.
-
-
-Q: Suppose, my battery monitoring chip/firmware does not provides capacity
-   in percents, but provides charge_{now,full,empty}. Should I calculate
-   percentage capacity manually, inside the driver, and register CAPACITY
-   attribute? The same question about time_to_empty/time_to_full.
-A: Most likely, no. This class is designed to export properties which are
-   directly measurable by the specific hardware available.
-
-   Inferring not available properties using some heuristics or mathematical
-   model is not subject of work for a battery driver. Such functionality
-   should be factored out, and in fact, apm_power, the driver to serve
-   legacy APM API on top of power supply class, uses a simple heuristic of
-   approximating remaining battery capacity based on its charge, current,
-   voltage and so on. But full-fledged battery model is likely not subject
-   for kernel at all, as it would require floating point calculation to deal
-   with things like differential equations and Kalman filters. This is
-   better be handled by batteryd/libbattery, yet to be written.
--- lin2625-rc5g2-kdoc.orig/arch/x86/Kconfig
+++ lin2625-rc5g2-kdoc/arch/x86/Kconfig
@@ -1259,7 +1259,7 @@ menuconfig APM
 	  machines with more than one CPU.
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- lin2625-rc5g2-kdoc.orig/kernel/power/Kconfig
+++ lin2625-rc5g2-kdoc/kernel/power/Kconfig
@@ -190,7 +190,7 @@ config APM_EMULATION
 	  notification of APM "events" (e.g. battery status change).
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- lin2625-rc5g2-kdoc.orig/Documentation/kernel-parameters.txt
+++ lin2625-rc5g2-kdoc/Documentation/kernel-parameters.txt
@@ -138,7 +138,7 @@ and is between 256 and 4096 characters. 
 			strict -- Be less tolerant of platforms that are not
 				strictly ACPI specification compliant.
 
-			See also Documentation/pm.txt, pci=noacpi
+			See also Documentation/power/pm.txt, pci=noacpi
 
 	acpi_apic_instance=	[ACPI, IOAPIC]
 			Format: <int>
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [linux-pm] [PATCH] doc/power: move power-related files to Documentation/power/

[Len Brown]

On Wednesday 12 March 2008, Randy Dunlap wrote:
> On Wed, 12 Mar 2008 16:00:45 -0400 Len Brown wrote:
> 
> > linus top of tree.  i was wrong that it was already gone,
> > i guess i assumed that since it had 1 hunk and patch
> > told me the hunk was reversed i assumed that part
> > had been applied already.
> 
> Can you try the patch below?
> It works_for_me but that doesn't give me lots of confidence.
> 
> ---
> From: Randy Dunlap <randy.dunlap@oracle.com>
> 
> 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>
> ---
>  Documentation/00-INDEX                     |    4 
>  Documentation/kernel-parameters.txt        |    2 
>  Documentation/pm.txt                       |  257 -------------------
>  Documentation/pm_qos_interface.txt         |   59 ----
>  Documentation/power/00-INDEX               |    6 
>  Documentation/power/pm.txt                 |  257 +++++++++++++++++++
>  Documentation/power/pm_qos_interface.txt   |   59 ++++
>  Documentation/power/power_supply_class.txt |  169 ++++++++++++
>  Documentation/power_supply_class.txt       |  169 ------------
>  arch/x86/Kconfig                           |    2 
>  kernel/power/Kconfig                       |    2 
>  11 files changed, 494 insertions(+), 492 deletions(-)
> 

not better

Please send it to me as an attachment,
maybe kmail is getting confused b/c this text has non ascii characters?

(does this patch apply for anybody else?)

thanks,
-Len

[lenb@t61 linus (master)]$ patch -Np1 --dry-run < ~/Documents/doc-new.patch
patching file Documentation/00-INDEX
patching file Documentation/power/00-INDEX
patching file Documentation/pm.txt
patching file Documentation/power/pm.txt
patching file Documentation/pm_qos_interface.txt
patching file Documentation/power/pm_qos_interface.txt
patching file Documentation/power/power_supply_class.txt
patching file Documentation/power_supply_class.txt
Reversed (or previously applied) patch detected!  Skipping patch.
1 out of 1 hunk ignored -- saving rejects to file Documentation/power_supply_class.txt.rej
patching file arch/x86/Kconfig
patching file kernel/power/Kconfig
patching file Documentation/kernel-parameters.txt
[lenb@t61 linus (master)]$   

Re: [linux-pm] [PATCH] doc/power: move power-related files to Documentation/power/

[Randy Dunlap]

[-- Attachment #1: Type: text/plain, Size: 708 bytes --]

On Wed, 12 Mar 2008 17:49:37 -0400 Len Brown wrote:

> On Wednesday 12 March 2008, Randy Dunlap wrote:
> > On Wed, 12 Mar 2008 16:00:45 -0400 Len Brown wrote:
> > 
> > > linus top of tree.  i was wrong that it was already gone,
> > > i guess i assumed that since it had 1 hunk and patch
> > > told me the hunk was reversed i assumed that part
> > > had been applied already.
> > 
> > Can you try the patch below?
> > It works_for_me but that doesn't give me lots of confidence.
> > 
> > ---
...
> > 
> 
> not better
> 
> Please send it to me as an attachment,
> maybe kmail is getting confused b/c this text has non ascii characters?
> 
> (does this patch apply for anybody else?)

OK, attached.

---
~Randy

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: doc-move-power.patch --]
[-- Type: text/x-patch; name="doc-move-power.patch", Size: 46020 bytes --]

From: Randy Dunlap <randy.dunlap@oracle.com>

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>
---
 Documentation/00-INDEX                     |    4 
 Documentation/kernel-parameters.txt        |    2 
 Documentation/pm.txt                       |  257 -------------------
 Documentation/pm_qos_interface.txt         |   59 ----
 Documentation/power/00-INDEX               |    6 
 Documentation/power/pm.txt                 |  257 +++++++++++++++++++
 Documentation/power/pm_qos_interface.txt   |   59 ++++
 Documentation/power/power_supply_class.txt |  169 ++++++++++++
 Documentation/power_supply_class.txt       |  169 ------------
 arch/x86/Kconfig                           |    2 
 kernel/power/Kconfig                       |    2 
 11 files changed, 494 insertions(+), 492 deletions(-)

--- lin2625-rc5g2-kdoc.orig/Documentation/00-INDEX
+++ lin2625-rc5g2-kdoc/Documentation/00-INDEX
@@ -301,12 +301,8 @@ pcmcia/
 	- info on the Linux PCMCIA driver.
 pi-futex.txt
 	- documentation on lightweight PI-futexes.
-pm.txt
-	- info on Linux power management support.
 pnp.txt
 	- Linux Plug and Play documentation.
-power_supply_class.txt
-	- Tells userspace about battery, UPS, AC or DC power supply properties
 power/
 	- directory with info on Linux PCI power management.
 powerpc/
--- lin2625-rc5g2-kdoc.orig/Documentation/power/00-INDEX
+++ lin2625-rc5g2-kdoc/Documentation/power/00-INDEX
@@ -14,6 +14,12 @@ notifiers.txt
 	- Registering suspend notifiers in device drivers
 pci.txt
 	- How the PCI Subsystem Does Power Management
+pm.txt
+	- info on Linux power management support.
+pm_qos_interface.txt
+	- info on Linux PM Quality of Service interface
+power_supply_class.txt
+	- Tells userspace about battery, UPS, AC or DC power supply properties
 s2ram.txt
 	- How to get suspend to ram working (and debug it when it isn't)
 states.txt
--- lin2625-rc5g2-kdoc.orig/Documentation/pm.txt
+++ /dev/null
@@ -1,257 +0,0 @@
-               Linux Power Management Support
-
-This document briefly describes how to use power management with your
-Linux system and how to add power management support to Linux drivers.
-
-APM or ACPI?
-------------
-If you have a relatively recent x86 mobile, desktop, or server system,
-odds are it supports either Advanced Power Management (APM) or
-Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
-of the two technologies and puts power management in the hands of the
-operating system, allowing for more intelligent power management than
-is possible with BIOS controlled APM.
-
-The best way to determine which, if either, your system supports is to
-build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
-enabled by default).  If a working ACPI implementation is found, the
-ACPI driver will override and disable APM, otherwise the APM driver
-will be used.
-
-No, sorry, you cannot have both ACPI and APM enabled and running at
-once.  Some people with broken ACPI or broken APM implementations
-would like to use both to get a full set of working features, but you
-simply cannot mix and match the two.  Only one power management
-interface can be in control of the machine at once.  Think about it..
-
-User-space Daemons
-------------------
-Both APM and ACPI rely on user-space daemons, apmd and acpid
-respectively, to be completely functional.  Obtain both of these
-daemons from your Linux distribution or from the Internet (see below)
-and be sure that they are started sometime in the system boot process.
-Go ahead and start both.  If ACPI or APM is not available on your
-system the associated daemon will exit gracefully.
-
-  apmd:   http://worldvisions.ca/~apenwarr/apmd/
-  acpid:  http://acpid.sf.net/
-
-Driver Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-
-Note: pm_register(), pm_access(), pm_dev_idle() and friends are
-obsolete. Please do not use them. Instead you should properly hook
-your driver into the driver model, and use its suspend()/resume()
-callbacks to do this kind of stuff.
-
-If you are writing a new driver or maintaining an old driver, it
-should include power management support.  Without power management
-support, a single driver may prevent a system with power management
-capabilities from ever being able to suspend (safely).
-
-Overview:
-1) Register each instance of a device with "pm_register"
-2) Call "pm_access" before accessing the hardware.
-   (this will ensure that the hardware is awake and ready)
-3) Your "pm_callback" is called before going into a
-   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
-   from a suspend.
-4) Call "pm_dev_idle" when the device is not being used
-   (optional but will improve device idle detection)
-5) When unloaded, unregister the device with "pm_unregister"
-
-/*
- * Description: Register a device with the power-management subsystem
- *
- * Parameters:
- *   type - device type (PCI device, system device, ...)
- *   id - instance number or unique identifier
- *   cback - request handler callback (suspend, resume, ...)
- *
- * Returns: Registered PM device or NULL on error
- *
- * Examples:
- *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
- *
- *   struct pci_dev *pci_dev = pci_find_dev(...);
- *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
- */
-struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
-
-/*
- * Description: Unregister a device with the power management subsystem
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- */
-void pm_unregister(struct pm_dev *dev);
-
-/*
- * Description: Unregister all devices with a matching callback function
- *
- * Parameters:
- *   cback - previously registered request callback
- *
- * Notes: Provided for easier porting from old APM interface
- */
-void pm_unregister_all(pm_callback cback);
-
-/*
- * Power management request callback
- *
- * Parameters:
- *   dev - PM device previously returned from pm_register
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          EINVAL if the request is not supported
- *          EBUSY if the device is now busy and cannot handle the request
- *          ENOMEM if the device was unable to handle the request due to memory
- *          
- * Details: The device request callback will be called before the
- *          device/system enters a suspend state (ACPI D1-D3) or
- *          or after the device/system resumes from suspend (ACPI D0).
- *          For PM_SUSPEND, the ACPI D-state being entered is passed
- *          as the "data" argument to the callback.  The device
- *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
- *          device context when the request callback is called.
- *
- *          Once a driver returns 0 (success) from a suspend
- *          request, it should not process any further requests or
- *          access the device hardware until a call to "pm_access" is made.
- */
-typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
-
-Driver Details
---------------
-This is just a quick Q&A as a stopgap until a real driver writers'
-power management guide is available.
-
-Q: When is a device suspended?
-
-Devices can be suspended based on direct user request (eg. laptop lid
-closes), system power policy (eg.  sleep after 30 minutes of console
-inactivity), or device power policy (eg. power down device after 5
-minutes of inactivity)
-
-Q: Must a driver honor a suspend request?
-
-No, a driver can return -EBUSY from a suspend request and this
-will stop the system from suspending.  When a suspend request
-fails, all suspended devices are resumed and the system continues
-to run.  Suspend can be retried at a later time.
-
-Q: Can the driver block suspend/resume requests?
-
-Yes, a driver can delay its return from a suspend or resume
-request until the device is ready to handle requests.  It
-is advantageous to return as quickly as possible from a
-request as suspend/resume are done serially.
-
-Q: What context is a suspend/resume initiated from?
-
-A suspend or resume is initiated from a kernel thread context.
-It is safe to block, allocate memory, initiate requests
-or anything else you can do within the kernel.
-
-Q: Will requests continue to arrive after a suspend?
-
-Possibly.  It is the driver's responsibility to queue(*),
-fail, or drop any requests that arrive after returning
-success to a suspend request.  It is important that the
-driver not access its device until after it receives
-a resume request as the device's bus may no longer
-be active.
-
-(*) If a driver queues requests for processing after
-    resume be aware that the device, network, etc.
-    might be in a different state than at suspend time.
-    It's probably better to drop requests unless
-    the driver is a storage device.
-
-Q: Do I have to manage bus-specific power management registers
-
-No.  It is the responsibility of the bus driver to manage
-PCI, USB, etc. power management registers.  The bus driver
-or the power management subsystem will also enable any
-wake-on functionality that the device has.
-
-Q: So, really, what do I need to do to support suspend/resume?
-
-You need to save any device context that would
-be lost if the device was powered off and then restore
-it at resume time.  When ACPI is active, there are
-three levels of device suspend states; D1, D2, and D3.
-(The suspend state is passed as the "data" argument
-to the device callback.)  With D3, the device is powered
-off and loses all context, D1 and D2 are shallower power
-states and require less device context to be saved.  To
-play it safe, just save everything at suspend and restore
-everything at resume.
-
-Q: Where do I store device context for suspend?
-
-Anywhere in memory, kmalloc a buffer or store it
-in the device descriptor.  You are guaranteed that the
-contents of memory will be restored and accessible
-before resume, even when the system suspends to disk.
-
-Q: What do I need to do for ACPI vs. APM vs. etc?
-
-Drivers need not be aware of the specific power management
-technology that is active.  They just need to be aware
-of when the overlying power management system requests
-that they suspend or resume.
-
-Q: What about device dependencies?
-
-When a driver registers a device, the power management
-subsystem uses the information provided to build a
-tree of device dependencies (eg. USB device X is on
-USB controller Y which is on PCI bus Z)  When power
-management wants to suspend a device, it first sends
-a suspend request to its driver, then the bus driver,
-and so on up to the system bus.  Device resumes
-proceed in the opposite direction.
-
-Q: Who do I contact for additional information about
-   enabling power management for my specific driver/device?
-
-ACPI Development mailing list: linux-acpi@vger.kernel.org
-
-System Interface -- OBSOLETE, DO NOT USE!
-----------------*************************
-If you are providing new power management support to Linux (ie.
-adding support for something like APM or ACPI), you should
-communicate with drivers through the existing generic power
-management interface.
-
-/*
- * Send a request to all devices
- *
- * Parameters:
- *   rqst - request type
- *   data - data, if any, associated with the request
- *
- * Returns: 0 if the request is successful
- *          See "pm_callback" return for errors
- *
- * Details: Walk list of registered devices and call pm_send
- *          for each until complete or an error is encountered.
- *          If an error is encountered for a suspend request,
- *          return all devices to the state they were in before
- *          the suspend request.
- */
-int pm_send_all(pm_request_t rqst, void *data);
-
-/*
- * Find a matching device
- *
- * Parameters:
- *   type - device type (PCI device, system device, or 0 to match all devices)
- *   from - previous match or NULL to start from the beginning
- *
- * Returns: Matching device or NULL if none found
- */
-struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/pm.txt
@@ -0,0 +1,257 @@
+               Linux Power Management Support
+
+This document briefly describes how to use power management with your
+Linux system and how to add power management support to Linux drivers.
+
+APM or ACPI?
+------------
+If you have a relatively recent x86 mobile, desktop, or server system,
+odds are it supports either Advanced Power Management (APM) or
+Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
+of the two technologies and puts power management in the hands of the
+operating system, allowing for more intelligent power management than
+is possible with BIOS controlled APM.
+
+The best way to determine which, if either, your system supports is to
+build a kernel with both ACPI and APM enabled (as of 2.3.x ACPI is
+enabled by default).  If a working ACPI implementation is found, the
+ACPI driver will override and disable APM, otherwise the APM driver
+will be used.
+
+No, sorry, you cannot have both ACPI and APM enabled and running at
+once.  Some people with broken ACPI or broken APM implementations
+would like to use both to get a full set of working features, but you
+simply cannot mix and match the two.  Only one power management
+interface can be in control of the machine at once.  Think about it..
+
+User-space Daemons
+------------------
+Both APM and ACPI rely on user-space daemons, apmd and acpid
+respectively, to be completely functional.  Obtain both of these
+daemons from your Linux distribution or from the Internet (see below)
+and be sure that they are started sometime in the system boot process.
+Go ahead and start both.  If ACPI or APM is not available on your
+system the associated daemon will exit gracefully.
+
+  apmd:   http://worldvisions.ca/~apenwarr/apmd/
+  acpid:  http://acpid.sf.net/
+
+Driver Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+
+Note: pm_register(), pm_access(), pm_dev_idle() and friends are
+obsolete. Please do not use them. Instead you should properly hook
+your driver into the driver model, and use its suspend()/resume()
+callbacks to do this kind of stuff.
+
+If you are writing a new driver or maintaining an old driver, it
+should include power management support.  Without power management
+support, a single driver may prevent a system with power management
+capabilities from ever being able to suspend (safely).
+
+Overview:
+1) Register each instance of a device with "pm_register"
+2) Call "pm_access" before accessing the hardware.
+   (this will ensure that the hardware is awake and ready)
+3) Your "pm_callback" is called before going into a
+   suspend state (ACPI D1-D3) or after resuming (ACPI D0)
+   from a suspend.
+4) Call "pm_dev_idle" when the device is not being used
+   (optional but will improve device idle detection)
+5) When unloaded, unregister the device with "pm_unregister"
+
+/*
+ * Description: Register a device with the power-management subsystem
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, ...)
+ *   id - instance number or unique identifier
+ *   cback - request handler callback (suspend, resume, ...)
+ *
+ * Returns: Registered PM device or NULL on error
+ *
+ * Examples:
+ *   dev = pm_register(PM_SYS_DEV, PM_SYS_VGA, vga_callback);
+ *
+ *   struct pci_dev *pci_dev = pci_find_dev(...);
+ *   dev = pm_register(PM_PCI_DEV, PM_PCI_ID(pci_dev), callback);
+ */
+struct pm_dev *pm_register(pm_dev_t type, unsigned long id, pm_callback cback);
+
+/*
+ * Description: Unregister a device with the power management subsystem
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ */
+void pm_unregister(struct pm_dev *dev);
+
+/*
+ * Description: Unregister all devices with a matching callback function
+ *
+ * Parameters:
+ *   cback - previously registered request callback
+ *
+ * Notes: Provided for easier porting from old APM interface
+ */
+void pm_unregister_all(pm_callback cback);
+
+/*
+ * Power management request callback
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          EINVAL if the request is not supported
+ *          EBUSY if the device is now busy and cannot handle the request
+ *          ENOMEM if the device was unable to handle the request due to memory
+ *
+ * Details: The device request callback will be called before the
+ *          device/system enters a suspend state (ACPI D1-D3) or
+ *          or after the device/system resumes from suspend (ACPI D0).
+ *          For PM_SUSPEND, the ACPI D-state being entered is passed
+ *          as the "data" argument to the callback.  The device
+ *          driver should save (PM_SUSPEND) or restore (PM_RESUME)
+ *          device context when the request callback is called.
+ *
+ *          Once a driver returns 0 (success) from a suspend
+ *          request, it should not process any further requests or
+ *          access the device hardware until a call to "pm_access" is made.
+ */
+typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
+
+Driver Details
+--------------
+This is just a quick Q&A as a stopgap until a real driver writers'
+power management guide is available.
+
+Q: When is a device suspended?
+
+Devices can be suspended based on direct user request (eg. laptop lid
+closes), system power policy (eg.  sleep after 30 minutes of console
+inactivity), or device power policy (eg. power down device after 5
+minutes of inactivity)
+
+Q: Must a driver honor a suspend request?
+
+No, a driver can return -EBUSY from a suspend request and this
+will stop the system from suspending.  When a suspend request
+fails, all suspended devices are resumed and the system continues
+to run.  Suspend can be retried at a later time.
+
+Q: Can the driver block suspend/resume requests?
+
+Yes, a driver can delay its return from a suspend or resume
+request until the device is ready to handle requests.  It
+is advantageous to return as quickly as possible from a
+request as suspend/resume are done serially.
+
+Q: What context is a suspend/resume initiated from?
+
+A suspend or resume is initiated from a kernel thread context.
+It is safe to block, allocate memory, initiate requests
+or anything else you can do within the kernel.
+
+Q: Will requests continue to arrive after a suspend?
+
+Possibly.  It is the driver's responsibility to queue(*),
+fail, or drop any requests that arrive after returning
+success to a suspend request.  It is important that the
+driver not access its device until after it receives
+a resume request as the device's bus may no longer
+be active.
+
+(*) If a driver queues requests for processing after
+    resume be aware that the device, network, etc.
+    might be in a different state than at suspend time.
+    It's probably better to drop requests unless
+    the driver is a storage device.
+
+Q: Do I have to manage bus-specific power management registers
+
+No.  It is the responsibility of the bus driver to manage
+PCI, USB, etc. power management registers.  The bus driver
+or the power management subsystem will also enable any
+wake-on functionality that the device has.
+
+Q: So, really, what do I need to do to support suspend/resume?
+
+You need to save any device context that would
+be lost if the device was powered off and then restore
+it at resume time.  When ACPI is active, there are
+three levels of device suspend states; D1, D2, and D3.
+(The suspend state is passed as the "data" argument
+to the device callback.)  With D3, the device is powered
+off and loses all context, D1 and D2 are shallower power
+states and require less device context to be saved.  To
+play it safe, just save everything at suspend and restore
+everything at resume.
+
+Q: Where do I store device context for suspend?
+
+Anywhere in memory, kmalloc a buffer or store it
+in the device descriptor.  You are guaranteed that the
+contents of memory will be restored and accessible
+before resume, even when the system suspends to disk.
+
+Q: What do I need to do for ACPI vs. APM vs. etc?
+
+Drivers need not be aware of the specific power management
+technology that is active.  They just need to be aware
+of when the overlying power management system requests
+that they suspend or resume.
+
+Q: What about device dependencies?
+
+When a driver registers a device, the power management
+subsystem uses the information provided to build a
+tree of device dependencies (eg. USB device X is on
+USB controller Y which is on PCI bus Z)  When power
+management wants to suspend a device, it first sends
+a suspend request to its driver, then the bus driver,
+and so on up to the system bus.  Device resumes
+proceed in the opposite direction.
+
+Q: Who do I contact for additional information about
+   enabling power management for my specific driver/device?
+
+ACPI Development mailing list: linux-acpi@vger.kernel.org
+
+System Interface -- OBSOLETE, DO NOT USE!
+----------------*************************
+If you are providing new power management support to Linux (ie.
+adding support for something like APM or ACPI), you should
+communicate with drivers through the existing generic power
+management interface.
+
+/*
+ * Send a request to all devices
+ *
+ * Parameters:
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          See "pm_callback" return for errors
+ *
+ * Details: Walk list of registered devices and call pm_send
+ *          for each until complete or an error is encountered.
+ *          If an error is encountered for a suspend request,
+ *          return all devices to the state they were in before
+ *          the suspend request.
+ */
+int pm_send_all(pm_request_t rqst, void *data);
+
+/*
+ * Find a matching device
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, or 0 to match all devices)
+ *   from - previous match or NULL to start from the beginning
+ *
+ * Returns: Matching device or NULL if none found
+ */
+struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);
--- lin2625-rc5g2-kdoc.orig/Documentation/pm_qos_interface.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-PM quality of Service interface.
-
-This interface provides a kernel and user mode interface for registering
-performance expectations by drivers, subsystems and user space applications on
-one of the parameters.
-
-Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
-initial set of pm_qos parameters.
-
-The infrastructure exposes multiple misc device nodes one per implemented
-parameter.  The set of parameters implement is defined by pm_qos_power_init()
-and pm_qos_params.h.  This is done because having the available parameters
-being runtime configurable or changeable from a driver was seen as too easy to
-abuse.
-
-For each parameter a list of performance requirements is maintained along with
-an aggregated target value.  The aggregated target value is updated with
-changes to the requirement list or elements of the list.  Typically the
-aggregated target value is simply the max or min of the requirement values held
-in the parameter list elements.
-
-From kernel mode the use of this interface is simple:
-pm_qos_add_requirement(param_id, name, target_value):
-Will insert a named element in the list for that identified PM_QOS parameter
-with the target value.  Upon change to this list the new target is recomputed
-and any registered notifiers are called only if the target value is now
-different.
-
-pm_qos_update_requirement(param_id, name, new_target_value):
-Will search the list identified by the param_id for the named list element and
-then update its target value, calling the notification tree if the aggregated
-target is changed.  with that name is already registered.
-
-pm_qos_remove_requirement(param_id, name):
-Will search the identified list for the named element and remove it, after
-removal it will update the aggregate target and call the notification tree if
-the target was changed as a result of removing the named requirement.
-
-
-From user mode:
-Only processes can register a pm_qos requirement.  To provide for automatic
-cleanup for process the interface requires the process to register its
-parameter requirements in the following way:
-
-To register the default pm_qos target for the specific parameter, the process
-must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
-
-As long as the device node is held open that process has a registered
-requirement on the parameter.  The name of the requirement is "process_<PID>"
-derived from the current->pid from within the open system call.
-
-To change the requested target value the process needs to write a s32 value to
-the open device node.  This translates to a pm_qos_update_requirement call.
-
-To remove the user mode request for a target value simply close the device
-node.
-
-
-
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/pm_qos_interface.txt
@@ -0,0 +1,59 @@
+PM quality of Service interface.
+
+This interface provides a kernel and user mode interface for registering
+performance expectations by drivers, subsystems and user space applications on
+one of the parameters.
+
+Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
+initial set of pm_qos parameters.
+
+The infrastructure exposes multiple misc device nodes one per implemented
+parameter.  The set of parameters implement is defined by pm_qos_power_init()
+and pm_qos_params.h.  This is done because having the available parameters
+being runtime configurable or changeable from a driver was seen as too easy to
+abuse.
+
+For each parameter a list of performance requirements is maintained along with
+an aggregated target value.  The aggregated target value is updated with
+changes to the requirement list or elements of the list.  Typically the
+aggregated target value is simply the max or min of the requirement values held
+in the parameter list elements.
+
+From kernel mode the use of this interface is simple:
+pm_qos_add_requirement(param_id, name, target_value):
+Will insert a named element in the list for that identified PM_QOS parameter
+with the target value.  Upon change to this list the new target is recomputed
+and any registered notifiers are called only if the target value is now
+different.
+
+pm_qos_update_requirement(param_id, name, new_target_value):
+Will search the list identified by the param_id for the named list element and
+then update its target value, calling the notification tree if the aggregated
+target is changed.  with that name is already registered.
+
+pm_qos_remove_requirement(param_id, name):
+Will search the identified list for the named element and remove it, after
+removal it will update the aggregate target and call the notification tree if
+the target was changed as a result of removing the named requirement.
+
+
+From user mode:
+Only processes can register a pm_qos requirement.  To provide for automatic
+cleanup for process the interface requires the process to register its
+parameter requirements in the following way:
+
+To register the default pm_qos target for the specific parameter, the process
+must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
+
+As long as the device node is held open that process has a registered
+requirement on the parameter.  The name of the requirement is "process_<PID>"
+derived from the current->pid from within the open system call.
+
+To change the requested target value the process needs to write a s32 value to
+the open device node.  This translates to a pm_qos_update_requirement call.
+
+To remove the user mode request for a target value simply close the device
+node.
+
+
+
--- /dev/null
+++ lin2625-rc5g2-kdoc/Documentation/power/power_supply_class.txt
@@ -0,0 +1,169 @@
+Linux power supply class
+========================
+
+Synopsis
+~~~~~~~~
+Power supply class used to represent battery, UPS, AC or DC power supply
+properties to user-space.
+
+It defines core set of attributes, which should be applicable to (almost)
+every power supply out there. Attributes are available via sysfs and uevent
+interfaces.
+
+Each attribute has well defined meaning, up to unit of measure used. While
+the attributes provided are believed to be universally applicable to any
+power supply, specific monitoring hardware may not be able to provide them
+all, so any of them may be skipped.
+
+Power supply class is extensible, and allows to define drivers own attributes.
+The core attribute set is subject to the standard Linux evolution (i.e.
+if it will be found that some attribute is applicable to many power supply
+types or their drivers, it can be added to the core set).
+
+It also integrates with LED framework, for the purpose of providing
+typically expected feedback of battery charging/fully charged status and
+AC/USB power supply online status. (Note that specific details of the
+indication (including whether to use it at all) are fully controllable by
+user and/or specific machine defaults, per design principles of LED
+framework).
+
+
+Attributes/properties
+~~~~~~~~~~~~~~~~~~~~~
+Power supply class has predefined set of attributes, this eliminates code
+duplication across drivers. Power supply class insist on reusing its
+predefined attributes *and* their units.
+
+So, userspace gets predictable set of attributes and their units for any
+kind of power supply, and can process/present them to a user in consistent
+manner. Results for different power supplies and machines are also directly
+comparable.
+
+See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
+example how to declare and handle attributes.
+
+
+Units
+~~~~~
+Quoting include/linux/power_supply.h:
+
+  All voltages, currents, charges, energies, time and temperatures in µV,
+  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
+  stated. It's driver's job to convert its raw values to units in which
+  this class operates.
+
+
+Attributes/properties detailed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
+~                                                                       ~
+~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
+~ of battery, this class distinguish these terms. Don't mix them!       ~
+~                                                                       ~
+~ CHARGE_* attributes represents capacity in µAh only.                  ~
+~ ENERGY_* attributes represents capacity in µWh only.                  ~
+~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
+~                                                                       ~
+~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+
+Postfixes:
+_AVG - *hardware* averaged value, use it if your hardware is really able to
+report averaged values.
+_NOW - momentary/instantaneous values.
+
+STATUS - this attribute represents operating status (charging, full,
+discharging (i.e. powering a load), etc.). This corresponds to
+BATTERY_STATUS_* values, as defined in battery.h.
+
+HEALTH - represents health of the battery, values corresponds to
+POWER_SUPPLY_HEALTH_*, defined in battery.h.
+
+VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
+minimal power supply voltages. Maximal/minimal means values of voltages
+when battery considered "full"/"empty" at normal conditions. Yes, there is
+no direct relation between voltage and battery capacity, but some dumb
+batteries use voltage for very approximated calculation of capacity.
+Battery driver also can use this attribute just to inform userspace
+about maximal and minimal voltage thresholds of a given battery.
+
+VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
+these ones should be used if hardware could only guess (measure and
+retain) the thresholds of a given power supply.
+
+CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
+battery considered full/empty.
+
+ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
+
+CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
+of charge when battery became full/empty". It also could mean "value of
+charge when battery considered full/empty at given conditions (temperature,
+age)". I.e. these attributes represents real thresholds, not design values.
+
+ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
+
+CAPACITY - capacity in percents.
+
+TEMP - temperature of the power supply.
+TEMP_AMBIENT - ambient temperature.
+
+TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
+while battery powers a load)
+TIME_TO_FULL - seconds left for battery to be considered full (i.e.
+while battery is charging)
+
+
+Battery <-> external power supply interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Often power supplies are acting as supplies and supplicants at the same
+time. Batteries are good example. So, batteries usually care if they're
+externally powered or not.
+
+For that case, power supply class implements notification mechanism for
+batteries.
+
+External power supply (AC) lists supplicants (batteries) names in
+"supplied_to" struct member, and each power_supply_changed() call
+issued by external power supply will notify supplicants via
+external_power_changed callback.
+
+
+QA
+~~
+Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
+A: If you cannot find attribute suitable for your driver needs, feel free
+   to add it and send patch along with your driver.
+
+   The attributes available currently are the ones currently provided by the
+   drivers written.
+
+   Good candidates to add in future: model/part#, cycle_time, manufacturer,
+   etc.
+
+
+Q: I have some very specific attribute (e.g. battery color), should I add
+   this attribute to standard ones?
+A: Most likely, no. Such attribute can be placed in the driver itself, if
+   it is useful. Of course, if the attribute in question applicable to
+   large set of batteries, provided by many drivers, and/or comes from
+   some general battery specification/standard, it may be a candidate to
+   be added to the core attribute set.
+
+
+Q: Suppose, my battery monitoring chip/firmware does not provides capacity
+   in percents, but provides charge_{now,full,empty}. Should I calculate
+   percentage capacity manually, inside the driver, and register CAPACITY
+   attribute? The same question about time_to_empty/time_to_full.
+A: Most likely, no. This class is designed to export properties which are
+   directly measurable by the specific hardware available.
+
+   Inferring not available properties using some heuristics or mathematical
+   model is not subject of work for a battery driver. Such functionality
+   should be factored out, and in fact, apm_power, the driver to serve
+   legacy APM API on top of power supply class, uses a simple heuristic of
+   approximating remaining battery capacity based on its charge, current,
+   voltage and so on. But full-fledged battery model is likely not subject
+   for kernel at all, as it would require floating point calculation to deal
+   with things like differential equations and Kalman filters. This is
+   better be handled by batteryd/libbattery, yet to be written.
--- lin2625-rc5g2-kdoc.orig/Documentation/power_supply_class.txt
+++ /dev/null
@@ -1,169 +0,0 @@
-Linux power supply class
-========================
-
-Synopsis
-~~~~~~~~
-Power supply class used to represent battery, UPS, AC or DC power supply
-properties to user-space.
-
-It defines core set of attributes, which should be applicable to (almost)
-every power supply out there. Attributes are available via sysfs and uevent
-interfaces.
-
-Each attribute has well defined meaning, up to unit of measure used. While
-the attributes provided are believed to be universally applicable to any
-power supply, specific monitoring hardware may not be able to provide them
-all, so any of them may be skipped.
-
-Power supply class is extensible, and allows to define drivers own attributes.
-The core attribute set is subject to the standard Linux evolution (i.e.
-if it will be found that some attribute is applicable to many power supply
-types or their drivers, it can be added to the core set).
-
-It also integrates with LED framework, for the purpose of providing
-typically expected feedback of battery charging/fully charged status and
-AC/USB power supply online status. (Note that specific details of the
-indication (including whether to use it at all) are fully controllable by
-user and/or specific machine defaults, per design principles of LED
-framework).
-
-
-Attributes/properties
-~~~~~~~~~~~~~~~~~~~~~
-Power supply class has predefined set of attributes, this eliminates code
-duplication across drivers. Power supply class insist on reusing its
-predefined attributes *and* their units.
-
-So, userspace gets predictable set of attributes and their units for any
-kind of power supply, and can process/present them to a user in consistent
-manner. Results for different power supplies and machines are also directly
-comparable.
-
-See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
-example how to declare and handle attributes.
-
-
-Units
-~~~~~
-Quoting include/linux/power_supply.h:
-
-  All voltages, currents, charges, energies, time and temperatures in µV,
-  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
-  stated. It's driver's job to convert its raw values to units in which
-  this class operates.
-
-
-Attributes/properties detailed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-~ ~ ~ ~ ~ ~ ~  Charge/Energy/Capacity - how to not confuse  ~ ~ ~ ~ ~ ~ ~
-~                                                                       ~
-~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity"  ~
-~ of battery, this class distinguish these terms. Don't mix them!       ~
-~                                                                       ~
-~ CHARGE_* attributes represents capacity in µAh only.                  ~
-~ ENERGY_* attributes represents capacity in µWh only.                  ~
-~ CAPACITY attribute represents capacity in *percents*, from 0 to 100.  ~
-~                                                                       ~
-~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
-
-Postfixes:
-_AVG - *hardware* averaged value, use it if your hardware is really able to
-report averaged values.
-_NOW - momentary/instantaneous values.
-
-STATUS - this attribute represents operating status (charging, full,
-discharging (i.e. powering a load), etc.). This corresponds to
-BATTERY_STATUS_* values, as defined in battery.h.
-
-HEALTH - represents health of the battery, values corresponds to
-POWER_SUPPLY_HEALTH_*, defined in battery.h.
-
-VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
-minimal power supply voltages. Maximal/minimal means values of voltages
-when battery considered "full"/"empty" at normal conditions. Yes, there is
-no direct relation between voltage and battery capacity, but some dumb
-batteries use voltage for very approximated calculation of capacity.
-Battery driver also can use this attribute just to inform userspace
-about maximal and minimal voltage thresholds of a given battery.
-
-VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
-these ones should be used if hardware could only guess (measure and
-retain) the thresholds of a given power supply.
-
-CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
-battery considered full/empty.
-
-ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
-
-CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
-of charge when battery became full/empty". It also could mean "value of
-charge when battery considered full/empty at given conditions (temperature,
-age)". I.e. these attributes represents real thresholds, not design values.
-
-ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
-
-CAPACITY - capacity in percents.
-
-TEMP - temperature of the power supply.
-TEMP_AMBIENT - ambient temperature.
-
-TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
-while battery powers a load)
-TIME_TO_FULL - seconds left for battery to be considered full (i.e.
-while battery is charging)
-
-
-Battery <-> external power supply interaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Often power supplies are acting as supplies and supplicants at the same
-time. Batteries are good example. So, batteries usually care if they're
-externally powered or not.
-
-For that case, power supply class implements notification mechanism for
-batteries.
-
-External power supply (AC) lists supplicants (batteries) names in
-"supplied_to" struct member, and each power_supply_changed() call
-issued by external power supply will notify supplicants via
-external_power_changed callback.
-
-
-QA
-~~
-Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
-A: If you cannot find attribute suitable for your driver needs, feel free
-   to add it and send patch along with your driver.
-
-   The attributes available currently are the ones currently provided by the
-   drivers written.
-
-   Good candidates to add in future: model/part#, cycle_time, manufacturer,
-   etc.
-
-
-Q: I have some very specific attribute (e.g. battery color), should I add
-   this attribute to standard ones?
-A: Most likely, no. Such attribute can be placed in the driver itself, if
-   it is useful. Of course, if the attribute in question applicable to
-   large set of batteries, provided by many drivers, and/or comes from
-   some general battery specification/standard, it may be a candidate to
-   be added to the core attribute set.
-
-
-Q: Suppose, my battery monitoring chip/firmware does not provides capacity
-   in percents, but provides charge_{now,full,empty}. Should I calculate
-   percentage capacity manually, inside the driver, and register CAPACITY
-   attribute? The same question about time_to_empty/time_to_full.
-A: Most likely, no. This class is designed to export properties which are
-   directly measurable by the specific hardware available.
-
-   Inferring not available properties using some heuristics or mathematical
-   model is not subject of work for a battery driver. Such functionality
-   should be factored out, and in fact, apm_power, the driver to serve
-   legacy APM API on top of power supply class, uses a simple heuristic of
-   approximating remaining battery capacity based on its charge, current,
-   voltage and so on. But full-fledged battery model is likely not subject
-   for kernel at all, as it would require floating point calculation to deal
-   with things like differential equations and Kalman filters. This is
-   better be handled by batteryd/libbattery, yet to be written.
--- lin2625-rc5g2-kdoc.orig/arch/x86/Kconfig
+++ lin2625-rc5g2-kdoc/arch/x86/Kconfig
@@ -1259,7 +1259,7 @@ menuconfig APM
 	  machines with more than one CPU.
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- lin2625-rc5g2-kdoc.orig/kernel/power/Kconfig
+++ lin2625-rc5g2-kdoc/kernel/power/Kconfig
@@ -190,7 +190,7 @@ config APM_EMULATION
 	  notification of APM "events" (e.g. battery status change).
 
 	  In order to use APM, you will need supporting software. For location
-	  and more information, read <file:Documentation/pm.txt> and the
+	  and more information, read <file:Documentation/power/pm.txt> and the
 	  Battery Powered Linux mini-HOWTO, available from
 	  <http://www.tldp.org/docs.html#howto>.
 
--- lin2625-rc5g2-kdoc.orig/Documentation/kernel-parameters.txt
+++ lin2625-rc5g2-kdoc/Documentation/kernel-parameters.txt
@@ -138,7 +138,7 @@ and is between 256 and 4096 characters. 
 			strict -- Be less tolerant of platforms that are not
 				strictly ACPI specification compliant.
 
-			See also Documentation/pm.txt, pci=noacpi
+			See also Documentation/power/pm.txt, pci=noacpi
 
 	acpi_apic_instance=	[ACPI, IOAPIC]
 			Format: <int>

Re: [linux-pm] [PATCH] doc/power: move power-related files to Documentation/power/

[Len Brown]

On Wednesday 12 March 2008, Randy Dunlap wrote:
> On Wed, 12 Mar 2008 17:49:37 -0400 Len Brown wrote:
> 
> > On Wednesday 12 March 2008, Randy Dunlap wrote:
> > > On Wed, 12 Mar 2008 16:00:45 -0400 Len Brown wrote:
> > > 
> > > > linus top of tree.  i was wrong that it was already gone,
> > > > i guess i assumed that since it had 1 hunk and patch
> > > > told me the hunk was reversed i assumed that part
> > > > had been applied already.
> > > 
> > > Can you try the patch below?
> > > It works_for_me but that doesn't give me lots of confidence.
> > > 
> > > ---
> ...
> > > 
> > 
> > not better
> > 
> > Please send it to me as an attachment,
> > maybe kmail is getting confused b/c this text has non ascii characters?
> > 
> > (does this patch apply for anybody else?)
> 
> OK, attached.

the attachment worked.
i guess the problem was something to do with the non-ascii characters
in that document file.

i use kmail for about 18 months b/c it seems to handle both plain text
and attachments.
This is the first issue I've had with it (though I did
recently change to the kmail that comes with FC8 from
the old version that camem with opensuse 10.2)

thanks,
-Len