1 /* 2 * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include <stddef.h> 10 #include <stdbool.h> 11 #include "esp_err.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 18 typedef enum { 19 /** 20 * Using SLEEP_EVENT to determine the execution of specific 21 * code at a particular point in the sleep flow. 22 */ 23 SLEEP_EVENT_HW_EXIT_SLEEP, // CPU wake up and start to work 24 SLEEP_EVENT_SW_CLK_READY, // CPU frequency restore 25 SLEEP_EVENT_SW_EXIT_SLEEP, // End of esp_light_sleep_start 26 SLEEP_EVENT_SW_GOTO_SLEEP, // Beginning of esp_light_sleep_start 27 SLEEP_EVENT_HW_TIME_START, // Start timing the sleep time 28 SLEEP_EVENT_HW_GOTO_SLEEP, // Hardware is about to power off 29 SLEEP_EVENT_SW_CPU_TO_MEM_START, // CPU registers are starting to be saved 30 SLEEP_EVENT_SW_CPU_TO_MEM_END, // CPU registers have finished saving 31 #if CONFIG_IDF_TARGET_ESP32H2 32 SLEEP_EVENT_HW_FLASH_BBPLL_EN_START, // Beginning of rtc_clk_bbpll_enable when using FLASH_PLL 33 SLEEP_EVENT_HW_FLASH_BBPLL_EN_STOP, // End of rtc_clk_bbpll_enable when using FLASH_PLL 34 #endif 35 SLEEP_EVENT_HW_BBPLL_EN_START, // Beginning of rtc_clk_bbpll_enable 36 SLEEP_EVENT_HW_BBPLL_EN_STOP, // End of rtc_clk_bbpll_enable 37 SLEEP_EVENT_CB_INDEX_NUM, 38 } esp_sleep_event_cb_index_t; 39 40 /** 41 * @brief Function prototype for light sleep event callback functions (if CONFIG_FREERTOS_USE_TICKLESS_IDLE). 42 * @param user_arg is the user provided argument while registering callbacks. 43 * @param ext_arg is an externally provided parameter that is used when the callback is executed. 44 * @return None 45 */ 46 47 typedef esp_err_t (*esp_sleep_event_cb_t)(void *user_arg, void *ext_arg); 48 49 /** 50 * @brief Function entry parameter types for light sleep event callback functions (if CONFIG_FREERTOS_USE_TICKLESS_IDLE) 51 */ 52 struct _esp_sleep_event_cb_config_t { 53 /** 54 * Callback function defined by internal developers. 55 */ 56 esp_sleep_event_cb_t cb; 57 /** 58 * Input parameters of callback function defined by internal developers. 59 */ 60 void *user_arg; 61 /** 62 * Execution priority of callback function defined by internal developers. 63 * The smaller the priority, the earlier it executes when call esp_sleep_execute_event_callbacks. 64 * If functions have the same priority, the function registered first will be executed first. 65 */ 66 uint32_t prior; 67 /** 68 * Next callback configuration defined by internal developer. 69 */ 70 struct _esp_sleep_event_cb_config_t *next; 71 }; 72 73 typedef struct _esp_sleep_event_cb_config_t esp_sleep_event_cb_config_t; 74 75 struct _esp_sleep_event_cbs_config_t { 76 /** 77 * Callback configurations defined by internal developers. 78 */ 79 esp_sleep_event_cb_config_t *sleep_event_cb_config[SLEEP_EVENT_CB_INDEX_NUM]; 80 }; 81 82 typedef struct _esp_sleep_event_cbs_config_t esp_sleep_event_cbs_config_t; 83 84 /** 85 * @brief Register event callbacks for light sleep internal events (if CONFIG_FREERTOS_USE_TICKLESS_IDLE) 86 * @param event_id Designed to register the corresponding event_cb in g_sleep_event_cbs_config 87 * @param event_cb_conf Config struct containing event callback function and corresponding argument 88 * @return 89 * - ESP_OK on success 90 * - ESP_ERR_INVALID_ARG if the input parameter event_cb_conf is NULL or event_id is out of range 91 * - ESP_ERR_NO_MEM if the remaining memory is insufficient to support malloc 92 * - ESP_FAIL if register the same function repeatedly 93 * 94 * @note Some of these callback functions are called from IDLE task context hence they cannot call any blocking functions 95 * @note Passing NULL value will not deregister the callbacks, it will silently ignore and return ESP_OK 96 */ 97 esp_err_t esp_sleep_register_event_callback(esp_sleep_event_cb_index_t event_id, const esp_sleep_event_cb_config_t *event_cb_conf); 98 99 /** 100 * @brief Unregister event callbacks for light sleep internal events (if CONFIG_FREERTOS_USE_TICKLESS_IDLE) 101 * @param event_id Designed to unregister the corresponding event_cb in g_sleep_event_cbs_config 102 * @param event_cb_conf Config struct containing event callback function and corresponding argument 103 * @return 104 * - ESP_OK on success 105 * - ESP_ERR_INVALID_ARG if the input parameter cb is NULL or event_id is out of range 106 */ 107 esp_err_t esp_sleep_unregister_event_callback(esp_sleep_event_cb_index_t event_id, esp_sleep_event_cb_t cb); 108 109 /** 110 * @brief Designed to execute functions in the esp_sleep_event_cb_config_t linked list 111 * 112 * @param event_id Designed to annotate the corresponding event_cb in g_sleep_event_cbs_config 113 * @param ext_arg Designed to pass external parameters 114 * @return None 115 */ 116 void esp_sleep_execute_event_callbacks(esp_sleep_event_cb_index_t event_id, void *ext_arg); 117 118 #ifdef __cplusplus 119 } 120 #endif 121
