1 /* 2 * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 #include <stdint.h> 9 #include "sdkconfig.h" 10 #include "soc/soc_caps.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 #if SOC_PAU_SUPPORTED 17 #include "esp_regdma.h" 18 19 /** 20 * @file sleep_retention.h 21 * 22 * This file contains declarations of sleep retention related functions, it 23 * includes sleep retention list creation, destruction and debugging interfaces. 24 */ 25 26 typedef enum sleep_retention_module_bitmap { 27 /* clock module, which includes system and modem */ 28 SLEEP_RETENTION_MODULE_CLOCK_SYSTEM = BIT(1), 29 SLEEP_RETENTION_MODULE_CLOCK_MODEM = BIT(2), 30 31 /* modem module, which includes WiFi, BLE and 802.15.4 */ 32 SLEEP_RETENTION_MODULE_WIFI_MAC = BIT(10), 33 SLEEP_RETENTION_MODULE_WIFI_BB = BIT(11), 34 SLEEP_RETENTION_MODULE_BLE_MAC = BIT(12), 35 SLEEP_RETENTION_MODULE_BT_BB = BIT(13), 36 SLEEP_RETENTION_MODULE_802154_MAC = BIT(14), 37 38 /* digital peripheral module, which includes Interrupt Matrix, HP_SYSTEM, 39 * TEE, APM, UART, Timer Group, IOMUX, SPIMEM, SysTimer, etc.. */ 40 SLEEP_RETENTION_MODULE_INTR_MATRIX = BIT(16), 41 SLEEP_RETENTION_MODULE_HP_SYSTEM = BIT(17), 42 SLEEP_RETENTION_MODULE_TEE_APM = BIT(18), 43 SLEEP_RETENTION_MODULE_UART0 = BIT(19), 44 SLEEP_RETENTION_MODULE_TG0 = BIT(20), 45 SLEEP_RETENTION_MODULE_IOMUX = BIT(21), 46 SLEEP_RETENTION_MODULE_SPIMEM = BIT(22), 47 SLEEP_RETENTION_MODULE_SYSTIMER = BIT(23), 48 49 SLEEP_RETENTION_MODULE_ALL = (uint32_t)-1 50 } sleep_retention_module_bitmap_t; 51 52 typedef regdma_entry_buf_t sleep_retention_entries_t; 53 54 typedef struct { 55 regdma_link_config_t config; 56 uint32_t owner; /**< Indicates which regdma entries the current node will insert into */ 57 } sleep_retention_entries_config_t; 58 59 /** 60 * @brief Create a runtime sleep retention linked list 61 * 62 * @param retent sleep retention linked list node configuration table 63 * @param num the total number of sleep retention linked list configuration 64 * items 65 * @param priority the priority of the created sleep retention linked list 66 * @param module the bitmap of the module to which the created sleep retention 67 * linked list belongs 68 * @return 69 * - ESP_OK on success 70 * - ESP_ERR_NO_MEM not enough memory for sleep retention 71 * - ESP_ERR_INVALID_ARG if either of the arguments is out of range 72 */ 73 esp_err_t sleep_retention_entries_create(const sleep_retention_entries_config_t retent[], int num, regdma_link_priority_t priority, int module); 74 75 /** 76 * @brief Destroy a runtime sleep retention linked list 77 * 78 * @param module the bitmap of the module to be destroyed 79 */ 80 void sleep_retention_entries_destroy(int module); 81 82 /** 83 * @brief Print all runtime sleep retention linked lists 84 */ 85 void sleep_retention_entries_show_memories(void); 86 87 /** 88 * @brief Find the linked list node with the unique id 89 * 90 * @param id the unique identifier of specified linked list node 91 * 92 * @return NULL or the address of the linked list node found 93 */ 94 void * sleep_retention_find_link_by_id(int id); 95 96 /** 97 * @brief Get the head pointer of all entry linked list of REGDMA 98 * 99 * @param entries buffer for getting results 100 */ 101 void sleep_retention_entries_get(sleep_retention_entries_t *entries); 102 103 #if SOC_PM_RETENTION_HAS_CLOCK_BUG 104 /** 105 * @brief Software trigger REGDMA to do extra linked list retention 106 * 107 * @param backup_or_restore true for backup register context to memory 108 * or false for restore to register from memory 109 */ 110 void sleep_retention_do_extra_retention(bool backup_or_restore); 111 112 void sleep_retention_module_deinit(void); 113 #endif 114 115 /** 116 * @brief Get all registered modules that require sleep retention 117 * 118 * This is an unprotected interface for getting a bitmap of all modules that 119 * require sleep retention. 120 * 121 * It can only be called by the sleep procedure. 122 * 123 * @return the bitmap of all modules requiring sleep retention 124 */ 125 uint32_t sleep_retention_get_modules(void); 126 127 #if SOC_PM_RETENTION_HAS_REGDMA_POWER_BUG 128 /** 129 * @brief Software trigger REGDMA to do system linked list retention 130 * 131 * @param backup_or_restore true for backup register context to memory 132 * or false for restore to register from memory 133 */ 134 void sleep_retention_do_system_retention(bool backup_or_restore); 135 #endif 136 137 #endif // SOC_PAU_SUPPORTED 138 139 #ifdef __cplusplus 140 } 141 #endif 142
