coredump.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_
#define ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_
 
#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * Define COREDUMP_*_STR as public to allow coredump_backend_other to re-use
 * these strings if necessary
 */
#define COREDUMP_BEGIN_STR      "BEGIN#"
#define COREDUMP_END_STR        "END#"
#define COREDUMP_ERROR_STR      "ERROR CANNOT DUMP#"
 
/*
 * Need to prefix coredump strings to make it easier to parse
 * as log module adds its own prefixes.
 */
#define COREDUMP_PREFIX_STR     "#CD:"

 

enum coredump_query_id {
        COREDUMP_QUERY_GET_ERROR,

        COREDUMP_QUERY_HAS_STORED_DUMP,

        COREDUMP_QUERY_GET_STORED_DUMP_SIZE,

        COREDUMP_QUERY_MAX
};

enum coredump_cmd_id {
        COREDUMP_CMD_CLEAR_ERROR,

        COREDUMP_CMD_VERIFY_STORED_DUMP,

        COREDUMP_CMD_ERASE_STORED_DUMP,

        COREDUMP_CMD_COPY_STORED_DUMP,

        COREDUMP_CMD_INVALIDATE_STORED_DUMP,

        COREDUMP_CMD_MAX
};

struct coredump_cmd_copy_arg {
        off_t offset;

        uint8_t *buffer;

        size_t length;
};
 
#ifdef CONFIG_DEBUG_COREDUMP
 
#include <zephyr/toolchain.h>
#include <zephyr/arch/cpu.h>
#include <zephyr/sys/byteorder.h>
 
#define COREDUMP_HDR_VER                2
 
#define COREDUMP_ARCH_HDR_ID            'A'
 
#define THREADS_META_HDR_ID             'T'
#define THREADS_META_HDR_VER            1
 
#define COREDUMP_MEM_HDR_ID             'M'
#define COREDUMP_MEM_HDR_VER            1
 
#define COREDUMP_CPU_SNAPSHOT_HDR_ID    'F'
#define COREDUMP_CPU_SNAPSHOT_HDR_VER   1
 
/* Target code */
enum coredump_tgt_code {
        COREDUMP_TGT_UNKNOWN = 0,
        COREDUMP_TGT_X86,
        COREDUMP_TGT_X86_64,
        COREDUMP_TGT_ARM_CORTEX_M,
        COREDUMP_TGT_RISC_V,
        COREDUMP_TGT_XTENSA,
        COREDUMP_TGT_ARM64,
};
 
/* Coredump header */
struct coredump_hdr_t {
        /* 'Z', 'E' */
        char            id[2];
 
        /* Header version */
        uint16_t        hdr_version;
 
        /* Target code */
        uint16_t        tgt_code;
 
        /* Pointer size in Log2 */
        uint8_t         ptr_size_bits;
 
        uint8_t         flag;
 
        /* Coredump Reason given */
        unsigned int    reason;
} __packed;
 
/* Architecture-specific block header */
struct coredump_arch_hdr_t {
        /* COREDUMP_ARCH_HDR_ID */
        char            id;
 
        /* Header version */
        uint16_t        hdr_version;
 
        /* Number of bytes in this block (excluding header) */
        uint16_t        num_bytes;
} __packed;
 
/* Threads metadata header */
struct coredump_threads_meta_hdr_t {
        /* THREADS_META_HDR_ID */
        char            id;
 
        /* Header version */
        uint16_t        hdr_version;
 
        /* Number of bytes in this block (excluding header) */
        uint16_t        num_bytes;
} __packed;
 
/* Memory block header */
struct coredump_mem_hdr_t {
        /* COREDUMP_MEM_HDR_ID */
        char            id;
 
        /* Header version */
        uint16_t        hdr_version;
 
        /* Address of start of memory region */
        uintptr_t       start;
 
        /* Address of end of memory region */
        uintptr_t       end;
} __packed;
 
/*
 * Live per-CPU register snapshot header (CONFIG_DEBUG_COREDUMP_SMP_FREEZE_CPUS).
 *
 * One of these precedes each frozen CPU's register block (same arch-specific
 * payload layout as the COREDUMP_ARCH_HDR_ID block for the panicking thread,
 * e.g. arm64_arch_block on ARM64), letting tooling show a correct backtrace
 * for a thread that was actively running on another CPU at panic time,
 * instead of falling back to its stale last-swapped-out saved context.
 */
struct coredump_cpu_snapshot_hdr_t {
        /* COREDUMP_CPU_SNAPSHOT_HDR_ID */
        char            id;
 
        /* Header version */
        uint16_t        hdr_version;
 
        /* Number of bytes in the arch-specific payload that follows */
        uint16_t        num_bytes;
 
        /* CPU index (0..CONFIG_MP_MAX_NUM_CPUS-1) this snapshot came from */
        uint32_t        cpu_id;
 
        /* The k_thread that was .current on that CPU when it was frozen */
        uintptr_t       thread_ptr;
} __packed;
 
typedef void (*coredump_backend_start_t)(void);
typedef void (*coredump_backend_end_t)(void);
typedef void (*coredump_backend_buffer_output_t)(uint8_t *buf, size_t buflen);
typedef int (*coredump_backend_query_t)(enum coredump_query_id query_id,
                                        void *arg);
typedef int (*coredump_backend_cmd_t)(enum coredump_cmd_id cmd_id,
                                      void *arg);
 
struct coredump_backend_api {
        /* Signal to backend of the start of coredump. */
        coredump_backend_start_t                start;
 
        /* Signal to backend of the end of coredump. */
        coredump_backend_end_t                  end;
 
        /* Raw buffer output */
        coredump_backend_buffer_output_t        buffer_output;
 
        /* Perform query on backend */
        coredump_backend_query_t                query;
 
        /* Perform command on backend */
        coredump_backend_cmd_t                  cmd;
};
 
void coredump(unsigned int reason, const struct arch_esf *esf,
              struct k_thread *thread);
void coredump_memory_dump(uintptr_t start_addr, uintptr_t end_addr);
void coredump_buffer_output(uint8_t *buf, size_t buflen);
 
int coredump_query(enum coredump_query_id query_id, void *arg);
int coredump_cmd(enum coredump_cmd_id cmd_id, void *arg);
 
#else
 
static inline void coredump(unsigned int reason, const struct arch_esf *esf,
                            struct k_thread *thread)
{
        ARG_UNUSED(reason);
        ARG_UNUSED(esf);
        ARG_UNUSED(thread);
}
 
static inline void coredump_memory_dump(uintptr_t start_addr, uintptr_t end_addr)
{
        ARG_UNUSED(start_addr);
        ARG_UNUSED(end_addr);
}
 
static inline void coredump_buffer_output(uint8_t *buf, size_t buflen)
{
        ARG_UNUSED(buf);
        ARG_UNUSED(buflen);
}
 
static inline int coredump_query(enum coredump_query_id query_id, void *arg)
{
        ARG_UNUSED(query_id);
        ARG_UNUSED(arg);
        return -ENOTSUP;
}
 
static inline int coredump_cmd(enum coredump_cmd_id query_id, void *arg)
{
        ARG_UNUSED(query_id);
        ARG_UNUSED(arg);
        return -ENOTSUP;
}
 
#endif /* CONFIG_DEBUG_COREDUMP */






 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_DEBUG_COREDUMP_H_ */