types.hpp

Go to the documentation of this file.

/**
 * @file types.hpp
 * @brief Interrupt system types: execution levels and trigger kinds
 * @ingroup hal
 *
 * One execution-level scheme for the whole library. Every platform's vector
 * table maps onto these names (see `<mcu>/driver/priorities.hpp` in
 * sbl-hardware); application code never writes a numeric priority.
 *
 * Numbers are ARM NVIC levels: lower is more urgent. The STM32H750
 * implements four priority bits, so the encoded byte is `level << 4` and
 * the sixteen levels below are the whole space. Rationale per row:
 * docs/research/interrupt-priority-and-real-time-scheduling.md §4.3.
 */
 
#ifndef SBL_HW_HAL_INTERRUPTS_TYPES_HPP_
#define SBL_HW_HAL_INTERRUPTS_TYPES_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace hal {
namespace interrupts {
 
/**
 * @brief Execution levels, most urgent first.
 *
 * The invariants the scheme guarantees:
 * - Level 0 stays empty, so nothing can ever tie with audio and nothing
 *   escapes BASEPRI.
 * - Audio has its own level. Any handler that shares it would delay audio
 *   by its full length (equal priority cannot preempt).
 * - ControlTick is the BASEPRI ceiling: a ScopedControlCritical masks this
 *   level and everything below it, and nothing above it may touch state
 *   that main or the tick protect. Audio's blocking term is therefore zero.
 * - SysTick, PendSV and SVCall are assigned explicitly; unassigned system
 *   handlers reset to level 0, above audio.
 */
enum class Level : uint8_t {
    Reserved      = 0,   ///< Empty by design (unmaskable by BASEPRI)
    ShortDeadline = 1,   ///< Reserved for microsecond handlers that touch only SPSC queues
    Audio         = 2,   ///< Audio DMA half/complete — the SAI streams only
    UsbMidi       = 4,   ///< USB OTG interrupt, MIDI UART RX (both FIFO-elastic)
    Dma           = 5,   ///< Every other DMA stream (ADC, SDMMC)
    Bus           = 6,   ///< I2C / SPI event handlers, if interrupt-driven
    ControlTick   = 8,   ///< Control-rate timer tick — the BASEPRI ceiling
    SoftPwm       = 9,   ///< Software PWM / BCM timer (tolerates tick preemption)
    Exti          = 10,  ///< External pin interrupts (encoders, buttons)
    SoftPend      = 11,  ///< Software-pended work: tud_task(), USB-MIDI parse
    Debug         = 12,  ///< Debug UART, diagnostics drain
    SysTick       = 14,  ///< Millisecond tick; busy_wait_ms works from any level below
    PendSv        = 15,  ///< PendSV and SVCall (left free for an RTOS later)
};
 
/// The level a ScopedControlCritical raises BASEPRI to.
inline constexpr Level kBasepriCeiling = Level::ControlTick;
 
/// Priority bits the target implements (STM32H750: 4 of 8).
inline constexpr uint8_t kPriorityBits = 4;
 
/// Encode a level as the byte written to NVIC->IP[] / SCB->SHP[] / BASEPRI.
constexpr uint8_t encode(Level level) {
    return static_cast<uint8_t>(static_cast<uint8_t>(level) << (8u - kPriorityBits));
}
 
/// True if a handler at `level` is masked while BASEPRI sits at the ceiling.
constexpr bool masked_by_ceiling(Level level) {
    return static_cast<uint8_t>(level) >= static_cast<uint8_t>(kBasepriCeiling);
}
 
/**
 * @brief External interrupt trigger types
 */
enum class Trigger : uint8_t {
    Rising,         ///< Rising edge trigger
    Falling,        ///< Falling edge trigger
    Change,         ///< Any edge (rising or falling)
    Low,            ///< Low level trigger
    High            ///< High level trigger
};
 
} // namespace interrupts
} // namespace hal
} // namespace sbl
 
#endif // SBL_HW_HAL_INTERRUPTS_TYPES_HPP_