pm.h

Go to the documentation of this file.

/*
 *  pm.h - Power management interface
 *
 *  Copyright (C) 2000 Andrew Henroid
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef _LINUX_PM_H
#define _LINUX_PM_H

#include <linux/list.h>
#include <linux/workqueue.h>
#include <linux/spinlock.h>
#include <linux/wait.h>
#include <linux/timer.h>
#include <linux/completion.h>

/*
 * Callbacks for platform drivers to implement.
 */
extern void (*pm_idle)(void);
extern void (*pm_power_off)(void);
extern void (*pm_power_off_prepare)(void);

/*
 * Device power management
 */

struct device;

#ifdef CONFIG_PM
extern const char power_group_name[];       /* = "power" */
#else
#define power_group_name    NULL
#endif

typedef struct pm_message {
    int event;
} pm_message_t;

struct dev_pm_ops {
    int (*prepare)(struct device *dev);
    void (*complete)(struct device *dev);
    int (*suspend)(struct device *dev);
    int (*resume)(struct device *dev);
    int (*freeze)(struct device *dev);
    int (*thaw)(struct device *dev);
    int (*poweroff)(struct device *dev);
    int (*restore)(struct device *dev);
    int (*suspend_late)(struct device *dev);
    int (*resume_early)(struct device *dev);
    int (*freeze_late)(struct device *dev);
    int (*thaw_early)(struct device *dev);
    int (*poweroff_late)(struct device *dev);
    int (*restore_early)(struct device *dev);
    int (*suspend_noirq)(struct device *dev);
    int (*resume_noirq)(struct device *dev);
    int (*freeze_noirq)(struct device *dev);
    int (*thaw_noirq)(struct device *dev);
    int (*poweroff_noirq)(struct device *dev);
    int (*restore_noirq)(struct device *dev);
    int (*runtime_suspend)(struct device *dev);
    int (*runtime_resume)(struct device *dev);
    int (*runtime_idle)(struct device *dev);
};

#ifdef CONFIG_PM_SLEEP
#define SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
    .suspend = suspend_fn, \
    .resume = resume_fn, \
    .freeze = suspend_fn, \
    .thaw = resume_fn, \
    .poweroff = suspend_fn, \
    .restore = resume_fn,
#else
#define SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn)
#endif

#ifdef CONFIG_PM_RUNTIME
#define SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn) \
    .runtime_suspend = suspend_fn, \
    .runtime_resume = resume_fn, \
    .runtime_idle = idle_fn,
#else
#define SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn)
#endif

/*
 * Use this if you want to use the same suspend and resume callbacks for suspend
 * to RAM and hibernation.
 */
#define SIMPLE_DEV_PM_OPS(name, suspend_fn, resume_fn) \
const struct dev_pm_ops name = { \
    SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
}

/*
 * Use this for defining a set of PM operations to be used in all situations
 * (sustem suspend, hibernation or runtime PM).
 * NOTE: In general, system suspend callbacks, .suspend() and .resume(), should
 * be different from the corresponding runtime PM callbacks, .runtime_suspend(),
 * and .runtime_resume(), because .runtime_suspend() always works on an already
 * quiescent device, while .suspend() should assume that the device may be doing
 * something when it is called (it should ensure that the device will be
 * quiescent after it has returned).  Therefore it's better to point the "late"
 * suspend and "early" resume callback pointers, .suspend_late() and
 * .resume_early(), to the same routines as .runtime_suspend() and
 * .runtime_resume(), respectively (and analogously for hibernation).
 */
#define UNIVERSAL_DEV_PM_OPS(name, suspend_fn, resume_fn, idle_fn) \
const struct dev_pm_ops name = { \
    SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
    SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn) \
}

#define PM_EVENT_INVALID    (-1)
#define PM_EVENT_ON     0x0000
#define PM_EVENT_FREEZE     0x0001
#define PM_EVENT_SUSPEND    0x0002
#define PM_EVENT_HIBERNATE  0x0004
#define PM_EVENT_QUIESCE    0x0008
#define PM_EVENT_RESUME     0x0010
#define PM_EVENT_THAW       0x0020
#define PM_EVENT_RESTORE    0x0040
#define PM_EVENT_RECOVER    0x0080
#define PM_EVENT_USER       0x0100
#define PM_EVENT_REMOTE     0x0200
#define PM_EVENT_AUTO       0x0400

#define PM_EVENT_SLEEP      (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
#define PM_EVENT_USER_SUSPEND   (PM_EVENT_USER | PM_EVENT_SUSPEND)
#define PM_EVENT_USER_RESUME    (PM_EVENT_USER | PM_EVENT_RESUME)
#define PM_EVENT_REMOTE_RESUME  (PM_EVENT_REMOTE | PM_EVENT_RESUME)
#define PM_EVENT_AUTO_SUSPEND   (PM_EVENT_AUTO | PM_EVENT_SUSPEND)
#define PM_EVENT_AUTO_RESUME    (PM_EVENT_AUTO | PM_EVENT_RESUME)

