Line data Source code
1 0 : /*
2 : * Copyright (c) 2012-2014 Wind River Systems, Inc.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_PM_PM_H_
8 : #define ZEPHYR_INCLUDE_PM_PM_H_
9 :
10 : #include <zephyr/types.h>
11 : #include <zephyr/sys/slist.h>
12 : #include <zephyr/pm/state.h>
13 : #include <zephyr/toolchain.h>
14 : #include <errno.h>
15 : #include <stdbool.h>
16 :
17 : #ifdef __cplusplus
18 : extern "C" {
19 : #endif
20 :
21 : /**
22 : * @brief System and device power management
23 : * @defgroup subsys_pm Power Management (PM)
24 : * @since 1.2
25 : * @ingroup os_services
26 : * @{
27 : * @}
28 : */
29 :
30 : /**
31 : * @brief System Power Management API
32 : * @defgroup subsys_pm_sys System
33 : * @since 1.2
34 : * @ingroup subsys_pm
35 : * @{
36 : */
37 :
38 : /**
39 : * Power management notifier struct
40 : *
41 : * This struct contains callbacks that are called when the target enters and
42 : * exits power states.
43 : *
44 : * As currently implemented the entry callback is invoked when
45 : * transitioning from PM_STATE_ACTIVE to another state, and the exit
46 : * callback is invoked when transitioning from a non-active state to
47 : * PM_STATE_ACTIVE. This behavior may change in the future.
48 : *
49 : * @note These callbacks can be called from the ISR of the event
50 : * that caused the kernel exit from idling.
51 : *
52 : * @note It is not allowed to call @ref pm_notifier_unregister or
53 : * @ref pm_notifier_register from these callbacks because they are called
54 : * with the spin locked in those functions.
55 : */
56 1 : struct pm_notifier {
57 : sys_snode_t _node;
58 : /**
59 : * Application defined function for doing any target specific operations
60 : * for power state entry.
61 : */
62 1 : void (*state_entry)(enum pm_state state);
63 : /**
64 : * Application defined function for doing any target specific operations
65 : * for power state exit.
66 : */
67 1 : void (*state_exit)(enum pm_state state);
68 : };
69 :
70 : #if defined(CONFIG_PM) || defined(__DOXYGEN__)
71 : /**
72 : * @brief Force usage of given power state.
73 : *
74 : * This function overrides decision made by PM policy forcing
75 : * usage of given power state upon next entry of the idle thread.
76 : *
77 : * @note This function can only run in thread context
78 : *
79 : * @param cpu CPU index.
80 : * @param info Power state which should be used in the ongoing
81 : * suspend operation.
82 : */
83 1 : bool pm_state_force(uint8_t cpu, const struct pm_state_info *info);
84 :
85 : /**
86 : * @brief Register a power management notifier
87 : *
88 : * Register the given notifier from the power management notification
89 : * list.
90 : *
91 : * @param notifier pm_notifier object to be registered.
92 : */
93 1 : void pm_notifier_register(struct pm_notifier *notifier);
94 :
95 : /**
96 : * @brief Unregister a power management notifier
97 : *
98 : * Remove the given notifier from the power management notification
99 : * list. After that this object callbacks will not be called.
100 : *
101 : * @param notifier pm_notifier object to be unregistered.
102 : *
103 : * @return 0 if the notifier was successfully removed, a negative value
104 : * otherwise.
105 : */
106 1 : int pm_notifier_unregister(struct pm_notifier *notifier);
107 :
108 : /**
109 : * @brief Gets the next power state that will be used.
110 : *
111 : * This function returns the next power state that will be used by the
112 : * SoC.
113 : *
114 : * @param cpu CPU index.
115 : * @return next pm_state_info that will be used
116 : */
117 1 : const struct pm_state_info *pm_state_next_get(uint8_t cpu);
118 :
119 : /**
120 : * @brief Notify exit from kernel sleep.
121 : *
122 : * This function would notify exit from kernel idling if a corresponding
123 : * pm_system_suspend() notification was handled and did not return
124 : * PM_STATE_ACTIVE.
125 : *
126 : * This function should be called from the ISR context of the event
127 : * that caused the exit from kernel idling.
128 : *
129 : * This is required for cpu power states that would require
130 : * interrupts to be enabled while entering low power states. e.g. C1 in x86. In
131 : * those cases, the ISR would be invoked immediately after the event wakes up
132 : * the CPU, before code following the CPU wait, gets a chance to execute. This
133 : * can be ignored if no operation needs to be done at the wake event
134 : * notification.
135 : */
136 1 : void pm_system_resume(void);
137 :
138 : /**
139 : * @}
140 : */
141 :
142 : /**
143 : * @brief System Power Management Hooks
144 : * @defgroup subsys_pm_sys_hooks Hooks
145 : * @ingroup subsys_pm_sys
146 : * @{
147 : */
148 :
149 : /**
150 : * @brief Put processor into a power state.
151 : *
152 : * This function implements the SoC specific details necessary
153 : * to put the processor into available power states.
154 : *
155 : * @param state Power state.
156 : * @param substate_id Power substate id.
157 : */
158 1 : void pm_state_set(enum pm_state state, uint8_t substate_id);
159 :
160 : /**
161 : * @brief Do any SoC or architecture specific post ops after sleep state exits.
162 : *
163 : * This function is a place holder to do any operations that may
164 : * be needed to be done after sleep state exits. Currently it enables
165 : * interrupts after resuming from sleep state. In future, the enabling
166 : * of interrupts may be moved into the kernel.
167 : *
168 : * @param state Power state.
169 : * @param substate_id Power substate id.
170 : */
171 1 : void pm_state_exit_post_ops(enum pm_state state, uint8_t substate_id);
172 :
173 : /**
174 : * @}
175 : */
176 :
177 : #else /* CONFIG_PM */
178 :
179 : static inline void pm_notifier_register(struct pm_notifier *notifier)
180 : {
181 : ARG_UNUSED(notifier);
182 : }
183 :
184 : static inline int pm_notifier_unregister(struct pm_notifier *notifier)
185 : {
186 : ARG_UNUSED(notifier);
187 :
188 : return -ENOSYS;
189 : }
190 :
191 : static inline const struct pm_state_info *pm_state_next_get(uint8_t cpu)
192 : {
193 : ARG_UNUSED(cpu);
194 :
195 : return NULL;
196 : }
197 :
198 : static inline void pm_system_resume(void)
199 : {
200 : }
201 :
202 : #endif /* CONFIG_PM */
203 :
204 : #ifdef __cplusplus
205 : }
206 : #endif
207 :
208 : #endif /* ZEPHYR_INCLUDE_PM_PM_H_ */
|
