1 /* 2 * SPDX-FileCopyrightText: 2017-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef ESP_APP_TRACE_H_ 7 #define ESP_APP_TRACE_H_ 8 9 #include <stdarg.h> 10 #include "esp_err.h" 11 #include "esp_app_trace_util.h" // ESP_APPTRACE_TMO_INFINITE 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * Application trace data destinations bits. 19 */ 20 typedef enum { 21 ESP_APPTRACE_DEST_JTAG = 1, ///< JTAG destination 22 ESP_APPTRACE_DEST_TRAX = ESP_APPTRACE_DEST_JTAG, ///< xxx_TRAX name is obsolete, use more common xxx_JTAG 23 ESP_APPTRACE_DEST_UART0, ///< UART0 destination 24 ESP_APPTRACE_DEST_MAX = ESP_APPTRACE_DEST_UART0, 25 ESP_APPTRACE_DEST_NUM 26 } esp_apptrace_dest_t; 27 28 /** 29 * @brief Initializes application tracing module. 30 * 31 * @note Should be called before any esp_apptrace_xxx call. 32 * 33 * @return ESP_OK on success, otherwise see esp_err_t 34 */ 35 esp_err_t esp_apptrace_init(void); 36 37 /** 38 * @brief Configures down buffer. 39 * @note Needs to be called before initiating any data transfer using esp_apptrace_buffer_get and esp_apptrace_write. 40 * This function does not protect internal data by lock. 41 * 42 * @param buf Address of buffer to use for down channel (host to target) data. 43 * @param size Size of the buffer. 44 */ 45 void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size); 46 47 /** 48 * @brief Allocates buffer for trace data. 49 * After data in buffer are ready to be sent off esp_apptrace_buffer_put must be called to indicate it. 50 * 51 * @param dest Indicates HW interface to send data. 52 * @param size Size of data to write to trace buffer. 53 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 54 * 55 * @return non-NULL on success, otherwise NULL. 56 */ 57 uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo); 58 59 /** 60 * @brief Indicates that the data in buffer are ready to be sent off. 61 * This function is a counterpart of and must be preceeded by esp_apptrace_buffer_get. 62 * 63 * @param dest Indicates HW interface to send data. Should be identical to the same parameter in call to esp_apptrace_buffer_get. 64 * @param ptr Address of trace buffer to release. Should be the value returned by call to esp_apptrace_buffer_get. 65 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 66 * 67 * @return ESP_OK on success, otherwise see esp_err_t 68 */ 69 esp_err_t esp_apptrace_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo); 70 71 /** 72 * @brief Writes data to trace buffer. 73 * 74 * @param dest Indicates HW interface to send data. 75 * @param data Address of data to write to trace buffer. 76 * @param size Size of data to write to trace buffer. 77 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 78 * 79 * @return ESP_OK on success, otherwise see esp_err_t 80 */ 81 esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_t size, uint32_t tmo); 82 83 /** 84 * @brief vprintf-like function to sent log messages to host via specified HW interface. 85 * 86 * @param dest Indicates HW interface to send data. 87 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 88 * @param fmt Address of format string. 89 * @param ap List of arguments. 90 * 91 * @return Number of bytes written. 92 */ 93 int esp_apptrace_vprintf_to(esp_apptrace_dest_t dest, uint32_t tmo, const char *fmt, va_list ap); 94 95 /** 96 * @brief vprintf-like function to sent log messages to host. 97 * 98 * @param fmt Address of format string. 99 * @param ap List of arguments. 100 * 101 * @return Number of bytes written. 102 */ 103 int esp_apptrace_vprintf(const char *fmt, va_list ap); 104 105 /** 106 * @brief Flushes remaining data in trace buffer to host. 107 * 108 * @param dest Indicates HW interface to flush data on. 109 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 110 * 111 * @return ESP_OK on success, otherwise see esp_err_t 112 */ 113 esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo); 114 115 /** 116 * @brief Flushes remaining data in trace buffer to host without locking internal data. 117 * This is special version of esp_apptrace_flush which should be called from panic handler. 118 * 119 * @param dest Indicates HW interface to flush data on. 120 * @param min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only. 121 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 122 * 123 * @return ESP_OK on success, otherwise see esp_err_t 124 */ 125 esp_err_t esp_apptrace_flush_nolock(esp_apptrace_dest_t dest, uint32_t min_sz, uint32_t tmo); 126 127 /** 128 * @brief Reads host data from trace buffer. 129 * 130 * @param dest Indicates HW interface to read the data on. 131 * @param data Address of buffer to put data from trace buffer. 132 * @param size Pointer to store size of read data. Before call to this function pointed memory must hold requested size of data 133 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 134 * 135 * @return ESP_OK on success, otherwise see esp_err_t 136 */ 137 esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size, uint32_t tmo); 138 139 /** 140 * @brief Retrieves incoming data buffer if any. 141 * After data in buffer are processed esp_apptrace_down_buffer_put must be called to indicate it. 142 * 143 * @param dest Indicates HW interface to receive data. 144 * @param size Address to store size of available data in down buffer. Must be initialized with requested value. 145 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 146 * 147 * @return non-NULL on success, otherwise NULL. 148 */ 149 uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t tmo); 150 151 /** 152 * @brief Indicates that the data in down buffer are processed. 153 * This function is a counterpart of and must be preceeded by esp_apptrace_down_buffer_get. 154 * 155 * @param dest Indicates HW interface to receive data. Should be identical to the same parameter in call to esp_apptrace_down_buffer_get. 156 * @param ptr Address of trace buffer to release. Should be the value returned by call to esp_apptrace_down_buffer_get. 157 * @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. 158 * 159 * @return ESP_OK on success, otherwise see esp_err_t 160 */ 161 esp_err_t esp_apptrace_down_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo); 162 163 /** 164 * @brief Checks whether host is connected. 165 * 166 * @param dest Indicates HW interface to use. 167 * 168 * @return true if host is connected, otherwise false 169 */ 170 bool esp_apptrace_host_is_connected(esp_apptrace_dest_t dest); 171 172 /** 173 * @brief Opens file on host. 174 * This function has the same semantic as 'fopen' except for the first argument. 175 * 176 * @param dest Indicates HW interface to use. 177 * @param path Path to file. 178 * @param mode Mode string. See fopen for details. 179 * 180 * @return non zero file handle on success, otherwise 0 181 */ 182 void *esp_apptrace_fopen(esp_apptrace_dest_t dest, const char *path, const char *mode); 183 184 /** 185 * @brief Closes file on host. 186 * This function has the same semantic as 'fclose' except for the first argument. 187 * 188 * @param dest Indicates HW interface to use. 189 * @param stream File handle returned by esp_apptrace_fopen. 190 * 191 * @return Zero on success, otherwise non-zero. See fclose for details. 192 */ 193 int esp_apptrace_fclose(esp_apptrace_dest_t dest, void *stream); 194 195 /** 196 * @brief Writes to file on host. 197 * This function has the same semantic as 'fwrite' except for the first argument. 198 * 199 * @param dest Indicates HW interface to use. 200 * @param ptr Address of data to write. 201 * @param size Size of an item. 202 * @param nmemb Number of items to write. 203 * @param stream File handle returned by esp_apptrace_fopen. 204 * 205 * @return Number of written items. See fwrite for details. 206 */ 207 size_t esp_apptrace_fwrite(esp_apptrace_dest_t dest, const void *ptr, size_t size, size_t nmemb, void *stream); 208 209 /** 210 * @brief Read file on host. 211 * This function has the same semantic as 'fread' except for the first argument. 212 * 213 * @param dest Indicates HW interface to use. 214 * @param ptr Address to store read data. 215 * @param size Size of an item. 216 * @param nmemb Number of items to read. 217 * @param stream File handle returned by esp_apptrace_fopen. 218 * 219 * @return Number of read items. See fread for details. 220 */ 221 size_t esp_apptrace_fread(esp_apptrace_dest_t dest, void *ptr, size_t size, size_t nmemb, void *stream); 222 223 /** 224 * @brief Set position indicator in file on host. 225 * This function has the same semantic as 'fseek' except for the first argument. 226 * 227 * @param dest Indicates HW interface to use. 228 * @param stream File handle returned by esp_apptrace_fopen. 229 * @param offset Offset. See fseek for details. 230 * @param whence Position in file. See fseek for details. 231 * 232 * @return Zero on success, otherwise non-zero. See fseek for details. 233 */ 234 int esp_apptrace_fseek(esp_apptrace_dest_t dest, void *stream, long offset, int whence); 235 236 /** 237 * @brief Get current position indicator for file on host. 238 * This function has the same semantic as 'ftell' except for the first argument. 239 * 240 * @param dest Indicates HW interface to use. 241 * @param stream File handle returned by esp_apptrace_fopen. 242 * 243 * @return Current position in file. See ftell for details. 244 */ 245 int esp_apptrace_ftell(esp_apptrace_dest_t dest, void *stream); 246 247 /** 248 * @brief Indicates to the host that all file operations are completed. 249 * This function should be called after all file operations are finished and 250 * indicate to the host that it can perform cleanup operations (close open files etc.). 251 * 252 * @param dest Indicates HW interface to use. 253 * 254 * @return ESP_OK on success, otherwise see esp_err_t 255 */ 256 int esp_apptrace_fstop(esp_apptrace_dest_t dest); 257 258 /** 259 * @brief Triggers gcov info dump. 260 * This function waits for the host to connect to target before dumping data. 261 */ 262 void esp_gcov_dump(void); 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif 269
