Linux Power Management Support（内核中pm.txt的翻译)

LinuxSmartphone

Linux Power Management Support
Linux电源管理支持

翻译：王仲俊  email:wzhjbj@sohu.com

This document briefly describes how to use power management with your Linux system and how to add power management support to Linux drivers.
这份文档简要地阐述了在你的linux系统中如何使用电源管理和如何在linux驱动中添加电源管理支持。

APM or ACPI?
APM或是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.
------------如果你近来有相关的x86移动、台式或是服务器系统，（那么你会发现）几乎是它不是支持Advanced Power Management (APM高级电源管理)就是Advanced Configuration and Power Interface (ACPI高级结构和电源接口)。ACPI在两种技术中是较新的，它将电源管理放到了操作系统一面，相对于可能是BIOS控制的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.
如果哪个都支持，决定使用哪种（电源管理方式）最好的方法是，你在编译内核时将ACPI和APM都激活。（这样），如果发现ACPI设备开始工作，ACPI驱动会被优先执行，APM被禁止，否则，APM驱动将被使用。

No sorry, you can not 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 can not mix and match the two.  Only one power management interface can be in control of the machine at once.  Think about it..
不，对不起，你不能同时将ACPI和APM使能和运行。有些人有损坏的ACPI或是APM设备，（这样）将来将会同时使用ACPI和APM来获取全面的工作机制，但你不能简单的在（ACPI和APM）两者之间混淆和竞争。在同一时间，只有一个电源管理接口可以控制这个设备。请考虑这一点。

User-space Daemons
用户空间的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/

-----------------APM和ACPI都要依赖用户空间的daemon程序，分别是apmd和acpid，功能才会完整。从你的linux发行商或是Inter网（如下网址）获取这些daemons，确信它们在系统启动的过程中已经被启动。如果你的系统地ACPI或是APM是不可用的，相应的daemon程序将会自动友好的退出。
  apmd:   
http://worldvisions.ca/~apenwarr/apmd/
  acpid:  
http://acpid.sf.net/


Driver Interface
驱动接口

