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