Crash Engine

include/console/crash.h View source View on GitHub

Structs

crash_regs

struct crash_regs (1 field)

§ union

§ struct

§ uint64_t rip

§ uint64_t rax

§ uint64_t r8

§ uint64_t rsp

§ uint64_t regs[CRASH_REG_COUNT]

crash_code

struct crash_code (3 fields)

NULL crashes are the generic, code-less crash

§ const char *name

§ const char *desc

§ const struct crash_facility *facility

crash_payload

struct crash_payload (3 fields)

§ const struct crash_code *code

§ void *data

§ uintptr_t params[4]

crash_facility

struct crash_facility (5 fields)

§ const char *name

§ const char *desc

§ const struct crash_code *const *codes

list order

§ size_t nr_codes

§ void (*const dump)(struct crash_payload pl)

crash_unwind_node_data

struct crash_unwind_node_data (2 fields)

§ uintptr_t arg

§ union

§ void *ptr

§ size_t rcu_lock_times

§ enum irql irql

§ uintptr_t raw

crash_unwind_node

struct crash_unwind_node (3 fields)

§ enum crash_unwind_type type

§ struct list_node list

§ struct crash_unwind_node_data data

crash_unwind_thread_data

struct crash_unwind_thread_data (3 fields)

§ struct list_head free_list

§ struct list_head in_use

LIFO

§ struct crash_unwind_node nodes[CRASH_UNWIND_NODES]

crash_thread_data

struct crash_thread_data (5 fields)

§ struct crash_unwind_thread_data unwind

§ struct list_head crash_hooks

struct crash_hook

§ bool unwinding

§ bool in_hook

§ jmp_buf env

crash_hook

struct crash_hook (4 fields)

The idea of crash hooks:

A hook can hook into a specific code, which is checked against a facility to verify if it is hookable.

They are hooked PER-THREAD, so as to not introduce strange non-determinism bugs and the chance that the crash hook registration path itself can crash (would be problematic) due to synchronization violations.

The generic (NULL) code is not hookable

§ char *name

§ struct list_node list

§ const struct crash_code *code

§ enum crash_source source_mask

crash_context

struct crash_context (10 fields)

§ struct crash_payload payload

§ enum crash_source source

§ enum crash_format_flags formats

§ const char *stmt

§ const char *file

§ int line

§ const char *func

§ const char *msg

§ const struct crash_regs *regs

NULL = capture caller’s frame via asm

§ void *source_data

Enums

qemu_exit_codes

enum qemu_exit_codes (3 variants)

§ QEMU_EXIT_OK = 0

§ QEMU_EXIT_FAIL = 1

§ QEMU_EXIT_PANIC = 2

crash_source

enum crash_source (8 variants)

§ CRASH_SOURCE_PANIC = 0

panic() call

§ CRASH_SOURCE_ENFORCE

enforce() failure

§ CRASH_SOURCE_KASAN

ASAN check failure

§ CRASH_SOURCE_UBSAN

UBSAN failure

§ CRASH_SOURCE_NMI_WATCHDOG

Watchdog / Liveness monitor hard stall

§ CRASH_SOURCE_CPU_EXCEPTION

Hardware CPU fault

§ CRASH_SOURCE_NIGHTMARE

Nightmare test harness failure

§ CRASH_SOURCE_LOCK_CHK

Lock validator order / dependency violation

crash_format_flags

enum crash_format_flags (7 variants)

§ CRASH_FMT_RAW_SERIAL = 1 << 0

Minimal serial printf

§ CRASH_FMT_VISUAL_PANES = 1 << 1

Dual pane ANSI console report

§ CRASH_FMT_NDJSON = 1 << 2

NDJSON stream

§ CRASH_FMT_DUMP_LOGS = 1 << 3

circular log buffer dump

§ CRASH_FMT_PEER_CPUS = 1 << 4

Quiesce and render peer CPU frames

CRASH_FMT_DEFAULT = CRASH_FMT_RAW_SERIAL | CRASH_FMT_VISUAL_PANES | CRASH_FMT_NDJSON | CRASH_FMT_DUMP_LOGS | CRASH_FMT_PEER_CPUS

Default formatting

§ CRASH_FMT_MINIMAL = CRASH_FMT_RAW_SERIAL | CRASH_FMT_NDJSON

Minimal formatting for early boot or nested crashes

crash_hook_flags

enum crash_hook_flags (3 variants)

§ CRASH_HOOK_DEFAULT = 0

§ CRASH_HOOK_FACILITY = 1 << 0

Facility granularity: match any code whose ->facility is the code’s facility

§ CRASH_HOOK_NO_UNWIND = 1 << 1

