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 <zephyr/arch/cpu.h> 15 #include <zephyr/toolchain.h> 16 #include <zephyr/fatal_types.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * @defgroup fatal_apis Fatal error APIs 24 * @ingroup kernel_apis 25 * @{ 26 */ 27 28 /** 29 * @brief Halt the system on a fatal error 30 * 31 * Invokes architecture-specific code to power off or halt the system in 32 * a low power state. Lacking that, lock interrupts and sit in an idle loop. 33 * 34 * @param reason Fatal exception reason code 35 */ 36 FUNC_NORETURN void k_fatal_halt(unsigned int reason); 37 38 /** 39 * @brief Fatal error policy handler 40 * 41 * This function is not invoked by application code, but is declared as a 42 * weak symbol so that applications may introduce their own policy. 43 * 44 * The default implementation of this function halts the system 45 * unconditionally. Depending on architecture support, this may be 46 * a simple infinite loop, power off the hardware, or exit an emulator. 47 * 48 * If this function returns, then the currently executing thread will be 49 * aborted. 50 * 51 * A few notes for custom implementations: 52 * 53 * - If the error is determined to be unrecoverable, LOG_PANIC() should be 54 * invoked to flush any pending logging buffers. 55 * - K_ERR_KERNEL_PANIC indicates a severe unrecoverable error in the kernel 56 * itself, and should not be considered recoverable. There is an assertion 57 * in z_fatal_error() to enforce this. 58 * - Even outside of a kernel panic, unless the fault occurred in user mode, 59 * the kernel itself may be in an inconsistent state, with API calls to 60 * kernel objects possibly exhibiting undefined behavior or triggering 61 * another exception. 62 * 63 * @param reason The reason for the fatal error 64 * @param esf Exception context, with details and partial or full register 65 * state when the error occurred. May in some cases be NULL. 66 */ 67 void k_sys_fatal_error_handler(unsigned int reason, const z_arch_esf_t *esf); 68 69 /** 70 * Called by architecture code upon a fatal error. 71 * 72 * This function dumps out architecture-agnostic information about the error 73 * and then makes a policy decision on what to do by invoking 74 * k_sys_fatal_error_handler(). 75 * 76 * On architectures where k_thread_abort() never returns, this function 77 * never returns either. 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 z_fatal_error(unsigned int reason, const z_arch_esf_t *esf); 84 85 /** @} */ 86 87 #ifdef __cplusplus 88 } 89 #endif 90 91 #endif /* ZEPHYR_INCLUDE_FATAL_H */ 92
