assert.hpp

Go to the documentation of this file.

#ifndef SBL_COMMON_ASSERT_HPP_
#define SBL_COMMON_ASSERT_HPP_
 
/**
 * @file assert.hpp
 * @brief Assert and panic for embedded firmware
 *
 * Provides SBL_ASSERT(cond) and SBL_PANIC(msg) macros that output
 * diagnostic info and halt the processor. Output goes through the
 * same sink as the logging system (SBL_LOG_OUTPUT).
 *
 * This header is pure library code — no hardware dependencies.
 * For HardFault register dumps, also include <sbl/common/fault.hpp>.
 *
 * Usage:
 *   #include <sbl/common/assert.hpp>
 *
 *   void process(float* buf, uint16_t frames) {
 *       SBL_ASSERT(buf != nullptr);
 *       SBL_ASSERT(frames <= 48);
 *       // ...
 *   }
 *
 *   if (something_unrecoverable) {
 *       SBL_PANIC("DMA config failed");
 *   }
 *
 * Configuration:
 *   SBL_ASSERT_ENABLED  - 1 (default) to enable, 0 to compile out
 *   SBL_FAULT_OUTPUT    - output sink class (defaults to SBL_LOG_OUTPUT)
 */
 
#include <cstdint>
#include <sbl/common/log/format.hpp>
 
// ============================================================================
// Output sink resolution
// ============================================================================
 
// If the user defined a dedicated fault output, use it.
// Otherwise, use polling UART (works with interrupts disabled).
// NOTE: Fault handlers run after cpsid i — interrupt-driven output
// (ring buffer + ISR) will never drain. Must use polling writes.
#ifndef SBL_FAULT_OUTPUT
    #include <sbl/common/log/defaults.hpp>
 
    #if SBL_LOG_HW_DEFAULTS_AVAILABLE
        #define SBL_FAULT_OUTPUT sbl::log::UartFaultOutput
    #else
        // No output available — fault still halts, just silently.
        namespace sbl::fault::detail {
            struct NullFaultOutput {
                static void write(const char*) {}
            };
        }
        #define SBL_FAULT_OUTPUT sbl::fault::detail::NullFaultOutput
    #endif
#endif
 
namespace sbl::fault {
 
/**
 * @brief Halt with a diagnostic message. Does not return.
 *
 * Disables interrupts, formats the message with file/line info,
 * outputs it, then enters an infinite loop with a debug breakpoint.
 *
 * Safe to call from any context (main loop, ISR, fault handler).
 */
[[noreturn]] inline void panic(const char* msg, const char* file, int line) {
    __asm volatile("cpsid i");  // __disable_irq()
 
    char buf[128];
    sbl::log::format(buf, sizeof(buf), "\r\n!!! %s\r\n    at %s:%d\r\n", msg, file, line);
    SBL_FAULT_OUTPUT::write(buf);
 
    while (true) {
        __asm volatile("bkpt #0");
    }
}
 
} // namespace sbl::fault
 
// ============================================================================
// Macros
// ============================================================================
 
#define SBL_PANIC(msg) sbl::fault::panic("PANIC: " msg, __FILE__, __LINE__)
 
#ifndef SBL_ASSERT_ENABLED
    #define SBL_ASSERT_ENABLED 1
#endif
 
#if SBL_ASSERT_ENABLED
    #define SBL_ASSERT(cond) \
        do { \
            if (!(cond)) { \
                sbl::fault::panic("ASSERT FAILED: " #cond, __FILE__, __LINE__); \
            } \
        } while (0)
#else
    #define SBL_ASSERT(cond) ((void)0)
#endif
 
#endif // SBL_COMMON_ASSERT_HPP_