By default, the crash handler will make a best-effort attempt to unwind: it’ll try to safely drop locks, exit RCU read-side critical sections, although memory may still leak (this is dependent on the facility implementation).

NO_UNWIND allows this behavior to be skipped. This is because in certain cases, the unwinding cannot happen (e.g. lock checking is disabled), and also because the stale state not unwinding leaves can be used as a postmortem for state verification.

crash_unwind_type

enum crash_unwind_type (7 variants)

§ CRASH_UNWIND_NONE

should not be reachable

§ CRASH_UNWIND_RCU

§ CRASH_UNWIND_MUTEX

§ CRASH_UNWIND_RWLOCK

§ CRASH_UNWIND_SPINLOCK

§ CRASH_UNWIND_QSPINLOCK

§ CRASH_UNWIND_MAX

Functions

enforce_impl_code_only

void enforce_impl_precond_msg(const char *file, int line, const char *func, const char *prefix, const char *expr, const char *fmt, ...) cc_printf_like(6, 7); cc_noreturn void enforce_impl_code(const char *file, int line, const char *func, const char *prefix, const char *expr, const struct crash_code *code, const char *fmt, ...) cc_printf_like(7, 8); cc_noreturn void enforce_impl_code_only(
    const char *file,
    int line,
    const char *func,
    const char *prefix,
    const char *expr,
    const struct crash_code *code
)

enforce_impl_msg() with INVALID_ARGUMENT for enforce_precond()

crash_full

cc_noreturn void crash_full(const struct crash_context *ctx)

crash_cpu_is_owner

bool crash_cpu_is_owner(uint64_t id)

crash_broadcast_nmi

void crash_broadcast_nmi(void)

crash_code_name

size_t crash_code_name(
    const struct crash_code *code,
    char *buf,
    size_t len
)

crash_nmi_handoff

void crash_nmi_handoff(void *p, struct irq_registers *irqc)

debug_print_stack

void debug_print_stack(void)

crash_code_in_facility

bool crash_code_in_facility(
    const struct crash_code *code,
    const struct crash_facility *f
)

crash_thread_init

void crash_thread_init(struct thread *t)

crash_unwind

void crash_unwind(void)

Enter/exit pairs

crash_unwind_enter_rcu

void crash_unwind_enter_rcu(void)

crash_unwind_exit_rcu

void crash_unwind_exit_rcu(void)

crash_unwind_enter_mutex

void crash_unwind_enter_mutex(struct mutex *m)

crash_unwind_exit_mutex

void crash_unwind_exit_mutex(struct mutex *m)

crash_unwind_enter_rwlock

void crash_unwind_enter_rwlock(struct rwlock *r)

crash_unwind_exit_rwlock

void crash_unwind_exit_rwlock(struct rwlock *r)

crash_unwind_enter_spinlock

void crash_unwind_enter_spinlock(struct spinlock *s, enum irql old)

crash_unwind_exit_spinlock

void crash_unwind_exit_spinlock(struct spinlock *s)

crash_unwind_enter_qspinlock

void crash_unwind_enter_qspinlock(struct qspinlock *q, enum irql old)

crash_unwind_exit_qspinlock

void crash_unwind_exit_qspinlock(struct qspinlock *q)

crash_thread_init

void crash_thread_init(struct thread *t)

crash_unwind

void crash_unwind(void)

crash_unwind_enter_rcu

void crash_unwind_enter_rcu(void)

crash_unwind_exit_rcu

void crash_unwind_exit_rcu(void)

crash_unwind_enter_mutex

void crash_unwind_enter_mutex(struct mutex *m)

crash_unwind_exit_mutex

void crash_unwind_exit_mutex(struct mutex *m)

crash_unwind_enter_rwlock

void crash_unwind_enter_rwlock(struct rwlock *r)

crash_unwind_exit_rwlock

void crash_unwind_exit_rwlock(struct rwlock *r)

crash_unwind_enter_spinlock

void crash_unwind_enter_spinlock(struct spinlock *s, enum irql old)

crash_unwind_exit_spinlock

void crash_unwind_exit_spinlock(struct spinlock *s)

crash_unwind_enter_qspinlock

void crash_unwind_enter_qspinlock(struct qspinlock *q, enum irql old)

crash_unwind_exit_qspinlock

void crash_unwind_exit_qspinlock(struct qspinlock *q)

qemu_exit

void qemu_exit(int code)

Variables

cc_noreturn

cc_noreturn void enforce_impl_msg(const char *file, int line, const char *func, const char *prefix, const char *expr, const char *fmt, ...) cc_printf_like(6, 7); /* enforce_impl_msg() with INVALID_ARGUMENT for enforce_precond() */ cc_noreturn

Macros

CRASH_REG_COUNT

#define CRASH_REG_COUNT 20

CRASH_CODES_global

