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