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 : union {
59 : struct {
60 : /**
61 : * Application defined function for doing any target specific operations
62 : * for power state entry.
63 : */
64 1 : void (*state_entry)(enum pm_state state);
65 : /**
66 : * Application defined function for doing any target specific operations
67 : * for power state exit.
68 : */
69 1 : void (*state_exit)(enum pm_state state);
70 : };
71 : struct {
72 : /**
73 : * Application defined function for doing any target specific operations
74 : * for power state entry. Reports the substate id additionally.
75 : */
76 1 : void (*substate_entry)(enum pm_state state, uint8_t substate_id);
77 : /**
78 : * Application defined function for doing any target specific operations
79 : * for power state exit. Reports the substate id additionally.
80 : */
81 1 : void (*substate_exit)(enum pm_state state, uint8_t substate_id);
82 : };
83 0 : };
84 0 : bool report_substate; /* 0 is for backwards compatibility that didn't report substates */
85 : };
86 :
87 : #if defined(CONFIG_PM) || defined(__DOXYGEN__)
88 : /**
89 : * @brief Force usage of given power state.
90 : *
91 : * This function overrides decision made by PM policy forcing
92 : * usage of given power state upon next entry of the idle thread.
93 : *
94 : * @note This function can only run in thread context
95 : *
96 : * @param cpu CPU index.
97 : * @param info Power state which should be used in the ongoing
98 : * suspend operation.
99 : */
100 1 : bool pm_state_force(uint8_t cpu, const struct pm_state_info *info);
101 :
102 : /**
103 : * @brief Register a power management notifier
104 : *
105 : * Register the given notifier from the power management notification
106 : * list.
107 : *
108 : * @param notifier pm_notifier object to be registered.
109 : */
110 1 : void pm_notifier_register(struct pm_notifier *notifier);
111 :
112 : /**
113 : * @brief Unregister a power management notifier
114 : *
115 : * Remove the given notifier from the power management notification
116 : * list. After that this object callbacks will not be called.
117 : *
118 : * @param notifier pm_notifier object to be unregistered.
119 : *
120 : * @return 0 if the notifier was successfully removed, a negative value
121 : * otherwise.
122 : */
123 1 : int pm_notifier_unregister(struct pm_notifier *notifier);
124 :
125 : /**
126 : * @brief Gets the next power state that will be used.
127 : *
128 : * This function returns the next power state that will be used by the
129 : * SoC.
130 : *
131 : * @param cpu CPU index.
132 : * @return next pm_state_info that will be used
133 : */
134 1 : const struct pm_state_info *pm_state_next_get(uint8_t cpu);
135 :
136 : /**
137 : * @brief Notify exit from kernel sleep.
138 : *
139 : * This function would notify exit from kernel idling if a corresponding
140 : * pm_system_suspend() notification was handled and did not return
141 : * PM_STATE_ACTIVE.
142 : *
143 : * This function should be called from the ISR context of the event
144 : * that caused the exit from kernel idling.
145 : *
146 : * This is required for cpu power states that would require
147 : * interrupts to be enabled while entering low power states. e.g. C1 in x86. In
148 : * those cases, the ISR would be invoked immediately after the event wakes up
149 : * the CPU, before code following the CPU wait, gets a chance to execute. This
150 : * can be ignored if no operation needs to be done at the wake event
151 : * notification.
152 : */
153 1 : void pm_system_resume(void);
154 :
155 : /**
156 : * @}
157 : */
158 :
159 : /**
160 : * @brief System Power Management Hooks
161 : * @defgroup subsys_pm_sys_hooks Hooks
162 : * @ingroup subsys_pm_sys
163 : * @{
164 : */
165 :
166 : /**
167 : * @brief Put processor into a power state.
168 : *
169 : * This function implements the SoC specific details necessary
170 : * to put the processor into available power states.
171 : *
172 : * @param state Power state.
173 : * @param substate_id Power substate id.
174 : */
175 1 : void pm_state_set(enum pm_state state, uint8_t substate_id);
176 :
177 : /**
178 : * @brief Do any SoC or architecture specific post ops after sleep state exits.
179 : *
180 : * This function is a place holder to do any operations that may
181 : * be needed to be done after sleep state exits. Currently it enables
182 : * interrupts after resuming from sleep state. In future, the enabling
183 : * of interrupts may be moved into the kernel.
184 : *
185 : * @param state Power state.
186 : * @param substate_id Power substate id.
187 : */
188 1 : void pm_state_exit_post_ops(enum pm_state state, uint8_t substate_id);
189 :
190 : /**
191 : * @}
192 : */
193 :
194 : #else /* CONFIG_PM */
195 :
196 : static inline void pm_notifier_register(struct pm_notifier *notifier)
197 : {
198 : ARG_UNUSED(notifier);
199 : }
200 :
201 : static inline int pm_notifier_unregister(struct pm_notifier *notifier)
202 : {
203 : ARG_UNUSED(notifier);
204 :
205 : return -ENOSYS;
206 : }
207 :
208 : static inline const struct pm_state_info *pm_state_next_get(uint8_t cpu)
209 : {
210 : ARG_UNUSED(cpu);
211 :
212 : return NULL;
213 : }
214 :
215 : static inline void pm_system_resume(void)
216 : {
217 : }
218 :
219 : #endif /* CONFIG_PM */
220 :
221 : #ifdef __cplusplus
222 : }
223 : #endif
224 :
225 : #endif /* ZEPHYR_INCLUDE_PM_PM_H_ */
|