#define CRASH_CODES_global

Codes that don’t have a facility, like enforce(p, INVALID_ARGUMENT)

Expansion

#define CRASH_CODES_global \
    (INVALID_ARGUMENT, "Argument was NULL or out of range"), \
        (INVALID_STATE, "Object was in a state this operation forbids"), \
        (INVALID_CONTEXT, \
         "Operation ran at a forbidden IRQL, IRQ or boot stage"), \
        (OUT_OF_MEMORY, "Allocation that must not fail did fail"), \
        (UNSUPPORTED, "Hardware or firmware lacks a required feature"), \
        (CORRUPTION, "Data structure or allocator invariant was broken"), \
        (CAPACITY_EXCEEDED, "A fixed-size limit was exceeded"), \
        (UNREACHABLE, "Control reached a path that must not execute"), \
        (DUPLICATE, "Object was registered, inserted, or defined twice"), \
        (OVERFLOW, "Counter or arithmetic result exceeded its range"), \
        (UNDERFLOW, "Counter was decremented below zero"), \
        (STALE_REFERENCE, "Reference to an object that is dying or dead"), \
        (BAD_FREE, "Freed memory was already free or never allocated"), \
        (UNINITIALIZED, "Object was used before initialization"), \
        (INIT_FAILED, "A required initialization step failed"), \
        (NOT_FOUND, "Lookup that must succeed found nothing")

CRASH_UNWIND_NODES

#define CRASH_UNWIND_NODES 128

CRASH_WAIT_US

#define CRASH_WAIT_US MS_TO_US(500)

Quiesce timeout per peer CPU

CRASH_SPIN_ONE_US

#define CRASH_SPIN_ONE_US 5

CRASH_MAX_DEPTH

#define CRASH_MAX_DEPTH 2

Max recursive fault depth

CRASH_MSG_MAX

#define CRASH_MSG_MAX 256

CRASH_PAYLOAD

#define CRASH_PAYLOAD(c, d)

Expansion

#define CRASH_PAYLOAD(c, d) ((struct crash_payload) {.code = c, .data = d})

CRASH_PARAMS

#define CRASH_PARAMS(c, p0, p1, p2, p3)

Expansion

#define CRASH_PARAMS(c, p0, p1, p2, p3) \
    ((struct crash_payload) {.code = (c), \
                             .params = {(uintptr_t) (p0), (uintptr_t) (p1), \
                                        (uintptr_t) (p2), (uintptr_t) (p3)}})

CRASH_CODE_TO_PAYLOAD

#define CRASH_CODE_TO_PAYLOAD(c)

Expansion

#define CRASH_CODE_TO_PAYLOAD(c) ((struct crash_payload) {.code = c})

CRASH_FACILITY

#define CRASH_FACILITY(f)

Use like this:   #define CRASH_CODES_asan
      (USE_AFTER_FREE, “Use after free”),
      (PARTIAL_GRANULE)

CRASH_CODE(asan, USE_AFTER_FREE)

Expansion

#define CRASH_FACILITY(f) __crash_facility_##f

CRASH_CODE

#define CRASH_CODE(f, n)

Expansion

#define CRASH_CODE(f, n) _crash_code_sym(f, n)

CRASH_CODE_NTH

#define CRASH_CODE_NTH(f, i)

Expansion

#define CRASH_CODE_NTH(f, i) __crash_codes_##f[(i)]

CRASH_CODES_ENUM

#define CRASH_CODES_ENUM(f, prefix)

Expansion

