home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / pm.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  18.0 KB  |  446 lines
  1. /*
  2.  *  pm.h - Power management interface
  3.  *
  4.  *  Copyright (C) 2000 Andrew Henroid
  5.  *
  6.  *  This program is free software; you can redistribute it and/or modify
  7.  *  it under the terms of the GNU General Public License as published by
  8.  *  the Free Software Foundation; either version 2 of the License, or
  9.  *  (at your option) any later version.
  10.  *
  11.  *  This program is distributed in the hope that it will be useful,
  12.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  *  GNU General Public License for more details.
  15.  *
  16.  *  You should have received a copy of the GNU General Public License
  17.  *  along with this program; if not, write to the Free Software
  18.  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19.  */
  20.  
  21. #ifndef _LINUX_PM_H
  22. #define _LINUX_PM_H
  23.  
  24. #include <linux/list.h>
  25.  
  26. /*
  27.  * Callbacks for platform drivers to implement.
  28.  */
  29. extern void (*pm_idle)(void);
  30. extern void (*pm_power_off)(void);
  31. extern void (*pm_power_off_prepare)(void);
  32.  
  33. /*
  34.  * Device power management
  35.  */
  36.  
  37. struct device;
  38.  
  39. typedef struct pm_message {
  40.     int event;
  41. } pm_message_t;
  42.  
  43. /**
  44.  * struct pm_ops - device PM callbacks
  45.  *
  46.  * Several driver power state transitions are externally visible, affecting
  47.  * the state of pending I/O queues and (for drivers that touch hardware)
  48.  * interrupts, wakeups, DMA, and other hardware state.  There may also be
  49.  * internal transitions to various low power modes, which are transparent
  50.  * to the rest of the driver stack (such as a driver that's ON gating off
  51.  * clocks which are not in active use).
  52.  *
  53.  * The externally visible transitions are handled with the help of the following
  54.  * callbacks included in this structure:
  55.  *
  56.  * @prepare: Prepare the device for the upcoming transition, but do NOT change
  57.  *    its hardware state.  Prevent new children of the device from being
  58.  *    registered after @prepare() returns (the driver's subsystem and
  59.  *    generally the rest of the kernel is supposed to prevent new calls to the
  60.  *    probe method from being made too once @prepare() has succeeded).  If
  61.  *    @prepare() detects a situation it cannot handle (e.g. registration of a
  62.  *    child already in progress), it may return -EAGAIN, so that the PM core
  63.  *    can execute it once again (e.g. after the new child has been registered)
  64.  *    to recover from the race condition.  This method is executed for all
  65.  *    kinds of suspend transitions and is followed by one of the suspend
  66.  *    callbacks: @suspend(), @freeze(), or @poweroff().
  67.  *    The PM core executes @prepare() for all devices before starting to
  68.  *    execute suspend callbacks for any of them, so drivers may assume all of
  69.  *    the other devices to be present and functional while @prepare() is being
  70.  *    executed.  In particular, it is safe to make GFP_KERNEL memory
  71.  *    allocations from within @prepare().  However, drivers may NOT assume
  72.  *    anything about the availability of the user space at that time and it
  73.  *    is not correct to request firmware from within @prepare() (it's too
  74.  *    late to do that).  [To work around this limitation, drivers may
  75.  *    register suspend and hibernation notifiers that are executed before the
  76.  *    freezing of tasks.]
  77.  *
  78.  * @complete: Undo the changes made by @prepare().  This method is executed for
  79.  *    all kinds of resume transitions, following one of the resume callbacks:
  80.  *    @resume(), @thaw(), @restore().  Also called if the state transition
  81.  *    fails before the driver's suspend callback (@suspend(), @freeze(),
  82.  *    @poweroff()) can be executed (e.g. if the suspend callback fails for one
  83.  *    of the other devices that the PM core has unsuccessfully attempted to
  84.  *    suspend earlier).
  85.  *    The PM core executes @complete() after it has executed the appropriate
  86.  *    resume callback for all devices.
  87.  *
  88.  * @suspend: Executed before putting the system into a sleep state in which the
  89.  *    contents of main memory are preserved.  Quiesce the device, put it into
  90.  *    a low power state appropriate for the upcoming system state (such as
  91.  *    PCI_D3hot), and enable wakeup events as appropriate.
  92.  *
  93.  * @resume: Executed after waking the system up from a sleep state in which the
  94.  *    contents of main memory were preserved.  Put the device into the
  95.  *    appropriate state, according to the information saved in memory by the
  96.  *    preceding @suspend().  The driver starts working again, responding to
  97.  *    hardware events and software requests.  The hardware may have gone
  98.  *    through a power-off reset, or it may have maintained state from the
  99.  *    previous suspend() which the driver may rely on while resuming.  On most
  100.  *    platforms, there are no restrictions on availability of resources like
  101.  *    clocks during @resume().
  102.  *
  103.  * @freeze: Hibernation-specific, executed before creating a hibernation image.
  104.  *    Quiesce operations so that a consistent image can be created, but do NOT
  105.  *    otherwise put the device into a low power device state and do NOT emit
  106.  *    system wakeup events.  Save in main memory the device settings to be
  107.  *    used by @restore() during the subsequent resume from hibernation or by
  108.  *    the subsequent @thaw(), if the creation of the image or the restoration
  109.  *    of main memory contents from it fails.
  110.  *
  111.  * @thaw: Hibernation-specific, executed after creating a hibernation image OR
  112.  *    if the creation of the image fails.  Also executed after a failing
  113.  *    attempt to restore the contents of main memory from such an image.
  114.  *    Undo the changes made by the preceding @freeze(), so the device can be
  115.  *    operated in the same way as immediately before the call to @freeze().
  116.  *
  117.  * @poweroff: Hibernation-specific, executed after saving a hibernation image.
  118.  *    Quiesce the device, put it into a low power state appropriate for the
  119.  *    upcoming system state (such as PCI_D3hot), and enable wakeup events as
  120.  *    appropriate.
  121.  *
  122.  * @restore: Hibernation-specific, executed after restoring the contents of main
  123.  *    memory from a hibernation image.  Driver starts working again,
  124.  *    responding to hardware events and software requests.  Drivers may NOT
  125.  *    make ANY assumptions about the hardware state right prior to @restore().
  126.  *    On most platforms, there are no restrictions on availability of
  127.  *    resources like clocks during @restore().
  128.  *
  129.  * All of the above callbacks, except for @complete(), return error codes.
  130.  * However, the error codes returned by the resume operations, @resume(),
  131.  * @thaw(), and @restore(), do not cause the PM core to abort the resume
  132.  * transition during which they are returned.  The error codes returned in
  133.  * that cases are only printed by the PM core to the system logs for debugging
  134.  * purposes.  Still, it is recommended that drivers only return error codes
  135.  * from their resume methods in case of an unrecoverable failure (i.e. when the
  136.  * device being handled refuses to resume and becomes unusable) to allow us to
  137.  * modify the PM core in the future, so that it can avoid attempting to handle
  138.  * devices that failed to resume and their children.
  139.  *
  140.  * It is allowed to unregister devices while the above callbacks are being
  141.  * executed.  However, it is not allowed to unregister a device from within any
  142.  * of its own callbacks.
  143.  */
  144.  
  145. struct pm_ops {
  146.     int (*prepare)(struct device *dev);
  147.     void (*complete)(struct device *dev);
  148.     int (*suspend)(struct device *dev);
  149.     int (*resume)(struct device *dev);
  150.     int (*freeze)(struct device *dev);
  151.     int (*thaw)(struct device *dev);
  152.     int (*poweroff)(struct device *dev);
  153.     int (*restore)(struct device *dev);
  154. };
  155.  
  156. /**
  157.  * struct pm_ext_ops - extended device PM callbacks
  158.  *
  159.  * Some devices require certain operations related to suspend and hibernation
  160.  * to be carried out with interrupts disabled.  Thus, 'struct pm_ext_ops' below
  161.  * is defined, adding callbacks to be executed with interrupts disabled to
  162.  * 'struct pm_ops'.
  163.  *
  164.  * The following callbacks included in 'struct pm_ext_ops' are executed with
  165.  * the nonboot CPUs switched off and with interrupts disabled on the only
  166.  * functional CPU.  They also are executed with the PM core list of devices
  167.  * locked, so they must NOT unregister any devices.
  168.  *
  169.  * @suspend_noirq: Complete the operations of ->suspend() by carrying out any
  170.  *    actions required for suspending the device that need interrupts to be
  171.  *    disabled
  172.  *
  173.  * @resume_noirq: Prepare for the execution of ->resume() by carrying out any
  174.  *    actions required for resuming the device that need interrupts to be
  175.  *    disabled
  176.  *
  177.  * @freeze_noirq: Complete the operations of ->freeze() by carrying out any
  178.  *    actions required for freezing the device that need interrupts to be
  179.  *    disabled
  180.  *
  181.  * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any
  182.  *    actions required for thawing the device that need interrupts to be
  183.  *    disabled
  184.  *
  185.  * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any
  186.  *    actions required for handling the device that need interrupts to be
  187.  *    disabled
  188.  *
  189.  * @restore_noirq: Prepare for the execution of ->restore() by carrying out any
  190.  *    actions required for restoring the operations of the device that need
  191.  *    interrupts to be disabled
  192.  *
  193.  * All of the above callbacks return error codes, but the error codes returned
  194.  * by the resume operations, @resume_noirq(), @thaw_noirq(), and
  195.  * @restore_noirq(), do not cause the PM core to abort the resume transition
  196.  * during which they are returned.  The error codes returned in that cases are
  197.  * only printed by the PM core to the system logs for debugging purposes.
  198.  * Still, as stated above, it is recommended that drivers only return error
  199.  * codes from their resume methods if the device being handled fails to resume
  200.  * and is not usable any more.
  201.  */
  202.  
  203. struct pm_ext_ops {
  204.     struct pm_ops base;
  205.     int (*suspend_noirq)(struct device *dev);
  206.     int (*resume_noirq)(struct device *dev);
  207.     int (*freeze_noirq)(struct device *dev);
  208.     int (*thaw_noirq)(struct device *dev);
  209.     int (*poweroff_noirq)(struct device *dev);
  210.     int (*restore_noirq)(struct device *dev);
  211. };
  212.  
  213. /**
  214.  * PM_EVENT_ messages
  215.  *
  216.  * The following PM_EVENT_ messages are defined for the internal use of the PM
  217.  * core, in order to provide a mechanism allowing the high level suspend and
  218.  * hibernation code to convey the necessary information to the device PM core
  219.  * code:
  220.  *
  221.  * ON        No transition.
  222.  *
  223.  * FREEZE     System is going to hibernate, call ->prepare() and ->freeze()
  224.  *        for all devices.
  225.  *
  226.  * SUSPEND    System is going to suspend, call ->prepare() and ->suspend()
  227.  *        for all devices.
  228.  *
  229.  * HIBERNATE    Hibernation image has been saved, call ->prepare() and
  230.  *        ->poweroff() for all devices.
  231.  *
  232.  * QUIESCE    Contents of main memory are going to be restored from a (loaded)
  233.  *        hibernation image, call ->prepare() and ->freeze() for all
  234.  *        devices.
  235.  *
  236.  * RESUME    System is resuming, call ->resume() and ->complete() for all
  237.  *        devices.
  238.  *
  239.  * THAW        Hibernation image has been created, call ->thaw() and
  240.  *        ->complete() for all devices.
  241.  *
  242.  * RESTORE    Contents of main memory have been restored from a hibernation
  243.  *        image, call ->restore() and ->complete() for all devices.
  244.  *
  245.  * RECOVER    Creation of a hibernation image or restoration of the main
  246.  *        memory contents from a hibernation image has failed, call
  247.  *        ->thaw() and ->complete() for all devices.
  248.  *
  249.  * The following PM_EVENT_ messages are defined for internal use by
  250.  * kernel subsystems.  They are never issued by the PM core.
  251.  *
  252.  * USER_SUSPEND        Manual selective suspend was issued by userspace.
  253.  *
  254.  * USER_RESUME        Manual selective resume was issued by userspace.
  255.  *
  256.  * REMOTE_WAKEUP    Remote-wakeup request was received from the device.
  257.  *
  258.  * AUTO_SUSPEND        Automatic (device idle) runtime suspend was
  259.  *            initiated by the subsystem.
  260.  *
  261.  * AUTO_RESUME        Automatic (device needed) runtime resume was
  262.  *            requested by a driver.
  263.  */
  264.  
  265. #define PM_EVENT_ON        0x0000
  266. #define PM_EVENT_FREEZE     0x0001
  267. #define PM_EVENT_SUSPEND    0x0002
  268. #define PM_EVENT_HIBERNATE    0x0004
  269. #define PM_EVENT_QUIESCE    0x0008
  270. #define PM_EVENT_RESUME        0x0010
  271. #define PM_EVENT_THAW        0x0020
  272. #define PM_EVENT_RESTORE    0x0040
  273. #define PM_EVENT_RECOVER    0x0080
  274. #define PM_EVENT_USER        0x0100
  275. #define PM_EVENT_REMOTE        0x0200
  276. #define PM_EVENT_AUTO        0x0400
  277.  
  278. #define PM_EVENT_SLEEP        (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
  279. #define PM_EVENT_USER_SUSPEND    (PM_EVENT_USER | PM_EVENT_SUSPEND)
  280. #define PM_EVENT_USER_RESUME    (PM_EVENT_USER | PM_EVENT_RESUME)
  281. #define PM_EVENT_REMOTE_WAKEUP    (PM_EVENT_REMOTE | PM_EVENT_RESUME)
  282. #define PM_EVENT_AUTO_SUSPEND    (PM_EVENT_AUTO | PM_EVENT_SUSPEND)
  283. #define PM_EVENT_AUTO_RESUME    (PM_EVENT_AUTO | PM_EVENT_RESUME)
  284.  
  285. #define PMSG_ON        ((struct pm_message){ .event = PM_EVENT_ON, })
  286. #define PMSG_FREEZE    ((struct pm_message){ .event = PM_EVENT_FREEZE, })
  287. #define PMSG_QUIESCE    ((struct pm_message){ .event = PM_EVENT_QUIESCE, })
  288. #define PMSG_SUSPEND    ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
  289. #define PMSG_HIBERNATE    ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
  290. #define PMSG_RESUME    ((struct pm_message){ .event = PM_EVENT_RESUME, })
  291. #define PMSG_THAW    ((struct pm_message){ .event = PM_EVENT_THAW, })
  292. #define PMSG_RESTORE    ((struct pm_message){ .event = PM_EVENT_RESTORE, })
  293. #define PMSG_RECOVER    ((struct pm_message){ .event = PM_EVENT_RECOVER, })
  294. #define PMSG_USER_SUSPEND    ((struct pm_messge) \
  295.                     { .event = PM_EVENT_USER_SUSPEND, })
  296. #define PMSG_USER_RESUME    ((struct pm_messge) \
  297.                     { .event = PM_EVENT_USER_RESUME, })
  298. #define PMSG_REMOTE_RESUME    ((struct pm_messge) \
  299.                     { .event = PM_EVENT_REMOTE_RESUME, })
  300. #define PMSG_AUTO_SUSPEND    ((struct pm_messge) \
  301.                     { .event = PM_EVENT_AUTO_SUSPEND, })
  302. #define PMSG_AUTO_RESUME        ((struct pm_messge) \
  303.                     { .event = PM_EVENT_AUTO_RESUME, })
  304.  
  305. /**
  306.  * Device power management states
  307.  *
  308.  * These state labels are used internally by the PM core to indicate the current
  309.  * status of a device with respect to the PM core operations.
  310.  *
  311.  * DPM_ON        Device is regarded as operational.  Set this way
  312.  *            initially and when ->complete() is about to be called.
  313.  *            Also set when ->prepare() fails.
  314.  *
  315.  * DPM_PREPARING    Device is going to be prepared for a PM transition.  Set
  316.  *            when ->prepare() is about to be called.
  317.  *
  318.  * DPM_RESUMING        Device is going to be resumed.  Set when ->resume(),
  319.  *            ->thaw(), or ->restore() is about to be called.
  320.  *
  321.  * DPM_SUSPENDING    Device has been prepared for a power transition.  Set
  322.  *            when ->prepare() has just succeeded.
  323.  *
  324.  * DPM_OFF        Device is regarded as inactive.  Set immediately after
  325.  *            ->suspend(), ->freeze(), or ->poweroff() has succeeded.
  326.  *            Also set when ->resume()_noirq, ->thaw_noirq(), or
  327.  *            ->restore_noirq() is about to be called.
  328.  *
  329.  * DPM_OFF_IRQ        Device is in a "deep sleep".  Set immediately after
  330.  *            ->suspend_noirq(), ->freeze_noirq(), or
  331.  *            ->poweroff_noirq() has just succeeded.
  332.  */
  333.  
  334. enum dpm_state {
  335.     DPM_INVALID,
  336.     DPM_ON,
  337.     DPM_PREPARING,
  338.     DPM_RESUMING,
  339.     DPM_SUSPENDING,
  340.     DPM_OFF,
  341.     DPM_OFF_IRQ,
  342. };
  343.  
  344. struct dev_pm_info {
  345.     pm_message_t        power_state;
  346.     unsigned        can_wakeup:1;
  347.     unsigned        should_wakeup:1;
  348.     enum dpm_state        status;        /* Owned by the PM core */
  349. #ifdef    CONFIG_PM_SLEEP
  350.     struct list_head    entry;
  351. #endif
  352. };
  353.  
  354. /*
  355.  * The PM_EVENT_ messages are also used by drivers implementing the legacy
  356.  * suspend framework, based on the ->suspend() and ->resume() callbacks common
  357.  * for suspend and hibernation transitions, according to the rules below.
  358.  */
  359.  
  360. /* Necessary, because several drivers use PM_EVENT_PRETHAW */
  361. #define PM_EVENT_PRETHAW PM_EVENT_QUIESCE
  362.  
  363. /*
  364.  * One transition is triggered by resume(), after a suspend() call; the
  365.  * message is implicit:
  366.  *
  367.  * ON        Driver starts working again, responding to hardware events
  368.  *         and software requests.  The hardware may have gone through
  369.  *         a power-off reset, or it may have maintained state from the
  370.  *         previous suspend() which the driver will rely on while
  371.  *         resuming.  On most platforms, there are no restrictions on
  372.  *         availability of resources like clocks during resume().
  373.  *
  374.  * Other transitions are triggered by messages sent using suspend().  All
  375.  * these transitions quiesce the driver, so that I/O queues are inactive.
  376.  * That commonly entails turning off IRQs and DMA; there may be rules
  377.  * about how to quiesce that are specific to the bus or the device's type.
  378.  * (For example, network drivers mark the link state.)  Other details may
  379.  * differ according to the message:
  380.  *
  381.  * SUSPEND    Quiesce, enter a low power device state appropriate for
  382.  *         the upcoming system state (such as PCI_D3hot), and enable
  383.  *         wakeup events as appropriate.
  384.  *
  385.  * HIBERNATE    Enter a low power device state appropriate for the hibernation
  386.  *         state (eg. ACPI S4) and enable wakeup events as appropriate.
  387.  *
  388.  * FREEZE    Quiesce operations so that a consistent image can be saved;
  389.  *         but do NOT otherwise enter a low power device state, and do
  390.  *         NOT emit system wakeup events.
  391.  *
  392.  * PRETHAW    Quiesce as if for FREEZE; additionally, prepare for restoring
  393.  *         the system from a snapshot taken after an earlier FREEZE.
  394.  *         Some drivers will need to reset their hardware state instead
  395.  *         of preserving it, to ensure that it's never mistaken for the
  396.  *         state which that earlier snapshot had set up.
  397.  *
  398.  * A minimally power-aware driver treats all messages as SUSPEND, fully
  399.  * reinitializes its device during resume() -- whether or not it was reset
  400.  * during the suspend/resume cycle -- and can't issue wakeup events.
  401.  *
  402.  * More power-aware drivers may also use low power states at runtime as
  403.  * well as during system sleep states like PM_SUSPEND_STANDBY.  They may
  404.  * be able to use wakeup events to exit from runtime low-power states,
  405.  * or from system low-power states such as standby or suspend-to-RAM.
  406.  */
  407.  
  408. #ifdef CONFIG_PM_SLEEP
  409. extern void device_pm_lock(void);
  410. extern void device_power_up(pm_message_t state);
  411. extern void device_resume(pm_message_t state);
  412.  
  413. extern void device_pm_unlock(void);
  414. extern int device_power_down(pm_message_t state);
  415. extern int device_suspend(pm_message_t state);
  416. extern int device_prepare_suspend(pm_message_t state);
  417.  
  418. extern void __suspend_report_result(const char *function, void *fn, int ret);
  419.  
  420. #define suspend_report_result(fn, ret)                    \
  421.     do {                                \
  422.         __suspend_report_result(__func__, fn, ret);        \
  423.     } while (0)
  424.  
  425. #else /* !CONFIG_PM_SLEEP */
  426.  
  427. static inline int device_suspend(pm_message_t state)
  428. {
  429.     return 0;
  430. }
  431.  
  432. #define suspend_report_result(fn, ret)        do {} while (0)
  433.  
  434. #endif /* !CONFIG_PM_SLEEP */
  435.  
  436. /*
  437.  * Global Power Management flags
  438.  * Used to keep APM and ACPI from both being active
  439.  */
  440. extern unsigned int    pm_flags;
  441.  
  442. #define PM_APM    1
  443. #define PM_ACPI    2
  444.  
  445. #endif /* _LINUX_PM_H */
  446.