components/esp_pm/include/esp_pm.h (ESP-IDF)

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

255

256

257

258

/* * 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_MAX, } 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. * * @note If the lock_type argument is not valid, it will cause an abort. * * @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 * - 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