#define PMSG_INVALID    ((struct pm_message){ .event = PM_EVENT_INVALID, })
#define PMSG_ON     ((struct pm_message){ .event = PM_EVENT_ON, })
#define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, })
#define PMSG_QUIESCE    ((struct pm_message){ .event = PM_EVENT_QUIESCE, })
#define PMSG_SUSPEND    ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
#define PMSG_HIBERNATE  ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
#define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, })
#define PMSG_THAW   ((struct pm_message){ .event = PM_EVENT_THAW, })
#define PMSG_RESTORE    ((struct pm_message){ .event = PM_EVENT_RESTORE, })
#define PMSG_RECOVER    ((struct pm_message){ .event = PM_EVENT_RECOVER, })
#define PMSG_USER_SUSPEND   ((struct pm_message) \
                    { .event = PM_EVENT_USER_SUSPEND, })
#define PMSG_USER_RESUME    ((struct pm_message) \
                    { .event = PM_EVENT_USER_RESUME, })
#define PMSG_REMOTE_RESUME  ((struct pm_message) \
                    { .event = PM_EVENT_REMOTE_RESUME, })
#define PMSG_AUTO_SUSPEND   ((struct pm_message) \
                    { .event = PM_EVENT_AUTO_SUSPEND, })
#define PMSG_AUTO_RESUME    ((struct pm_message) \
                    { .event = PM_EVENT_AUTO_RESUME, })

#define PMSG_IS_AUTO(msg)   (((msg).event & PM_EVENT_AUTO) != 0)

enum rpm_status {
    RPM_ACTIVE = 0,
    RPM_RESUMING,
    RPM_SUSPENDED,
    RPM_SUSPENDING,
};

enum rpm_request {
    RPM_REQ_NONE = 0,
    RPM_REQ_IDLE,
    RPM_REQ_SUSPEND,
    RPM_REQ_AUTOSUSPEND,
    RPM_REQ_RESUME,
};

struct wakeup_source;

struct pm_domain_data {
    struct list_head list_node;
    struct device *dev;
};

struct pm_subsys_data {
    spinlock_t lock;
    unsigned int refcount;
#ifdef CONFIG_PM_CLK
    struct list_head clock_list;
#endif
#ifdef CONFIG_PM_GENERIC_DOMAINS
    struct pm_domain_data *domain_data;
#endif
};

struct dev_pm_info {
    pm_message_t        power_state;
    unsigned int        can_wakeup:1;
    unsigned int        async_suspend:1;
    bool            is_prepared:1;  /* Owned by the PM core */
    bool            is_suspended:1; /* Ditto */
    bool            ignore_children:1;
    bool            early_init:1;   /* Owned by the PM core */
    spinlock_t      lock;
#ifdef CONFIG_PM_SLEEP
    struct list_head    entry;
    struct completion   completion;
    struct wakeup_source    *wakeup;
    bool            wakeup_path:1;
    bool            syscore:1;
#else
    unsigned int        should_wakeup:1;
#endif
#ifdef CONFIG_PM_RUNTIME
    struct timer_list   suspend_timer;
    unsigned long       timer_expires;
    struct work_struct  work;
    wait_queue_head_t   wait_queue;
    atomic_t        usage_count;
    atomic_t        child_count;
    unsigned int        disable_depth:3;
    unsigned int        idle_notification:1;
    unsigned int        request_pending:1;
    unsigned int        deferred_resume:1;
    unsigned int        run_wake:1;
    unsigned int        runtime_auto:1;
    unsigned int        no_callbacks:1;
    unsigned int        irq_safe:1;
    unsigned int        use_autosuspend:1;
    unsigned int        timer_autosuspends:1;
    enum rpm_request    request;
    enum rpm_status     runtime_status;
    int         runtime_error;
    int         autosuspend_delay;
    unsigned long       last_busy;
    unsigned long       active_jiffies;
    unsigned long       suspended_jiffies;
    unsigned long       accounting_timestamp;
    struct dev_pm_qos_request *pq_req;
#endif
    struct pm_subsys_data   *subsys_data;  /* Owned by the subsystem. */
    struct pm_qos_constraints *constraints;
};

extern void update_pm_runtime_accounting(struct device *dev);
extern int dev_pm_get_subsys_data(struct device *dev);
extern int dev_pm_put_subsys_data(struct device *dev);

/*
 * Power domains provide callbacks that are executed during system suspend,
 * hibernation, system resume and during runtime PM transitions along with
 * subsystem-level and driver-level callbacks.
 */
struct dev_pm_domain {
    struct dev_pm_ops   ops;
};

/*
 * The PM_EVENT_ messages are also used by drivers implementing the legacy
 * suspend framework, based on the ->suspend() and ->resume() callbacks common
 * for suspend and hibernation transitions, according to the rules below.
 */

/* Necessary, because several drivers use PM_EVENT_PRETHAW */
#define PM_EVENT_PRETHAW PM_EVENT_QUIESCE