---------------- 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).
----------------如果你正在写一个新的驱动或是修改一个旧的驱动，它应当包含有电源管理的支持。没有电源管理的支持，一个简单的驱动就有可能阻止系统suspend状态安全的恢复过来。

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"
综述：1）通过"pm_register"注册每种情况的设备。2）在访问硬件前调用"pm_access"（这样可以保证硬件处于唤醒和等待状态）。3）你的"pm_callback"在进入suspend状态（ACPI D1-D3）之前或是在从suspend状态resuming（恢复）之后被调用（ACPI D0）。4）在设备处于不使用状态时调用"pm_dev_idle"。（可选，今后将改善设备空闲探测）5）当unloaded、unregister设备时调用"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);
/*
* Device idle/use detection
*
* In general, drivers for all devices should call "pm_access"
* before accessing the hardware (ie. before reading or modifying
* a hardware register).  Request or packet-driven drivers should
* additionally call "pm_dev_idle" when a device is not being used.
*
* Examples:
* 1) A keyboard driver would call pm_access whenever a key is pressed
* 2) A network driver would call pm_access before submitting
*    a packet for transmit or receive and pm_dev_idle when its
*    transfer and receive queues are empty.
* 3) A VGA driver would call pm_access before it accesses any
*    of the video controller registers
*
* Ultimately, the PM policy manager uses the access and idle
* information to decide when to suspend individual devices
* or when to suspend the entire system
*/
/*
* Description: Update device access time and wake up device, if necessary
*
* Parameters:
*   dev - PM device previously returned from pm_register
*
* Details: If called from an interrupt handler pm_access updates
*          access time but should never need to wake up the device
*          (if device is generating interrupts, it should be awake
*          already)  This is important as we can not wake up
*          devices from an interrupt handler.
*/ void pm_access(struct pm_dev *dev);
/*
* Description: Identify device as currently being idle
*
* Parameters:
*   dev - PM device previously returned from pm_register
*
* Details: A call to pm_dev_idle might signal to the policy manager
*          to put a device to sleep.  If a new device request arrives
*          between the call to pm_dev_idle and the pm_callback
*          callback, the driver should fail the pm_callback request.
*/ void pm_dev_idle(struct pm_dev *dev);
/*
* 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 can not 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&A仅作权宜之策。

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:什么时候设备暂停？
设备可以基于用户请求（比如笔记本电脑盖合上），系统电源策略（譬如，控制台静止30分钟没有事件进入睡眠），或是设备电源策略（譬如，设备静止5分钟没有活动）被暂停。

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:一个驱动必须实现暂停请求吗？
不。驱动可以从暂停请求中返回-EBUSY，这样将会停止系统的暂停。当一个暂停请求失败，所有的暂停的设备被恢复，系统继续运行。在这之后的一段时间可以再次尝试暂停。

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:驱动可以堵塞暂停/恢复请求吗？
是的。驱动可延缓从一个暂停或是恢复请求的返回，直到设备准备好处理请求。这对于尽可能快的从连续处理的暂停/恢复请求中返回是有利的。

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:在什么环境下初始化一个暂停/恢复？
一个suspend或是resume是从一个内核线程环境中被初始化的。在内核中它可以安全的执行堵塞，分配内存，初始化请求或是任何你可以做的事。

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:在suspend之后还会有请求到达吗？
有可能。Queuw(*)-排队、舍弃或是撤销（处理）在suspend请求返回成功之后到达的请求是驱动的职责。在设备总线不再活跃时驱动不应去访问它的设备，直到它收到resume请求，这非常重要。如果驱动queues请求在设备、网络等从也许不同于suspend时的状态中唤醒恢复后需要处理，也许最好的方式是撤销这个请求，除非是存储设备的驱动。

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:我可以去管理bus-specific（特殊总线）电源管理寄存器吗？
不行。管理PCI、USB等的电源管理寄存器是总线驱动的职责。总线驱动或是电源管理子系统将同样对设备所拥有的任何唤醒商店功能使能。

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:那事实上支持suspend/resume我需要做些什么呢？
你必须在设备掉电之前将设备的环境状态保存好，否则会丢失，再在恢复时还原。当ACPI工作活跃时，设备的suspend状态有三种；D1，D2和D3（suspend状态以“data”参数的形式传递给设备回调函数）。D3，设备掉电并丢失所有环境状态。D1和D2是较浅的电源状态，需要保存的设备状态较少。为了安全运行，应该在suspend时保存所有的东西，并在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:我在哪儿存放设备的suspend的环境状态？
内存的任何地方，kmalloc一个buffer或是存储在设备的描述符中。你必须保证即使是disk也suspend时resume之前内存中的这些内容能被完好的恢复。

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:对于ACPI、APM等我需要做些什么呢？
驱动不需要主动地知道特定的电源管理技术。它们只需要知道什么时候电源管理系统上需要它们的suspend或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:设备依赖是什么意思？
当驱动注册一个设备时，电源管理子系统就会以这些信息为条件创建一个设备依赖树（比方说，USB设备X在USB控制器Y上，而USB控制器Y又在PCI总线Z上）。当电源管理想suspend一个设备时，它首先发送一个suspend请求到驱动，然后发一个suspend请求到驱动总线，再是向上到系统总线。设备resume处理正好反方向进行。

Q: Who do I contact for additional information about enabling power management for my specific driver/device?
ACPI Development mailing list:
acpi-devel@lists.sourceforge.net
Q:在我要为我的特定驱动/设备添加启动电源管理信息时，我该和谁联系？
ACPI开发邮件列表:
acpi-devel@lists.sourceforge.net

System Interface
系统接口

---------------- 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.
----------------如果你要在linux中添加新的电源管理支持（比方说添加一些像APM或是ACPI的支持），你应该保持驱动和现有的电源管理模块接口的通讯。

/*
* Send a request to a single device
*
* Parameters:
*   dev - PM device previously returned from pm_register or pm_find
*   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: Forward request to device callback and, if a suspend
*          or resume request, update the pm_dev "state" field
*          appropriately
*/ int pm_send(struct pm_dev *dev, pm_request_t rqst, void *data);
/*
* 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);


本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u2/66024/showart_547931.html