1 /*
2 * SPDX-FileCopyrightText: 2016-2023 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #pragma once
8
9 /**
10 * @file esp_private/pm_impl.h
11 *
12 * This header file defines interface between PM lock functions (pm_locks.c)
13 * and the chip-specific power management (DFS/light sleep) implementation.
14 */
15
16 #include "soc/rtc.h"
17 #include "esp_pm.h"
18 #include "esp_timer.h"
19 #include "sdkconfig.h"
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /**
26 * This is an enum of possible power modes supported by the implementation
27 */
28 typedef enum {
29 PM_MODE_LIGHT_SLEEP,//!< Light sleep
30 PM_MODE_APB_MIN, //!< Idle (no CPU frequency or APB frequency locks)
31 PM_MODE_APB_MAX, //!< Maximum APB frequency mode
32 PM_MODE_CPU_MAX, //!< Maximum CPU frequency mode
33 PM_MODE_COUNT //!< Number of items
34 } pm_mode_t;
35
36 /**
37 * @brief Get the mode corresponding to a certain lock
38 * @param type lock type
39 * @param arg argument value for this lock (passed to esp_pm_lock_create)
40 * @return lowest power consumption mode which meets the constraints of the lock
41 */
42 pm_mode_t esp_pm_impl_get_mode(esp_pm_lock_type_t type, int arg);
43
44 /**
45 * @brief Get CPU clock frequency by power mode
46 * @param mode power mode
47 * @return CPU clock frequency
48 */
49 int esp_pm_impl_get_cpu_freq(pm_mode_t mode);
50
51 /**
52 * If profiling is enabled, this data type will be used to store microsecond
53 * timestamps.
54 */
55 typedef int64_t pm_time_t;
56
57 /**
58 * See \ref esp_pm_impl_switch_mode
59 */
60 typedef enum {
61 MODE_LOCK,
62 MODE_UNLOCK
63 } pm_mode_switch_t;
64
65 /**
66 * @brief Switch between power modes when lock is taken or released
67 * @param mode pm_mode_t corresponding to the lock being taken or released,
68 * as returned by \ref esp_pm_impl_get_mode
69 * @param lock_or_unlock
70 * - MODE_LOCK: lock was taken. Implementation needs to make sure
71 * that the constraints of the lock are met by switching to the
72 * given 'mode' or any of the higher power ones.
73 * - MODE_UNLOCK: lock was released. If all the locks for given
74 * mode are released, and no locks for higher power modes are
75 * taken, implementation can switch to one of lower power modes.
76 * @param now timestamp when the lock was taken or released. Passed as
77 * a minor optimization, so that the implementation does not need to
78 * call pm_get_time again.
79 */
80 void esp_pm_impl_switch_mode(pm_mode_t mode, pm_mode_switch_t lock_or_unlock, pm_time_t now);
81
82 /**
83 * @brief Call once at startup to initialize pm implementation
84 */
85 void esp_pm_impl_init(void);
86
87 /**
88 * @brief Hook function for the idle task
89 * Must be called from the IDLE task on each CPU before entering waiti state.
90 */
91 void esp_pm_impl_idle_hook(void);
92
93 /**
94 * @brief Hook function for the interrupt dispatcher
95 * Must be called soon after entering the ISR
96 */
97 void esp_pm_impl_isr_hook(void);
98
99 /**
100 * @brief Dump the information about time spent in each of the pm modes.
101 *
102 * Prints three columns:
103 * mode name, total time in mode (in microseconds), percentage of time in mode
104 *
105 * @param out stream to dump the information to
106 */
107 void esp_pm_impl_dump_stats(FILE* out);
108
109 /**
110 * @brief Hook function implementing `waiti` instruction, should be invoked from idle task context
111 */
112 void esp_pm_impl_waiti(void);
113
114 /**
115 * @brief Callback function type for peripherals to skip light sleep.
116 *
117 */
118 typedef bool (* skip_light_sleep_cb_t)(void);
119
120 /**
121 * @brief Register peripherals skip light sleep callback
122 *
123 * This function allows you to register a callback that gets the result
124 * that if light sleep should be skipped by peripherals.
125 * @param cb function to get the result
126 * @return
127 * - ESP_OK on success
128 * - ESP_ERR_NO_MEM if no more callback slots are available
129 */
130 esp_err_t esp_pm_register_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
131
132 /**
133 * @brief Unregisterperipherals skip light sleep callback
134 *
135 * This function allows you to unregister a callback which was previously
136 * registered using esp_register_skip_light_sleep_callback.
137 * @param cb function to get the result
138 * @return
139 * - ESP_OK on success
140 * - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before
141 */
142 esp_err_t esp_pm_unregister_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
143
144 #ifdef CONFIG_PM_PROFILING
145 #define WITH_PROFILING
146 #endif
147
148 #ifdef WITH_PROFILING
pm_get_time(void)149 static inline pm_time_t IRAM_ATTR pm_get_time(void)
150 {
151 return esp_timer_get_time();
152 }
153 #endif // WITH_PROFILING
154
155 #ifdef __cplusplus
156 }
157 #endif
158
