1 /* 2 * Copyright (c) 2019 Intel Corporation. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** @file 8 * @brief Fatal error functions 9 */ 10 11 #ifndef ZEPHYR_INCLUDE_FATAL_H 12 #define ZEPHYR_INCLUDE_FATAL_H 13 14 #include <arch/cpu.h> 15 #include <toolchain.h> 16 17 /** 18 * @defgroup fatal_apis Fatal error APIs 19 * @ingroup kernel_apis 20 * @{ 21 */ 22 23 enum k_fatal_error_reason { 24 /** Generic CPU exception, not covered by other codes */ 25 K_ERR_CPU_EXCEPTION, 26 27 /** Unhandled hardware interrupt */ 28 K_ERR_SPURIOUS_IRQ, 29 30 /** Faulting context overflowed its stack buffer */ 31 K_ERR_STACK_CHK_FAIL, 32 33 /** Moderate severity software error */ 34 K_ERR_KERNEL_OOPS, 35 36 /** High severity software error */ 37 K_ERR_KERNEL_PANIC 38 39 /* TODO: add more codes for exception types that are common across 40 * architectures 41 */ 42 }; 43 44 /** 45 * @brief Halt the system on a fatal error 46 * 47 * Invokes architecture-specific code to power off or halt the system in 48 * a low power state. Lacking that, lock interrupts and sit in an idle loop. 49 * 50 * @param reason Fatal exception reason code 51 */ 52 FUNC_NORETURN void k_fatal_halt(unsigned int reason); 53 54 /** 55 * @brief Fatal error policy handler 56 * 57 * This function is not invoked by application code, but is declared as a 58 * weak symbol so that applications may introduce their own policy. 59 * 60 * The default implementation of this function halts the system 61 * unconditionally. Depending on architecture support, this may be 62 * a simple infinite loop, power off the hardware, or exit an emulator. 63 * 64 * If this function returns, then the currently executing thread will be 65 * aborted. 66 * 67 * A few notes for custom implementations: 68 * 69 * - If the error is determined to be unrecoverable, LOG_PANIC() should be 70 * invoked to flush any pending logging buffers. 71 * - K_ERR_KERNEL_PANIC indicates a severe unrecoverable error in the kernel 72 * itself, and should not be considered recoverable. There is an assertion 73 * in z_fatal_error() to enforce this. 74 * - Even outside of a kernel panic, unless the fault occurred in user mode, 75 * the kernel itself may be in an inconsistent state, with API calls to 76 * kernel objects possibly exhibiting undefined behavior or triggering 77 * another exception. 78 * 79 * @param reason The reason for the fatal error 80 * @param esf Exception context, with details and partial or full register 81 * state when the error occurred. May in some cases be NULL. 82 */ 83 void k_sys_fatal_error_handler(unsigned int reason, const z_arch_esf_t *esf); 84 85 /** 86 * Called by architecture code upon a fatal error. 87 * 88 * This function dumps out architecture-agnostic information about the error 89 * and then makes a policy decision on what to do by invoking 90 * k_sys_fatal_error_handler(). 91 * 92 * On architectures where k_thread_abort() never returns, this function 93 * never returns either. 94 * 95 * @param reason The reason for the fatal error 96 * @param esf Exception context, with details and partial or full register 97 * state when the error occurred. May in some cases be NULL. 98 */ 99 void z_fatal_error(unsigned int reason, const z_arch_esf_t *esf); 100 101 /** @} */ 102 103 #endif /* ZEPHYR_INCLUDE_FATAL_H */ 104
