1 // Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 #pragma once
16
17 /**
18 * @file esp_private/pm_impl.h
19 *
20 * This header file defines interface between PM lock functions (pm_locks.c)
21 * and the chip-specific power management (DFS/light sleep) implementation.
22 */
23
24 #include "soc/rtc.h"
25 #include "esp_pm.h"
26 #include "esp_timer.h"
27 #include "sdkconfig.h"
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /**
34 * This is an enum of possible power modes supported by the implementation
35 */
36 typedef enum {
37 PM_MODE_LIGHT_SLEEP,//!< Light sleep
38 PM_MODE_APB_MIN, //!< Idle (no CPU frequency or APB frequency locks)
39 PM_MODE_APB_MAX, //!< Maximum APB frequency mode
40 PM_MODE_CPU_MAX, //!< Maximum CPU frequency mode
41 PM_MODE_COUNT //!< Number of items
42 } pm_mode_t;
43
44 /**
45 * @brief Get the mode corresponding to a certain lock
46 * @param type lock type
47 * @param arg argument value for this lock (passed to esp_pm_lock_create)
48 * @return lowest power consumption mode which meets the constraints of the lock
49 */
50 pm_mode_t esp_pm_impl_get_mode(esp_pm_lock_type_t type, int arg);
51
52 /**
53 * @brief Get CPU clock frequency by power mode
54 * @param mode power mode
55 * @return CPU clock frequency
56 */
57 int esp_pm_impl_get_cpu_freq(pm_mode_t mode);
58
59 /**
60 * If profiling is enabled, this data type will be used to store microsecond
61 * timestamps.
62 */
63 typedef int64_t pm_time_t;
64
65 /**
66 * See \ref esp_pm_impl_switch_mode
67 */
68 typedef enum {
69 MODE_LOCK,
70 MODE_UNLOCK
71 } pm_mode_switch_t;
72
73 /**
74 * @brief Switch between power modes when lock is taken or released
75 * @param mode pm_mode_t corresponding to the lock being taken or released,
76 * as returned by \ref esp_pm_impl_get_mode
77 * @param lock_or_unlock
78 * - MODE_LOCK: lock was taken. Implementation needs to make sure
79 * that the constraints of the lock are met by switching to the
80 * given 'mode' or any of the higher power ones.
81 * - MODE_UNLOCK: lock was released. If all the locks for given
82 * mode are released, and no locks for higher power modes are
83 * taken, implementation can switch to one of lower power modes.
84 * @param now timestamp when the lock was taken or released. Passed as
85 * a minor optimization, so that the implementation does not need to
86 * call pm_get_time again.
87 */
88 void esp_pm_impl_switch_mode(pm_mode_t mode, pm_mode_switch_t lock_or_unlock, pm_time_t now);
89
90 /**
91 * @brief Call once at startup to initialize pm implementation
92 */
93 void esp_pm_impl_init(void);
94
95 /**
96 * @brief Hook function for the idle task
97 * Must be called from the IDLE task on each CPU before entering waiti state.
98 */
99 void esp_pm_impl_idle_hook(void);
100
101 /**
102 * @brief Hook function for the interrupt dispatcher
103 * Must be called soon after entering the ISR
104 */
105 void esp_pm_impl_isr_hook(void);
106
107 /**
108 * @brief Dump the information about time spent in each of the pm modes.
109 *
110 * Prints three columns:
111 * mode name, total time in mode (in microseconds), percentage of time in mode
112 *
113 * @param out stream to dump the information to
114 */
115 void esp_pm_impl_dump_stats(FILE* out);
116
117 /**
118 * @brief Hook function implementing `waiti` instruction, should be invoked from idle task context
119 */
120 void esp_pm_impl_waiti(void);
121
122 /**
123 * @brief Callback function type for peripherals to skip light sleep.
124 *
125 */
126 typedef bool (* skip_light_sleep_cb_t)(void);
127
128 /**
129 * @brief Register peripherals skip light sleep callback
130 *
131 * This function allows you to register a callback that gets the result
132 * that if light sleep should be skipped by peripherals.
133 * @param cb function to get the result
134 * @return
135 * - ESP_OK on success
136 * - ESP_ERR_NO_MEM if no more callback slots are available
137 */
138 esp_err_t esp_pm_register_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
139
140 /**
141 * @brief Unregisterperipherals skip light sleep callback
142 *
143 * This function allows you to unregister a callback which was previously
144 * registered using esp_register_skip_light_sleep_callback.
145 * @param cb function to get the result
146 * @return
147 * - ESP_OK on success
148 * - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before
149 */
150 esp_err_t esp_pm_unregister_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
151
152 /**
153 * @brief Callback function type for peripherals to know light sleep wakeup overhead.
154 *
155 */
156 typedef void (* inform_out_light_sleep_overhead_cb_t)(uint32_t);
157
158 /**
159 * @brief Register informing peripherals light sleep wakeup overhead time callback
160 *
161 * This function allows you to register a callback that informs the peripherals of
162 * the wakeup overhead time of light sleep.
163 * @param cb function to inform time
164 * @return
165 * - ESP_OK on success
166 * - ESP_ERR_NO_MEM if no more callback slots are available
167 */
168 esp_err_t esp_pm_register_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb);
169
170 /**
171 * @brief Unregister informing peripherals light sleep wakeup overhead time callback
172 *
173 * This function allows you to unregister a callback that informs the peripherals of
174 * the wakeup overhead time of light sleep.
175 * @param cb function to inform time
176 * @return
177 * - ESP_OK on success
178 * - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before
179 */
180 esp_err_t esp_pm_unregister_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb);
181
182 /**
183 * @brief Callback function type for peripherals to know light sleep default parameters
184 */
185 typedef void (* update_light_sleep_default_params_config_cb_t)(int, int);
186
187 /**
188 * @brief Register peripherals light sleep default parameters configure callback
189 *
190 * This function allows you to register a callback that configure the peripherals
191 * of default parameters of light sleep
192 * @param cb function to update default parameters
193 */
194 void esp_pm_register_light_sleep_default_params_config_callback(update_light_sleep_default_params_config_cb_t cb);
195
196 /**
197 * @brief Unregister peripherals light sleep default parameters configure Callback
198 *
199 * This function allows you to unregister a callback that configure the peripherals
200 * of default parameters of light sleep
201 */
202 void esp_pm_unregister_light_sleep_default_params_config_callback(void);
203
204 #ifdef CONFIG_PM_PROFILING
205 #define WITH_PROFILING
206 #endif
207
208 #ifdef WITH_PROFILING
pm_get_time(void)209 static inline pm_time_t IRAM_ATTR pm_get_time(void)
210 {
211 return esp_timer_get_time();
212 }
213 #endif // WITH_PROFILING
214
215 #ifdef __cplusplus
216 }
217 #endif
218
