fault.hpp

Go to the documentation of this file.

#pragma once
/**
 * @file fault.hpp
 * @brief HardFault handler with register dump
 *
 * Bridge between the MCU's HardFault vector (in sbl-hardware startup.cpp)
 * and the library's diagnostic output. Including this header provides:
 *
 * 1. sbl::fault::on_hard_fault() — formats the Cortex-M exception frame
 * 2. sbl_on_hard_fault() — strong C symbol that overrides the weak default
 *    in startup.cpp, connecting the vector to the formatter
 *
 * The startup.cpp in sbl-hardware declares a weak sbl_on_hard_fault() that
 * just hits a breakpoint. When this header is included in the application,
 * the strong symbol here wins, giving formatted register output on any fault.
 *
 * Usage:
 *   // Include once in your main.cpp (or any single TU)
 *   #include <sbl/fault.hpp>
 *
 *   // That's it. HardFaults now dump registers to your log output.
 *
 * The output sink is shared with assert.hpp (SBL_FAULT_OUTPUT).
 * See assert.hpp for sink configuration.
 */
 
#include <sbl/assert.hpp>  // For SBL_FAULT_OUTPUT and sbl::log::format
 
namespace sbl::fault {
 
/**
 * @brief Format and output the Cortex-M exception stack frame.
 *
 * The Cortex-M exception entry pushes these registers onto the
 * active stack (MSP or PSP):
 *   [0] R0   [1] R1   [2] R2   [3] R3
 *   [4] R12  [5] LR   [6] PC   [7] xPSR
 *
 * The faulting instruction address is frame[6] (stacked PC).
 * frame[5] (stacked LR) shows where the faulting function would
 * have returned to.
 *
 * @param frame Pointer to the exception stack frame
 */
[[noreturn]] inline void on_hard_fault(const uint32_t* frame) {
    __asm volatile("cpsid i");
 
    char buf[256];
    int pos = 0;
 
    pos += sbl::log::format(buf + pos, sizeof(buf) - pos,
        "\r\n!!! HARD FAULT\r\n"
        "    PC  = 0x%08lX  (faulting instruction)\r\n"
        "    LR  = 0x%08lX  (return address)\r\n"
        "    PSR = 0x%08lX\r\n",
        frame[6], frame[5], frame[7]);
 
    pos += sbl::log::format(buf + pos, sizeof(buf) - pos,
        "    R0  = 0x%08lX  R1  = 0x%08lX\r\n"
        "    R2  = 0x%08lX  R3  = 0x%08lX\r\n"
        "    R12 = 0x%08lX\r\n",
        frame[0], frame[1], frame[2], frame[3], frame[4]);
 
    SBL_FAULT_OUTPUT::write(buf);
 
    while (true) {
        __asm volatile("bkpt #1");
    }
}
 
} // namespace sbl::fault
 
// ============================================================================
// HardFault handler override
// ============================================================================
// This strong symbol overrides the weak default in startup.cpp,
// connecting the MCU's HardFault vector to the formatted output above.
//
// __attribute__((used)) forces the compiler to emit the symbol even
// though nothing in C++ calls it directly — the call comes from the
// HardFault assembly stub in startup.cpp via the vector table.
 
extern "C" [[noreturn]] __attribute__((used))
inline void sbl_on_hard_fault(const uint32_t* frame) {
    sbl::fault::on_hard_fault(frame);
}