Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
device.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015 Intel Corporation.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#ifndef ZEPHYR_INCLUDE_PM_DEVICE_H_
8#define ZEPHYR_INCLUDE_PM_DEVICE_H_
9
10#include <zephyr/device.h>
11#include <zephyr/kernel.h>
12#include <zephyr/sys/atomic.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
28struct device;
29
31enum pm_device_flag {
33 PM_DEVICE_FLAG_BUSY,
35 PM_DEVICE_FLAG_TURN_ON_FAILED,
37 PM_DEVICE_FLAG_PD_CLAIMED,
42 PM_DEVICE_FLAG_WS_CAPABLE,
44 PM_DEVICE_FLAG_WS_ENABLED,
46 PM_DEVICE_FLAG_RUNTIME_ENABLED,
48 PM_DEVICE_FLAG_PD,
50 PM_DEVICE_FLAG_RUNTIME_AUTO,
52 PM_DEVICE_FLAG_ISR_SAFE,
53};
54
65#define PM_DEVICE_ISR_SAFE 1
66
87};
88
107};
108
119typedef int (*pm_device_action_cb_t)(const struct device *dev,
120 enum pm_device_action action);
121
130typedef bool (*pm_device_action_failed_cb_t)(const struct device *dev,
131 int err);
132
146#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
149#endif /* CONFIG_PM_DEVICE_RUNTIME */
150#ifdef CONFIG_PM_DEVICE_POWER_DOMAIN
152 const struct device *domain;
153#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
154};
155
163struct pm_device {
166#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
168 const struct device *dev;
170 struct k_sem lock;
175#endif /* CONFIG_PM_DEVICE_RUNTIME */
176};
177
188#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
191#endif
192};
193
194/* Base part must be the first element. */
195BUILD_ASSERT(offsetof(struct pm_device, base) == 0);
196BUILD_ASSERT(offsetof(struct pm_device_isr, base) == 0);
197
200#ifdef CONFIG_PM_DEVICE_RUNTIME
201#define Z_PM_DEVICE_RUNTIME_INIT(obj) \
202 .lock = Z_SEM_INITIALIZER(obj.lock, 1, 1), \
203 .event = Z_EVENT_INITIALIZER(obj.event),
204#else
205#define Z_PM_DEVICE_RUNTIME_INIT(obj)
206#endif /* CONFIG_PM_DEVICE_RUNTIME */
207
208#ifdef CONFIG_PM_DEVICE_POWER_DOMAIN
209#define Z_PM_DEVICE_POWER_DOMAIN_INIT(_node_id) \
210 .domain = DEVICE_DT_GET_OR_NULL(DT_PHANDLE(_node_id, \
211 power_domain)),
212#else
213#define Z_PM_DEVICE_POWER_DOMAIN_INIT(obj)
214#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
215
221#define Z_PM_DEVICE_FLAGS(node_id) \
222 (COND_CODE_1( \
223 DT_NODE_EXISTS(node_id), \
224 ((DT_PROP_OR(node_id, wakeup_source, 0) \
225 << PM_DEVICE_FLAG_WS_CAPABLE) | \
226 (DT_PROP_OR(node_id, zephyr_pm_device_runtime_auto, 0) \
227 << PM_DEVICE_FLAG_RUNTIME_AUTO) | \
228 (DT_NODE_HAS_COMPAT(node_id, power_domain) << \
229 PM_DEVICE_FLAG_PD)), \
230 (0)))
231
243#define Z_PM_DEVICE_BASE_INIT(obj, node_id, pm_action_cb, _flags) \
244 { \
245 .action_cb = pm_action_cb, \
246 .state = PM_DEVICE_STATE_ACTIVE, \
247 .flags = ATOMIC_INIT(Z_PM_DEVICE_FLAGS(node_id) | (_flags)), \
248 Z_PM_DEVICE_POWER_DOMAIN_INIT(node_id) \
249 }
250
261#define Z_PM_DEVICE_INIT(obj, node_id, pm_action_cb, isr_safe) \
262 { \
263 .base = Z_PM_DEVICE_BASE_INIT(obj, node_id, pm_action_cb, \
264 isr_safe ? BIT(PM_DEVICE_FLAG_ISR_SAFE) : 0), \
265 COND_CODE_1(isr_safe, (), (Z_PM_DEVICE_RUNTIME_INIT(obj))) \
266 }
267
273#define Z_PM_DEVICE_NAME(dev_id) _CONCAT(__pm_device_, dev_id)
274
275#ifdef CONFIG_PM
287#define Z_PM_DEVICE_DEFINE_SLOT(dev_id) \
288 static STRUCT_SECTION_ITERABLE_ALTERNATE(pm_device_slots, device, \
289 _CONCAT(__pm_slot_, dev_id))
290#else
291#define Z_PM_DEVICE_DEFINE_SLOT(dev_id)
292#endif /* CONFIG_PM */
293
294#ifdef CONFIG_PM_DEVICE
302#define Z_PM_DEVICE_DEFINE(node_id, dev_id, pm_action_cb, isr_safe) \
303 Z_PM_DEVICE_DEFINE_SLOT(dev_id); \
304 static struct COND_CODE_1(isr_safe, (pm_device_isr), (pm_device)) \
305 Z_PM_DEVICE_NAME(dev_id) = \
306 Z_PM_DEVICE_INIT(Z_PM_DEVICE_NAME(dev_id), node_id, \
307 pm_action_cb, isr_safe)
308
314#define Z_PM_DEVICE_GET(dev_id) ((struct pm_device_base *)&Z_PM_DEVICE_NAME(dev_id))
315
316#else
317#define Z_PM_DEVICE_DEFINE(node_id, dev_id, pm_action_cb, isr_safe)
318#define Z_PM_DEVICE_GET(dev_id) NULL
319#endif /* CONFIG_PM_DEVICE */
320
334#define PM_DEVICE_DEFINE(dev_id, pm_action_cb, ...) \
335 Z_PM_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, pm_action_cb, \
336 COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))
337
349#define PM_DEVICE_DT_DEFINE(node_id, pm_action_cb, ...) \
350 Z_PM_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), pm_action_cb, \
351 COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))
352
364#define PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb, ...) \
365 Z_PM_DEVICE_DEFINE(DT_DRV_INST(idx), \
366 Z_DEVICE_DT_DEV_ID(DT_DRV_INST(idx)), \
367 pm_action_cb, \
368 COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))
369
378#define PM_DEVICE_GET(dev_id) \
379 Z_PM_DEVICE_GET(dev_id)
380
389#define PM_DEVICE_DT_GET(node_id) \
390 PM_DEVICE_GET(Z_DEVICE_DT_DEV_ID(node_id))
391
400#define PM_DEVICE_DT_INST_GET(idx) \
401 PM_DEVICE_DT_GET(DT_DRV_INST(idx))
402
409
427int pm_device_action_run(const struct device *dev,
428 enum pm_device_action action);
429
441 enum pm_device_action action,
443
444#if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
454int pm_device_state_get(const struct device *dev,
455 enum pm_device_state *state);
456
468static inline void pm_device_init_suspended(const struct device *dev)
469{
470 struct pm_device_base *pm = dev->pm_base;
471
473}
474
488static inline void pm_device_init_off(const struct device *dev)
489{
490 struct pm_device_base *pm = dev->pm_base;
491
493}
494
506void pm_device_busy_set(const struct device *dev);
507
515void pm_device_busy_clear(const struct device *dev);
516
524
533bool pm_device_is_busy(const struct device *dev);
534
548bool pm_device_wakeup_enable(const struct device *dev, bool enable);
549
558bool pm_device_wakeup_is_enabled(const struct device *dev);
559
568bool pm_device_wakeup_is_capable(const struct device *dev);
569
578bool pm_device_on_power_domain(const struct device *dev);
579
593int pm_device_power_domain_add(const struct device *dev,
594 const struct device *domain);
595
609 const struct device *domain);
610
620bool pm_device_is_powered(const struct device *dev);
621
636
637#else
638static inline int pm_device_state_get(const struct device *dev,
640{
641 ARG_UNUSED(dev);
642
644
645 return 0;
646}
647
648static inline void pm_device_init_suspended(const struct device *dev)
649{
650 ARG_UNUSED(dev);
651}
652static inline void pm_device_init_off(const struct device *dev)
653{
654 ARG_UNUSED(dev);
655}
656static inline void pm_device_busy_set(const struct device *dev)
657{
658 ARG_UNUSED(dev);
659}
660static inline void pm_device_busy_clear(const struct device *dev)
661{
662 ARG_UNUSED(dev);
663}
664static inline bool pm_device_is_any_busy(void) { return false; }
665static inline bool pm_device_is_busy(const struct device *dev)
666{
667 ARG_UNUSED(dev);
668 return false;
669}
670static inline bool pm_device_wakeup_enable(const struct device *dev,
671 bool enable)
672{
673 ARG_UNUSED(dev);
674 ARG_UNUSED(enable);
675 return false;
676}
677static inline bool pm_device_wakeup_is_enabled(const struct device *dev)
678{
679 ARG_UNUSED(dev);
680 return false;
681}
682static inline bool pm_device_wakeup_is_capable(const struct device *dev)
683{
684 ARG_UNUSED(dev);
685 return false;
686}
687static inline bool pm_device_on_power_domain(const struct device *dev)
688{
689 ARG_UNUSED(dev);
690 return false;
691}
692
693static inline int pm_device_power_domain_add(const struct device *dev,
694 const struct device *domain)
695{
696 ARG_UNUSED(dev);
697 ARG_UNUSED(domain);
698 return -ENOSYS;
699}
700
701static inline int pm_device_power_domain_remove(const struct device *dev,
702 const struct device *domain)
703{
704 ARG_UNUSED(dev);
705 ARG_UNUSED(domain);
706 return -ENOSYS;
707}
708
709static inline bool pm_device_is_powered(const struct device *dev)
710{
711 ARG_UNUSED(dev);
712 return true;
713}
714
715static inline int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb)
716{
717 int rc;
718
719 /* When power management is not enabled, all drivers should initialise to active state */
721 if (rc == 0) {
723 }
724 return rc;
725}
726
727#endif /* CONFIG_PM_DEVICE */
728
731#ifdef __cplusplus
732}
733#endif
734
735#endif
long atomic_t
Definition: atomic_types.h:15
bool pm_device_wakeup_is_enabled(const struct device *dev)
Check if a device is enabled as a wake up source.
int pm_device_power_domain_remove(const struct device *dev, const struct device *domain)
Remove a device from a power domain.
bool pm_device_on_power_domain(const struct device *dev)
Check if the device is on a switchable power domain.
int pm_device_action_run(const struct device *dev, enum pm_device_action action)
Run a pm action on a device.
static void pm_device_init_suspended(const struct device *dev)
Initialize a device state to PM_DEVICE_STATE_SUSPENDED.
Definition: device.h:468
pm_device_state
Device power states.
Definition: device.h:68
bool pm_device_wakeup_enable(const struct device *dev, bool enable)
Enable or disable a device as a wake up source.
void pm_device_children_action_run(const struct device *dev, enum pm_device_action action, pm_device_action_failed_cb_t failure_cb)
Run a pm action on all children of a device.
void pm_device_busy_set(const struct device *dev)
Mark a device as busy.
int(* pm_device_action_cb_t)(const struct device *dev, enum pm_device_action action)
Device PM action callback.
Definition: device.h:119
void pm_device_busy_clear(const struct device *dev)
Clear a device busy status.
bool pm_device_is_busy(const struct device *dev)
Check if a device is busy.
bool(* pm_device_action_failed_cb_t)(const struct device *dev, int err)
Device PM action failed callback.
Definition: device.h:130
bool pm_device_is_powered(const struct device *dev)
Check if the device is currently powered.
int pm_device_power_domain_add(const struct device *dev, const struct device *domain)
Add a device to a power domain.
bool pm_device_wakeup_is_capable(const struct device *dev)
Check if a device is wake up capable.
const char * pm_device_state_str(enum pm_device_state state)
Get name of device PM state.
int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb)
Setup a device driver into the lowest valid power mode.
bool pm_device_is_any_busy(void)
Check if any device is busy.
pm_device_action
Device PM actions.
Definition: device.h:90
static void pm_device_init_off(const struct device *dev)
Initialize a device state to PM_DEVICE_STATE_OFF.
Definition: device.h:488
int pm_device_state_get(const struct device *dev, enum pm_device_state *state)
Obtain the power state of a device.
@ PM_DEVICE_STATE_SUSPENDED
Device is suspended.
Definition: device.h:77
@ PM_DEVICE_STATE_OFF
Device is turned off (power removed).
Definition: device.h:86
@ PM_DEVICE_STATE_SUSPENDING
Device is being suspended.
Definition: device.h:79
@ PM_DEVICE_STATE_ACTIVE
Device is in active or regular state.
Definition: device.h:70
@ PM_DEVICE_ACTION_TURN_OFF
Turn off.
Definition: device.h:100
@ PM_DEVICE_ACTION_SUSPEND
Suspend.
Definition: device.h:92
@ PM_DEVICE_ACTION_RESUME
Resume.
Definition: device.h:94
@ PM_DEVICE_ACTION_TURN_ON
Turn on.
Definition: device.h:106
#define ENOSYS
Function not implemented.
Definition: errno.h:83
Public kernel APIs.
state
Definition: parser_state.h:29
#define bool
Definition: stdbool.h:13
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
Runtime device structure (in ROM) per driver instance.
Definition: device.h:399
struct pm_device_base * pm_base
Definition: device.h:427
Event Structure.
Definition: kernel.h:2221
Kernel Spin Lock.
Definition: spinlock.h:45
A structure used to submit work after a delay.
Definition: kernel.h:3903
Device PM info.
Definition: device.h:139
uint32_t usage
Device usage count.
Definition: device.h:148
pm_device_action_cb_t action_cb
Device PM action callback.
Definition: device.h:145
enum pm_device_state state
Device power state.
Definition: device.h:143
atomic_t flags
Device PM status flags.
Definition: device.h:141
Runtime PM info for device with synchronous PM.
Definition: device.h:185
struct k_spinlock lock
Lock to synchronize the synchronous get/put operations.
Definition: device.h:190
struct pm_device_base base
Base info.
Definition: device.h:187
Runtime PM info for device with generic PM.
Definition: device.h:163
struct k_work_delayable work
Work object for asynchronous calls.
Definition: device.h:174
struct k_event event
Event var to listen to the sync request events.
Definition: device.h:172
struct k_sem lock
Lock to synchronize the get/put operations.
Definition: device.h:170
const struct device * dev
Pointer to the device.
Definition: device.h:168
struct pm_device_base base
Base info.
Definition: device.h:165