#define CRASH_CODES_ENUM(f, prefix) \
    PP_FOREACH_CTX(_crash_code_enumerator, prefix, CRASH_CODES_##f)

crash_code_in

#define crash_code_in(c, f)

Expansion

#define crash_code_in(c, f) crash_code_in_facility((c), &CRASH_FACILITY(f))

CRASH_CODES_DECLARE

#define CRASH_CODES_DECLARE(f)

Expansion

#define CRASH_CODES_DECLARE(f) \
    extern const struct crash_facility CRASH_FACILITY(f); \
    extern const struct crash_code *const __crash_codes_##f[]; \
    PP_FOREACH_CTX(_crash_code_extern, f, CRASH_CODES_##f)

CRASH_FACILITY_DEFINE

#define CRASH_FACILITY_DEFINE(f, d, ...)

Expansion

#define CRASH_FACILITY_DEFINE(f, d, ...) \
    CRASH_CODES_DECLARE(f); \
    PP_FOREACH_CTX(_crash_code_def, f, CRASH_CODES_##f) \
    const struct crash_code *const __crash_codes_##f[] = { \
        PP_FOREACH_CTX(_crash_code_ptr, f, CRASH_CODES_##f)}; \
    const struct crash_facility CRASH_FACILITY(f) = { \
        .name = #f, \
        .desc = d, \
        .codes = __crash_codes_##f, \
        .nr_codes = ct_array_size(__crash_codes_##f), \
        __VA_ARGS__}

_crash_code_sym

#define _crash_code_sym(f, n)

Expansion

#define _crash_code_sym(f, n) __crash_code_##f##_##n

_crash_code_name

#define _crash_code_name(t)

Expansion

#define _crash_code_name(t) PP_GET_1 t

_crash_code_desc

#define _crash_code_desc(t)

Expansion

#define _crash_code_desc(t) _crash_code_desc_(PP_UNPAREN(t), NULL, ~)

crash_code_desc

#define _crash_code_desc_(...)

Expansion

#define _crash_code_desc_(...) _crash_code_desc_pick(__VA_ARGS__)

_crash_code_desc_pick

#define _crash_code_desc_pick(n, d, ...)

Expansion

#define _crash_code_desc_pick(n, d, ...) d

_crash_code_extern

#define _crash_code_extern(f, t)

Expansion

#define _crash_code_extern(f, t) _crash_code_extern_(f, _crash_code_name(t))

crash_code_extern

#define _crash_code_extern_(f, n)

Expansion

#define _crash_code_extern_(f, n) \
    extern const struct crash_code _crash_code_sym(f, n)[1];

_crash_code_def

#define _crash_code_def(f, t)

Expansion

#define _crash_code_def(f, t) \
    _crash_code_def_(f, _crash_code_name(t), _crash_code_desc(t))

crash_code_def

#define _crash_code_def_(f, n, d)

Expansion

#define _crash_code_def_(f, n, d) \
    const struct crash_code _crash_code_sym(f, n)[1] = { \
        {PP_STRINGIZE(n), d, &CRASH_FACILITY(f)}};

_crash_code_ptr

#define _crash_code_ptr(f, t)

Expansion

#define _crash_code_ptr(f, t) _crash_code_ptr_(f, _crash_code_name(t))

crash_code_ptr

#define _crash_code_ptr_(f, n)

Expansion

#define _crash_code_ptr_(f, n) _crash_code_sym(f, n),

_crash_code_enumerator

#define _crash_code_enumerator(p, t)

Expansion

#define _crash_code_enumerator(p, t) PP_CONCAT(p, _crash_code_name(t)),

CRASH_CODE_ARG

#define CRASH_CODE_ARG(a)

Expansion

#define CRASH_CODE_ARG(a) PP_IIF(PP_IS_PAREN(a))(_crash_tuple_code(a), a)

_crash_tuple_code

#define _crash_tuple_code(t)

Expansion

#define _crash_tuple_code(t) \
    PP_CONCAT(_crash_tuple_code_, _crash_narg(PP_UNPAREN(t))) t

_crash_narg

#define _crash_narg(...)

Expansion

#define _crash_narg(...) PP_NARG(__VA_ARGS__)

_crash_tuple_code_1

#define _crash_tuple_code_1(n)

Expansion

#define _crash_tuple_code_1(n) CRASH_CODE(global, n)

_crash_tuple_code_2

#define _crash_tuple_code_2(f, n)

Expansion

#define _crash_tuple_code_2(f, n) CRASH_CODE(f, n)

CRASH_CODE_SCOPED

#define CRASH_CODE_SCOPED(a, ...)

Wraps stmt in the bare-name scope unless code was a tuple

Expansion

#define CRASH_CODE_SCOPED(a, ...) \
    PP_CONCAT(_crash_code_scoped_, PP_IS_PAREN(a))(__VA_ARGS__)

_crash_code_scoped_1

#define _crash_code_scoped_1(...)

Expansion

#define _crash_code_scoped_1(...) __VA_ARGS__

_crash_code_scoped_0

#define _crash_code_scoped_0(...)

Expansion

#define _crash_code_scoped_0(...) \
    ({ \
        _CRASH_CODE_SCOPE \
        __VA_ARGS__; \
    })

_crash_code_alias

#define _crash_code_alias(f, t)

Expansion

#define _crash_code_alias(f, t) _crash_code_alias_(f, _crash_code_name(t))

crash_code_alias

#define _crash_code_alias_(f, n)

Expansion

#define _crash_code_alias_(f, n) \
    cc_unused extern const struct crash_code n[1] asm(PP_STRINGIZE(__USER_LABEL_PREFIX__) PP_STRINGIZE(_crash_code_sym(f, n)));

_CRASH_CODE_SCOPE

#define _CRASH_CODE_SCOPE

Expansion

#define _CRASH_CODE_SCOPE \
    PP_FOREACH_CTX(_crash_code_alias, global, CRASH_CODES_global)