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_COMMON_H_
15 #define ESP_CORE_DUMP_COMMON_H_
16
17 #include "freertos/FreeRTOS.h"
18 #include "soc/cpu.h"
19 #include "esp_debug_helpers.h"
20 #include "esp_app_format.h"
21 #include "esp_core_dump_types.h"
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 /**
28 * @brief Enumeration of the existing memory regions.
29 * One can use these definitions to retrieve the start address and/or the size
30 * of a specific region using the functions below.
31 */
32 typedef enum {
33 COREDUMP_MEMORY_DRAM,
34 COREDUMP_MEMORY_IRAM,
35 COREDUMP_MEMORY_RTC,
36 COREDUMP_MEMORY_RTC_FAST,
37 COREDUMP_MEMORY_MAX,
38 COREDUMP_MEMORY_START = COREDUMP_MEMORY_DRAM
39 } coredump_region_t;
40
41 /**
42 * @brief Get the (FreeRTOS) task handle for the current task.
43 *
44 * @return Task handle of the current task.
45 */
46 core_dump_task_handle_t esp_core_dump_get_current_task_handle(void);
47
48 /**
49 * @brief Get next task handle of a given handle.
50 *
51 * @param handle Task handle to get the next handle from.
52 *
53 * @return Next task handle.
54 */
55 core_dump_task_handle_t esp_core_dump_get_next_task(core_dump_task_handle_t handle);
56
57 /**
58 * @brief Get a task snapshot from a given handle.
59 *
60 * @param handle Task handle to get the snapshot from.
61 * @param task Returned task header.
62 * @param interrupted_stack Backup of the task stack if the handle passed is the task
63 * that crashed and if it crashed within an ISR context.
64 *
65 * @return false is the task is broken, true else.
66 */
67 bool esp_core_dump_get_task_snapshot(core_dump_task_handle_t handle,
68 core_dump_task_header_t *task,
69 core_dump_mem_seg_header_t *interrupted_stack);
70
71 /**
72 * @brief Reset tasks snapshot iterator.
73 */
74 void esp_core_dump_reset_tasks_snapshots_iter(void);
75
76
77 /**
78 * @brief Check if the TCB passed as a parameter is sane.
79 *
80 * @param address Address of the TCB to check.
81 *
82 * @return true if the TCB is sane, false else.
83 */
84 bool esp_core_dump_tcb_addr_is_sane(uint32_t addr);
85
86 /**
87 * @brief Get the number of RAM segments.
88 *
89 * @return Number of RAM segments.
90 */
91 uint32_t esp_core_dump_get_user_ram_segments(void);
92
93
94 /**
95 * @brief Get start address and size of a memory region.
96 *
97 * @param region Memory region to get information about.
98 * @param start Pointer that will be filled with the region start address.
99 * Must **not** be NULL.
100 *
101 * @return Size, in bytes, of the memory region.
102 */
103 int esp_core_dump_get_user_ram_info(coredump_region_t region, uint32_t *start);
104
105
106 /**
107 * @brief Check if the current task is in an ISR.
108 *
109 * @return true if task in an ISR, false else.
110 */
111 bool esp_core_dump_in_isr_context(void);
112
113
114 /**
115 * @brief Get the size all the memory regions (DRAM, RTC, RTC_FAST, IRAM)
116 *
117 * @return Size, in bytes, of all the memory regions.
118 */
119 uint32_t esp_core_dump_get_user_ram_size(void);
120
121
122 /**
123 * @brief Get TCB length, in bytes.
124 *
125 * @return Length of TCB, in bytes.
126 */
esp_core_dump_get_tcb_len(void)127 static inline uint32_t esp_core_dump_get_tcb_len(void)
128 {
129 return (sizeof(StaticTask_t) % sizeof(uint32_t)) ?
130 ((sizeof(StaticTask_t) / sizeof(uint32_t) + 1) * sizeof(uint32_t)) :
131 sizeof(StaticTask_t);
132 }
133
134 /**
135 * @brief Get the length, in bytes, of a given memory location. Padding is
136 * taken into account in this calculation.
137 *
138 * @param start Start address of the momery location.
139 * @param end End address of the memory location.
140 *
141 * @return Size of the memory location, multiple of sizeof(uint32_t).
142 */
esp_core_dump_get_memory_len(uint32_t start,uint32_t end)143 static inline uint32_t esp_core_dump_get_memory_len(uint32_t start, uint32_t end)
144 {
145 const uint32_t len = end - start;
146 // Take stack padding into account
147 return (len + sizeof(uint32_t) - 1) & ~(sizeof(uint32_t) - 1);
148 }
149
150
151 #ifdef __cplusplus
152 }
153 #endif
154
155 #endif
156
