Zephyr API Documentation 4.0.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
coredump.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Intel Corporation.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#ifndef ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_
8#define ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_
9
10#include <stddef.h>
11#include <stdint.h>
12#include <sys/types.h>
13
14/*
15 * Define COREDUMP_*_STR as public to allow coredump_backend_other to re-use
16 * these strings if necessary
17 */
18#define COREDUMP_BEGIN_STR "BEGIN#"
19#define COREDUMP_END_STR "END#"
20#define COREDUMP_ERROR_STR "ERROR CANNOT DUMP#"
21
22/*
23 * Need to prefix coredump strings to make it easier to parse
24 * as log module adds its own prefixes.
25 */
26#define COREDUMP_PREFIX_STR "#CD:"
27
68
126
138
139#ifdef CONFIG_DEBUG_COREDUMP
140
141#include <zephyr/toolchain.h>
142#include <zephyr/arch/cpu.h>
143#include <zephyr/sys/byteorder.h>
144
145#define COREDUMP_HDR_VER 2
146
147#define COREDUMP_ARCH_HDR_ID 'A'
148
149#define THREADS_META_HDR_ID 'T'
150#define THREADS_META_HDR_VER 1
151
152#define COREDUMP_MEM_HDR_ID 'M'
153#define COREDUMP_MEM_HDR_VER 1
154
155/* Target code */
156enum coredump_tgt_code {
157 COREDUMP_TGT_UNKNOWN = 0,
158 COREDUMP_TGT_X86,
159 COREDUMP_TGT_X86_64,
160 COREDUMP_TGT_ARM_CORTEX_M,
161 COREDUMP_TGT_RISC_V,
162 COREDUMP_TGT_XTENSA,
163 COREDUMP_TGT_ARM64,
164};
165
166/* Coredump header */
167struct coredump_hdr_t {
168 /* 'Z', 'E' */
169 char id[2];
170
171 /* Header version */
172 uint16_t hdr_version;
173
174 /* Target code */
175 uint16_t tgt_code;
176
177 /* Pointer size in Log2 */
178 uint8_t ptr_size_bits;
179
180 uint8_t flag;
181
182 /* Coredump Reason given */
183 unsigned int reason;
184} __packed;
185
186/* Architecture-specific block header */
187struct coredump_arch_hdr_t {
188 /* COREDUMP_ARCH_HDR_ID */
189 char id;
190
191 /* Header version */
192 uint16_t hdr_version;
193
194 /* Number of bytes in this block (excluding header) */
195 uint16_t num_bytes;
196} __packed;
197
198/* Threads metadata header */
199struct coredump_threads_meta_hdr_t {
200 /* THREADS_META_HDR_ID */
201 char id;
202
203 /* Header version */
204 uint16_t hdr_version;
205
206 /* Number of bytes in this block (excluding header) */
207 uint16_t num_bytes;
208} __packed;
209
210/* Memory block header */
211struct coredump_mem_hdr_t {
212 /* COREDUMP_MEM_HDR_ID */
213 char id;
214
215 /* Header version */
216 uint16_t hdr_version;
217
218 /* Address of start of memory region */
219 uintptr_t start;
220
221 /* Address of end of memory region */
222 uintptr_t end;
223} __packed;
224
225typedef void (*coredump_backend_start_t)(void);
226typedef void (*coredump_backend_end_t)(void);
227typedef void (*coredump_backend_buffer_output_t)(uint8_t *buf, size_t buflen);
228typedef int (*coredump_backend_query_t)(enum coredump_query_id query_id,
229 void *arg);
230typedef int (*coredump_backend_cmd_t)(enum coredump_cmd_id cmd_id,
231 void *arg);
232
233struct coredump_backend_api {
234 /* Signal to backend of the start of coredump. */
235 coredump_backend_start_t start;
236
237 /* Signal to backend of the end of coredump. */
238 coredump_backend_end_t end;
239
240 /* Raw buffer output */
241 coredump_backend_buffer_output_t buffer_output;
242
243 /* Perform query on backend */
244 coredump_backend_query_t query;
245
246 /* Perform command on backend */
247 coredump_backend_cmd_t cmd;
248};
249
250void coredump(unsigned int reason, const struct arch_esf *esf,
251 struct k_thread *thread);
252void coredump_memory_dump(uintptr_t start_addr, uintptr_t end_addr);
253void coredump_buffer_output(uint8_t *buf, size_t buflen);
254
255int coredump_query(enum coredump_query_id query_id, void *arg);
256int coredump_cmd(enum coredump_cmd_id cmd_id, void *arg);
257
258#else
259
260static inline void coredump(unsigned int reason, const struct arch_esf *esf,
261 struct k_thread *thread)
262{
263 ARG_UNUSED(reason);
264 ARG_UNUSED(esf);
265 ARG_UNUSED(thread);
266}
267
268static inline void coredump_memory_dump(uintptr_t start_addr, uintptr_t end_addr)
269{
270 ARG_UNUSED(start_addr);
271 ARG_UNUSED(end_addr);
272}
273
274static inline void coredump_buffer_output(uint8_t *buf, size_t buflen)
275{
276 ARG_UNUSED(buf);
277 ARG_UNUSED(buflen);
278}
279
280static inline int coredump_query(enum coredump_query_id query_id, void *arg)
281{
282 ARG_UNUSED(query_id);
283 ARG_UNUSED(arg);
284 return -ENOTSUP;
285}
286
287static inline int coredump_cmd(enum coredump_cmd_id query_id, void *arg)
288{
289 ARG_UNUSED(query_id);
290 ARG_UNUSED(arg);
291 return -ENOTSUP;
292}
293
294#endif /* CONFIG_DEBUG_COREDUMP */
295
357#endif /* ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_ */
coredump_query_id
Query ID.
Definition coredump.h:39
coredump_cmd_id
Command ID.
Definition coredump.h:70
static int coredump_cmd(enum coredump_cmd_id query_id, void *arg)
Perform command on coredump subsystem.
Definition coredump.h:287
static int coredump_query(enum coredump_query_id query_id, void *arg)
Perform query on coredump subsystem.
Definition coredump.h:280
static void coredump_memory_dump(uintptr_t start_addr, uintptr_t end_addr)
Dump memory region.
Definition coredump.h:268
static void coredump(unsigned int reason, const struct arch_esf *esf, struct k_thread *thread)
Perform coredump.
Definition coredump.h:260
static void coredump_buffer_output(uint8_t *buf, size_t buflen)
Output the buffer via coredump.
Definition coredump.h:274
@ COREDUMP_QUERY_HAS_STORED_DUMP
Check if there is a stored coredump from backend.
Definition coredump.h:53
@ COREDUMP_QUERY_GET_STORED_DUMP_SIZE
Returns:
Definition coredump.h:61
@ COREDUMP_QUERY_MAX
Max value for query ID.
Definition coredump.h:66
@ COREDUMP_QUERY_GET_ERROR
Returns error code from backend.
Definition coredump.h:43
@ COREDUMP_CMD_COPY_STORED_DUMP
Copy the raw stored coredump.
Definition coredump.h:108
@ COREDUMP_CMD_MAX
Max value for command ID.
Definition coredump.h:124
@ COREDUMP_CMD_INVALIDATE_STORED_DUMP
Invalidate the stored coredump.
Definition coredump.h:119
@ COREDUMP_CMD_ERASE_STORED_DUMP
Erase the stored coredump.
Definition coredump.h:97
@ COREDUMP_CMD_VERIFY_STORED_DUMP
Verify that the stored coredump is valid.
Definition coredump.h:87
@ COREDUMP_CMD_CLEAR_ERROR
Clear error code from backend.
Definition coredump.h:76
static void cmd(uint32_t command)
Execute a display list command by co-processor engine.
Definition ft8xx_reference_api.h:153
#define ENOTSUP
Unsupported value.
Definition errno.h:114
__INTPTR_TYPE__ off_t
Definition types.h:36
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINTPTR_TYPE__ uintptr_t
Definition stdint.h:105
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Exception Stack Frame.
Definition exception.h:60
Coredump copy command (COREDUMP_CMD_COPY_STORED_DUMP) argument definition.
Definition coredump.h:128
off_t offset
Copy offset.
Definition coredump.h:130
uint8_t * buffer
Copy destination buffer.
Definition coredump.h:133
size_t length
Copy length.
Definition coredump.h:136
Thread Structure.
Definition thread.h:259
Byte order helpers.
Macros to abstract toolchain specific capabilities.