-
Notifications
You must be signed in to change notification settings - Fork 7.2k
/
esp_pm.h
254 lines (235 loc) · 9.48 KB
/
esp_pm.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
/*
* SPDX-FileCopyrightText: 2016-2023 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Power management config
*
* Pass a pointer to this structure as an argument to esp_pm_configure function.
*/
typedef struct {
int max_freq_mhz; /*!< Maximum CPU frequency, in MHz */
int min_freq_mhz; /*!< Minimum CPU frequency to use when no locks are taken, in MHz */
bool light_sleep_enable; /*!< Enter light sleep when no locks are taken */
} esp_pm_config_t;
/**
* backward compatibility
* newer chips no longer require this typedef
*/
typedef esp_pm_config_t esp_pm_config_esp32_t __attribute__((deprecated("please use esp_pm_config_t instead")));
typedef esp_pm_config_t esp_pm_config_esp32s2_t __attribute__((deprecated("please use esp_pm_config_t instead")));
typedef esp_pm_config_t esp_pm_config_esp32s3_t __attribute__((deprecated("please use esp_pm_config_t instead")));
typedef esp_pm_config_t esp_pm_config_esp32c3_t __attribute__((deprecated("please use esp_pm_config_t instead")));
typedef esp_pm_config_t esp_pm_config_esp32c2_t __attribute__((deprecated("please use esp_pm_config_t instead")));
typedef esp_pm_config_t esp_pm_config_esp32c6_t __attribute__((deprecated("please use esp_pm_config_t instead")));
/**
* @brief Power management constraints
*/
typedef enum {
/**
* Require CPU frequency to be at the maximum value set via esp_pm_configure.
* Argument is unused and should be set to 0.
*/
ESP_PM_CPU_FREQ_MAX,
/**
* Require APB frequency to be at the maximum value supported by the chip.
* Argument is unused and should be set to 0.
*/
ESP_PM_APB_FREQ_MAX,
/**
* Prevent the system from going into light sleep.
* Argument is unused and should be set to 0.
*/
ESP_PM_NO_LIGHT_SLEEP,
} esp_pm_lock_type_t;
/**
* @brief Set implementation-specific power management configuration
* @param config pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the configuration values are not correct
* - ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported,
* or if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_configure(const void* config);
/**
* @brief Get implementation-specific power management configuration
* @param config pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the pointer is null
*/
esp_err_t esp_pm_get_configuration(void* config);
/**
* @brief Opaque handle to the power management lock
*/
typedef struct esp_pm_lock* esp_pm_lock_handle_t;
/**
* @brief Initialize a lock handle for certain power management parameter
*
* When lock is created, initially it is not taken.
* Call esp_pm_lock_acquire to take the lock.
*
* This function must not be called from an ISR.
*
* @param lock_type Power management constraint which the lock should control
* @param arg argument, value depends on lock_type, see esp_pm_lock_type_t
* @param name arbitrary string identifying the lock (e.g. "wifi" or "spi").
* Used by the esp_pm_dump_locks function to list existing locks.
* May be set to NULL. If not set to NULL, must point to a string which is valid
* for the lifetime of the lock.
* @param[out] out_handle handle returned from this function. Use this handle when calling
* esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release.
* Must not be NULL.
* @return
* - ESP_OK on success
* - ESP_ERR_NO_MEM if the lock structure can not be allocated
* - ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid
* - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg,
const char* name, esp_pm_lock_handle_t* out_handle);
/**
* @brief Take a power management lock
*
* Once the lock is taken, power management algorithm will not switch to the
* mode specified in a call to esp_pm_lock_create, or any of the lower power
* modes (higher numeric values of 'mode').
*
* The lock is recursive, in the sense that if esp_pm_lock_acquire is called
* a number of times, esp_pm_lock_release has to be called the same number of
* times in order to release the lock.
*
* This function may be called from an ISR.
*
* This function is not thread-safe w.r.t. calls to other esp_pm_lock_*
* functions for the same handle.
*
* @param handle handle obtained from esp_pm_lock_create function
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the handle is invalid
* - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_lock_acquire(esp_pm_lock_handle_t handle);
/**
* @brief Release the lock taken using esp_pm_lock_acquire.
*
* Call to this functions removes power management restrictions placed when
* taking the lock.
*
* Locks are recursive, so if esp_pm_lock_acquire is called a number of times,
* esp_pm_lock_release has to be called the same number of times in order to
* actually release the lock.
*
* This function may be called from an ISR.
*
* This function is not thread-safe w.r.t. calls to other esp_pm_lock_*
* functions for the same handle.
*
* @param handle handle obtained from esp_pm_lock_create function
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the handle is invalid
* - ESP_ERR_INVALID_STATE if lock is not acquired
* - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_lock_release(esp_pm_lock_handle_t handle);
/**
* @brief Delete a lock created using esp_pm_lock
*
* The lock must be released before calling this function.
*
* This function must not be called from an ISR.
*
* @param handle handle obtained from esp_pm_lock_create function
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the handle argument is NULL
* - ESP_ERR_INVALID_STATE if the lock is still acquired
* - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_lock_delete(esp_pm_lock_handle_t handle);
/**
* Dump the list of all locks to stderr
*
* This function dumps debugging information about locks created using
* esp_pm_lock_create to an output stream.
*
* This function must not be called from an ISR. If esp_pm_lock_acquire/release
* are called while this function is running, inconsistent results may be
* reported.
*
* @param stream stream to print information to; use stdout or stderr to print
* to the console; use fmemopen/open_memstream to print to a
* string buffer.
* @return
* - ESP_OK on success
* - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
*/
esp_err_t esp_pm_dump_locks(FILE* stream);
#if CONFIG_PM_LIGHT_SLEEP_CALLBACKS
/**
* @brief Function prototype for light sleep callback functions (if CONFIG_FREERTOS_USE_TICKLESS_IDLE)
*
* @param sleep_time_us supplied by the power management framework.
* For entry callback, sleep_time_us indicates the expected sleep time in us
* For exit callback, sleep_time_us indicates the actual sleep time in us
* @param arg is the user provided argument while registering callbacks
*
* @return
* - ESP_OK allow entry light sleep mode
*/
typedef esp_err_t (*esp_pm_light_sleep_cb_t)(int64_t sleep_time_us, void *arg);
typedef struct {
/**
* Callback function defined by internal developers.
*/
esp_pm_light_sleep_cb_t enter_cb;
esp_pm_light_sleep_cb_t exit_cb;
/**
* Input parameters of callback function defined by internal developers.
*/
void *enter_cb_user_arg;
void *exit_cb_user_arg;
/**
* Execution priority of callback function defined by internal developers.
* The smaller the priority, the earlier it executes when call esp_sleep_execute_event_callbacks.
* If functions have the same priority, the function registered first will be executed first.
*/
uint32_t enter_cb_prior;
uint32_t exit_cb_prior;
} esp_pm_sleep_cbs_register_config_t;
/**
* @brief Register entry or exit callbacks for light sleep (if CONFIG_FREERTOS_USE_TICKLESS_IDLE)
* @param cbs_conf Config struct containing entry or exit callbacks function and corresponding argument
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the input parameter enter_cb and exit_cb in cbs_conf are NULL
* - ESP_ERR_NO_MEM if the remaining memory is insufficient to support malloc
* - ESP_FAIL if register the same function repeatedly
*
* @note These callback functions are called from IDLE task context hence they cannot call any blocking functions
*/
esp_err_t esp_pm_light_sleep_register_cbs(esp_pm_sleep_cbs_register_config_t *cbs_conf);
/**
* @brief Unregister entry or exit callbacks for light sleep (if CONFIG_FREERTOS_USE_TICKLESS_IDLE)
* @param cbs_conf Config struct containing entry or exit callbacks function and corresponding argument
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if the input parameter enter_cb and exit_cb in cbs_conf are NULL
*/
esp_err_t esp_pm_light_sleep_unregister_cbs(esp_pm_sleep_cbs_register_config_t *cbs_conf);
#endif
#ifdef __cplusplus
}
#endif