1 // Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #ifndef ESP_CORE_DUMP_H_ 15 #define ESP_CORE_DUMP_H_ 16 17 #include "sdkconfig.h" 18 #include <stddef.h> 19 #include "esp_err.h" 20 #include "esp_private/panic_internal.h" 21 #include "esp_core_dump_summary_port.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #define APP_ELF_SHA256_SZ (CONFIG_APP_RETRIEVE_LEN_ELF_SHA + 1) 28 29 #if CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH && CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF 30 31 /** 32 * @brief Core dump summary, Most meaningful contents of the core dump 33 * are accommodated in this structure 34 */ 35 typedef struct { 36 uint32_t exc_tcb; /*!< TCB pointer to the task causing exception */ 37 char exc_task[16]; /*!< Name of the task that caused exception */ 38 uint32_t exc_pc; /*!< Program counter for exception */ 39 esp_core_dump_bt_info_t exc_bt_info; /*!< Backtrace information for task causing exception */ 40 uint32_t core_dump_version; /*!< Core dump version */ 41 uint8_t app_elf_sha256[APP_ELF_SHA256_SZ]; /*!< Crashing application's SHA256 sum as a string */ 42 esp_core_dump_summary_extra_info_t ex_info; /*!< Architecture specific extra data */ 43 } esp_core_dump_summary_t; 44 45 #endif /* CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH && CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF */ 46 47 /**************************************************************************************/ 48 /******************************** EXCEPTION MODE API **********************************/ 49 /**************************************************************************************/ 50 51 /** 52 * @brief Initializes core dump module internal data. 53 * 54 * @note Should be called at system startup. 55 */ 56 void esp_core_dump_init(void); 57 58 /** 59 * @brief Saves core dump to flash. 60 * 61 * The structure of data stored in flash is as follows: 62 * 63 * | TOTAL_LEN | VERSION | TASKS_NUM | TCB_SIZE | 64 * | TCB_ADDR_1 | STACK_TOP_1 | STACK_END_1 | TCB_1 | STACK_1 | 65 * . . . . 66 * . . . . 67 * | TCB_ADDR_N | STACK_TOP_N | STACK_END_N | TCB_N | STACK_N | 68 * | CHECKSUM | 69 * 70 * Core dump in flash consists of header and data for every task in the system at the moment of crash. 71 * For flash data integrity, a checksum is used at the end of core the dump data. 72 * The structure of core dump data is described below in details. 73 * 1) Core dump starts with header: 74 * 1.1) TOTAL_LEN is total length of core dump data in flash including the checksum. Size is 4 bytes. 75 * 1.2) VERSION field keeps 4 byte version of core dump. 76 * 1.2) TASKS_NUM is the number of tasks for which data are stored. Size is 4 bytes. 77 * 1.3) TCB_SIZE is the size of task's TCB structure. Size is 4 bytes. 78 * 2) Core dump header is followed by the data for every task in the system. 79 * Task data are started with task header: 80 * 2.1) TCB_ADDR is the address of TCB in memory. Size is 4 bytes. 81 * 2.2) STACK_TOP is the top of task's stack (address of the topmost stack item). Size is 4 bytes. 82 * 2.2) STACK_END is the end of task's stack (address from which task's stack starts). Size is 4 bytes. 83 * 3) Task header is followed by TCB data. Size is TCB_SIZE bytes. 84 * 4) Task's stack is placed after TCB data. Size is (STACK_END - STACK_TOP) bytes. 85 * 5) The checksum is placed at the end of the data. 86 */ 87 void esp_core_dump_to_flash(panic_info_t *info); 88 89 /** 90 * @brief Print base64-encoded core dump to UART. 91 * 92 * The structure of core dump data is the same as for data stored in flash (@see esp_core_dump_to_flash) with some notes: 93 * 1) The checksum is not present in core dump printed to UART. 94 * 2) Since checksum is omitted TOTAL_LEN does not include its size. 95 * 3) Printed base64 data are surrounded with special messages to help user recognize the start and end of actual data. 96 */ 97 void esp_core_dump_to_uart(panic_info_t *info); 98 99 /**************************************************************************************/ 100 /*********************************** USER MODE API ************************************/ 101 /**************************************************************************************/ 102 103 /** 104 * @brief Check integrity of coredump data in flash. 105 * This function reads the coredump data while calculating their checksum. If it 106 * doesn't match the checksum written on flash, it means data are corrupted, 107 * an error will be returned. Else, ESP_OK is returned. 108 * 109 * @return `ESP_OK` if core dump is present and valid, `ESP_ERR_NOT_FOUND` if no core dump 110 * is stored in the partition, `ESP_ERR_INVALID_SIZE` or `ESP_ERR_INVALID_CRC` 111 * if the core dump is corrupted, other errors when unable to access flash, in that 112 * case please refer to \see esp_err_t 113 */ 114 esp_err_t esp_core_dump_image_check(void); 115 116 /** 117 * @brief Retrieves address and size of coredump data in flash. 118 * This function is always available, even when core dump is disabled in menuconfig. 119 * 120 * @param out_addr pointer to store image address in flash. 121 * @param out_size pointer to store image size in flash (including checksum). In bytes. 122 * 123 * @return ESP_OK on success, otherwise \see esp_err_t 124 */ 125 esp_err_t esp_core_dump_image_get(size_t* out_addr, size_t *out_size); 126 127 /** 128 * @brief Erases coredump data in flash. esp_core_dump_image_get() will then return 129 * ESP_ERR_NOT_FOUND. Can be used after a coredump has been transmitted successfully. 130 * This function is always available, even when core dump is disabled in menuconfig. 131 * 132 * @return ESP_OK on success, otherwise \see esp_err_t 133 */ 134 esp_err_t esp_core_dump_image_erase(void); 135 136 #if CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH && CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF 137 138 /** 139 * @brief Get the summary of a core dump. 140 * 141 * @param summary Summary of the core dump 142 * 143 * @return ESP_OK on success, otherwise \see esp_err_t 144 * 145 * @note This function works only if coredump is stored in flash and in ELF format 146 * 147 * Example usage: 148 * @code{c} 149 * esp_core_dump_summary_t *summary = malloc(sizeof(esp_core_dump_summary_t)); 150 * if (summary) { 151 * if (esp_core_dump_get_summary(summary) == ESP_OK) { 152 * // Do stuff 153 * } 154 * } 155 * free(summary); 156 * @endcode 157 */ 158 esp_err_t esp_core_dump_get_summary(esp_core_dump_summary_t *summary); 159 160 #endif /* CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH && CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF */ 161 162 #ifdef __cplusplus 163 } 164 #endif 165 166 #endif 167
