Line data    Source code

       1            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            1 : 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            1 : 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 */