/*
 * One transition is triggered by resume(), after a suspend() call; the
 * message is implicit:
 *
 * ON       Driver starts working again, responding to hardware events
 *      and software requests.  The hardware may have gone through
 *      a power-off reset, or it may have maintained state from the
 *      previous suspend() which the driver will rely on while
 *      resuming.  On most platforms, there are no restrictions on
 *      availability of resources like clocks during resume().
 *
 * Other transitions are triggered by messages sent using suspend().  All
 * these transitions quiesce the driver, so that I/O queues are inactive.
 * That commonly entails turning off IRQs and DMA; there may be rules
 * about how to quiesce that are specific to the bus or the device's type.
 * (For example, network drivers mark the link state.)  Other details may
 * differ according to the message:
 *
 * SUSPEND  Quiesce, enter a low power device state appropriate for
 *      the upcoming system state (such as PCI_D3hot), and enable
 *      wakeup events as appropriate.
 *
 * HIBERNATE    Enter a low power device state appropriate for the hibernation
 *      state (eg. ACPI S4) and enable wakeup events as appropriate.
 *
 * FREEZE   Quiesce operations so that a consistent image can be saved;
 *      but do NOT otherwise enter a low power device state, and do
 *      NOT emit system wakeup events.
 *
 * PRETHAW  Quiesce as if for FREEZE; additionally, prepare for restoring
 *      the system from a snapshot taken after an earlier FREEZE.
 *      Some drivers will need to reset their hardware state instead
 *      of preserving it, to ensure that it's never mistaken for the
 *      state which that earlier snapshot had set up.
 *
 * A minimally power-aware driver treats all messages as SUSPEND, fully
 * reinitializes its device during resume() -- whether or not it was reset
 * during the suspend/resume cycle -- and can't issue wakeup events.
 *
 * More power-aware drivers may also use low power states at runtime as
 * well as during system sleep states like PM_SUSPEND_STANDBY.  They may
 * be able to use wakeup events to exit from runtime low-power states,
 * or from system low-power states such as standby or suspend-to-RAM.
 */

#ifdef CONFIG_PM_SLEEP
extern void device_pm_lock(void);
extern void dpm_resume_start(pm_message_t state);
extern void dpm_resume_end(pm_message_t state);
extern void dpm_resume(pm_message_t state);
extern void dpm_complete(pm_message_t state);

extern void device_pm_unlock(void);
extern int dpm_suspend_end(pm_message_t state);
extern int dpm_suspend_start(pm_message_t state);
extern int dpm_suspend(pm_message_t state);
extern int dpm_prepare(pm_message_t state);

extern void __suspend_report_result(const char *function, void *fn, int ret);

#define suspend_report_result(fn, ret)                  \
    do {                                \
        __suspend_report_result(__func__, fn, ret);     \
    } while (0)

extern int device_pm_wait_for_dev(struct device *sub, struct device *dev);
extern void dpm_for_each_dev(void *data, void (*fn)(struct device *, void *));

extern int pm_generic_prepare(struct device *dev);
extern int pm_generic_suspend_late(struct device *dev);
extern int pm_generic_suspend_noirq(struct device *dev);
extern int pm_generic_suspend(struct device *dev);
extern int pm_generic_resume_early(struct device *dev);
extern int pm_generic_resume_noirq(struct device *dev);
extern int pm_generic_resume(struct device *dev);
extern int pm_generic_freeze_noirq(struct device *dev);
extern int pm_generic_freeze_late(struct device *dev);
extern int pm_generic_freeze(struct device *dev);
extern int pm_generic_thaw_noirq(struct device *dev);
extern int pm_generic_thaw_early(struct device *dev);
extern int pm_generic_thaw(struct device *dev);
extern int pm_generic_restore_noirq(struct device *dev);
extern int pm_generic_restore_early(struct device *dev);
extern int pm_generic_restore(struct device *dev);
extern int pm_generic_poweroff_noirq(struct device *dev);
extern int pm_generic_poweroff_late(struct device *dev);
extern int pm_generic_poweroff(struct device *dev);
extern void pm_generic_complete(struct device *dev);

#else /* !CONFIG_PM_SLEEP */

#define device_pm_lock() do {} while (0)
#define device_pm_unlock() do {} while (0)

static inline int dpm_suspend_start(pm_message_t state)
{
    return 0;
}

#define suspend_report_result(fn, ret)      do {} while (0)

static inline int device_pm_wait_for_dev(struct device *a, struct device *b)
{
    return 0;
}

static inline void dpm_for_each_dev(void *data, void (*fn)(struct device *, void *))
{
}

#define pm_generic_prepare  NULL
#define pm_generic_suspend  NULL
#define pm_generic_resume   NULL
#define pm_generic_freeze   NULL
#define pm_generic_thaw     NULL
#define pm_generic_restore  NULL
#define pm_generic_poweroff NULL
#define pm_generic_complete NULL
#endif /* !CONFIG_PM_SLEEP */

/* How to reorder dpm_list after device_move() */
enum dpm_order {
    DPM_ORDER_NONE,
    DPM_ORDER_DEV_AFTER_PARENT,
    DPM_ORDER_PARENT_BEFORE_DEV,
    DPM_ORDER_DEV_LAST,
};

#endif /* _LINUX_PM_H */