feat(esp_hw_support): implement of sleep retention module initialize and dependency management

components/esp_hw_support/include/esp_private/sleep_retention.h

@@ -28,6 +28,21 @@ typedef periph_retention_module_bitmap_t    sleep_retention_module_bitmap_t;
 typedef regdma_entry_buf_t                  sleep_retention_entries_t;
 typedef regdma_entries_config_t             sleep_retention_entries_config_t;
 
+typedef esp_err_t (*sleep_retention_callback_t)(void *args);
+
+typedef struct {
+    sleep_retention_callback_t handle;
+    void *arg;
+} sleep_retention_create_callback_t;
+
+typedef struct {
+    sleep_retention_create_callback_t create;  /*!< A function handle is used to register the implementation of creating a sleep retention linked list and is executed when the corresponding module is created */
+} sleep_retention_module_callbacks_t;
+
+typedef enum {
+    SLEEP_RETENTION_MODULE_ATTR_PASSIVE = 0x1
+} sleep_retention_module_attribute_t;
+
 /**
  * @brief Create a runtime sleep retention linked list
  *
@@ -44,13 +59,6 @@ typedef regdma_entries_config_t             sleep_retention_entries_config_t;
  */
 esp_err_t sleep_retention_entries_create(const sleep_retention_entries_config_t retent[], int num, regdma_link_priority_t priority, sleep_retention_module_t module);
 
-/**
- * @brief Destroy a runtime sleep retention linked list
- *
- * @param module   the bitmap of the module to be destroyed
- */
-void sleep_retention_entries_destroy(sleep_retention_module_t module);
-
 /**
  * @brief Print all runtime sleep retention linked lists
  */
@@ -72,6 +80,77 @@ void * sleep_retention_find_link_by_id(int id);
  */
 void sleep_retention_entries_get(sleep_retention_entries_t *entries);
 
+typedef struct sleep_retention_module_init_param {
+    sleep_retention_module_callbacks_t  cbs;        /*!< The callbacks list of the initialize module */
+    sleep_retention_module_attribute_t  attribute;  /*!< A bitmap indicating attribute of the initialize module */
+    sleep_retention_module_bitmap_t     depends;    /*!< A bitmap identifying all modules that the current module depends on */
+} sleep_retention_module_init_param_t;
+
+/**
+ * @brief sleep retention initialization for the module
+ *
+ * @param module   the module number that needs initialization
+ * @param param    the initialize parameters for module sleep retention initialization
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NO_MEM not enough memory for sleep retention
+ *      - ESP_ERR_INVALID_ARG if either of the arguments is out of range
+ *      - ESP_ERR_INVALID_STATE if the retention context of module already been allocated
+ */
+esp_err_t sleep_retention_module_init(sleep_retention_module_t module, sleep_retention_module_init_param_t *param);
+
+/**
+ * @brief sleep retention de-initialization for the module
+ *
+ * @param module   the module number that needs de-initialization
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if either of the arguments is out of range
+ *      - ESP_ERR_INVALID_STATE if the retention context of module already been allocated
+ */
+esp_err_t sleep_retention_module_deinit(sleep_retention_module_t module);
+
+/**
+ * @brief Allocate the sleep retention context for the module
+ *
+ * @param module   the module number that need to allocating sleep retention context
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NO_MEM not enough memory for sleep retention
+ *      - ESP_ERR_INVALID_ARG if either of the arguments is out of range
+ *      - ESP_ERR_INVALID_STATE if the module is de-initialized
+ *      - ESP_ERR_NOT_ALLOWED if the attribute of module is set to SLEEP_RETENTION_MODULE_ATTR_PASSIVE
+ */
+esp_err_t sleep_retention_module_allocate(sleep_retention_module_t module);
+
+/**
+ * @brief Free the sleep retention context for the module
+ *
+ * @param module   the module number that need to free sleep retention context
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if either of the arguments is out of range
+ *      - ESP_ERR_INVALID_STATE if the module is de-initialized
+ *      - ESP_ERR_NOT_ALLOWED if the attribute of module is set to SLEEP_RETENTION_MODULE_ATTR_PASSIVE
+ */
+esp_err_t sleep_retention_module_free(sleep_retention_module_t module);
+
+/**
+ * @brief Get all initialized modules that require sleep retention
+ *
+ * This is an unprotected interface for getting a bitmap of all modules that
+ * require sleep retention.
+ *
+ * It can only be called by the sleep procedure.
+ *
+ * @return the bitmap for all modules that require sleep retention
+ */
+uint32_t sleep_retention_get_inited_modules(void);
+
 /**
  * @brief Get all created modules that require sleep retention
  *
@@ -80,7 +159,8 @@ void sleep_retention_entries_get(sleep_retention_entries_t *entries);
  *
  * It can only be called by the sleep procedure.
  *
- * @return the bitmap of all modules requiring sleep retention
+ * @return the bitmap for all modules that have successfully created a sleep
+ * retention context
  */
 uint32_t sleep_retention_get_created_modules(void);