1 /* 2 * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include <stdint.h> 9 #include <stdio.h> 10 #include "esp_err.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** 17 * @brief ETM channel handle 18 */ 19 typedef struct esp_etm_channel_t *esp_etm_channel_handle_t; 20 21 /** 22 * @brief ETM event handle 23 */ 24 typedef struct esp_etm_event_t *esp_etm_event_handle_t; 25 26 /** 27 * @brief ETM task handle 28 */ 29 typedef struct esp_etm_task_t *esp_etm_task_handle_t; 30 31 /** 32 * @brief ETM channel configuration 33 */ 34 typedef struct { 35 36 } esp_etm_channel_config_t; 37 38 /** 39 * @brief Allocate an ETM channel 40 * 41 * @note The channel can later be freed by `esp_etm_del_channel` 42 * 43 * @param[in] config ETM channel configuration 44 * @param[out] ret_chan Returned ETM channel handle 45 * @return 46 * - ESP_OK: Allocate ETM channel successfully 47 * - ESP_ERR_INVALID_ARG: Allocate ETM channel failed because of invalid argument 48 * - ESP_ERR_NO_MEM: Allocate ETM channel failed because of out of memory 49 * - ESP_ERR_NOT_FOUND: Allocate ETM channel failed because all channels are used up and no more free one 50 * - ESP_FAIL: Allocate ETM channel failed because of other reasons 51 */ 52 esp_err_t esp_etm_new_channel(const esp_etm_channel_config_t *config, esp_etm_channel_handle_t *ret_chan); 53 54 /** 55 * @brief Delete an ETM channel 56 * 57 * @param[in] chan ETM channel handle that created by `esp_etm_new_channel` 58 * @return 59 * - ESP_OK: Delete ETM channel successfully 60 * - ESP_ERR_INVALID_ARG: Delete ETM channel failed because of invalid argument 61 * - ESP_FAIL: Delete ETM channel failed because of other reasons 62 */ 63 esp_err_t esp_etm_del_channel(esp_etm_channel_handle_t chan); 64 65 /** 66 * @brief Enable ETM channel 67 * 68 * @note This function will transit the channel state from init to enable. 69 * 70 * @param[in] chan ETM channel handle that created by `esp_etm_new_channel` 71 * @return 72 * - ESP_OK: Enable ETM channel successfully 73 * - ESP_ERR_INVALID_ARG: Enable ETM channel failed because of invalid argument 74 * - ESP_ERR_INVALID_STATE: Enable ETM channel failed because the channel has been enabled already 75 * - ESP_FAIL: Enable ETM channel failed because of other reasons 76 */ 77 esp_err_t esp_etm_channel_enable(esp_etm_channel_handle_t chan); 78 79 /** 80 * @brief Disable ETM channel 81 * 82 * @note This function will transit the channel state from enable to init. 83 * 84 * @param[in] chan ETM channel handle that created by `esp_etm_new_channel` 85 * @return 86 * - ESP_OK: Disable ETM channel successfully 87 * - ESP_ERR_INVALID_ARG: Disable ETM channel failed because of invalid argument 88 * - ESP_ERR_INVALID_STATE: Disable ETM channel failed because the channel is not enabled yet 89 * - ESP_FAIL: Disable ETM channel failed because of other reasons 90 */ 91 esp_err_t esp_etm_channel_disable(esp_etm_channel_handle_t chan); 92 93 /** 94 * @brief Connect an ETM event to an ETM task via a previously allocated ETM channel 95 * 96 * @note Setting the ETM event/task handle to NULL means to disconnect the channel from any event/task 97 * 98 * @param[in] chan ETM channel handle that created by `esp_etm_new_channel` 99 * @param[in] event ETM event handle obtained from a driver/peripheral, e.g. `xxx_new_etm_event` 100 * @param[in] task ETM task handle obtained from a driver/peripheral, e.g. `xxx_new_etm_task` 101 * @return 102 * - ESP_OK: Connect ETM event and task to the channel successfully 103 * - ESP_ERR_INVALID_ARG: Connect ETM event and task to the channel failed because of invalid argument 104 * - ESP_FAIL: Connect ETM event and task to the channel failed because of other reasons 105 */ 106 esp_err_t esp_etm_channel_connect(esp_etm_channel_handle_t chan, esp_etm_event_handle_t event, esp_etm_task_handle_t task); 107 108 /** 109 * @brief Delete ETM event 110 * 111 * @note Although the ETM event comes from various peripherals, we provide the same user API to delete the event handle seamlessly. 112 * 113 * @param[in] event ETM event handle obtained from a driver/peripheral, e.g. `xxx_new_etm_event` 114 * @return 115 * - ESP_OK: Delete ETM event successfully 116 * - ESP_ERR_INVALID_ARG: Delete ETM event failed because of invalid argument 117 * - ESP_FAIL: Delete ETM event failed because of other reasons 118 */ 119 esp_err_t esp_etm_del_event(esp_etm_event_handle_t event); 120 121 /** 122 * @brief Delete ETM task 123 * 124 * @note Although the ETM task comes from various peripherals, we provide the same user API to delete the task handle seamlessly. 125 * 126 * @param[in] task ETM task handle obtained from a driver/peripheral, e.g. `xxx_new_etm_task` 127 * @return 128 * - ESP_OK: Delete ETM task successfully 129 * - ESP_ERR_INVALID_ARG: Delete ETM task failed because of invalid argument 130 * - ESP_FAIL: Delete ETM task failed because of other reasons 131 */ 132 esp_err_t esp_etm_del_task(esp_etm_task_handle_t task); 133 134 /** 135 * @brief Dump ETM channel usages to the given IO stream 136 * 137 * @param[in] out_stream IO stream (e.g. stdout) 138 * @return 139 * - ESP_OK: Dump ETM channel usages successfully 140 * - ESP_ERR_INVALID_ARG: Dump ETM channel usages failed because of invalid argument 141 * - ESP_FAIL: Dump ETM channel usages failed because of other reasons 142 */ 143 esp_err_t esp_etm_dump(FILE *out_stream); 144 145 #ifdef __cplusplus 146 } 147 #endif 148
