control.hpp

Go to the documentation of this file.

/**
 * @file control.hpp
 * @brief ARM Cortex-M interrupt masking primitives
 * @ingroup hal
 *
 * Two masks, two jobs:
 *
 * - BASEPRI raises the execution priority to a ceiling. Handlers above the
 *   ceiling keep running — the audio ISR is never delayed by a critical
 *   section anywhere in main or control code. ScopedControlCritical is the
 *   default critical section.
 * - PRIMASK stops every configurable exception, audio included. It is for
 *   death paths (assert, fault) and nothing else.
 *
 * The rule (research doc §4.3 item 10): nothing above the ceiling touches
 * state that main or the control tick protect; nothing at or below it uses
 * PRIMASK. Cortex-M7 r1p1 (the STM32H750) does not carry the r0p1 BASEPRI
 * erratum 837070, so a plain MSR is correct.
 *
 * On targets without BASEPRI (ARMv6-M) or on the host, the BASEPRI
 * primitives are no-ops: the workbench has no interrupts to mask, and the
 * bridge invariants are enforced by construction there (single control
 * context, see FDP-073).
 */
 
#ifndef SBL_HW_HAL_INTERRUPTS_CONTROL_HPP_
#define SBL_HW_HAL_INTERRUPTS_CONTROL_HPP_
 
#include <cstdint>
#include <sbl/hw/hal/interrupts/types.hpp>
 
#if defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_8M_MAIN__)
#define SBL_HAS_BASEPRI 1
#endif
#if defined(__arm__) && !defined(__linux__)
#define SBL_HAS_PRIMASK 1
#endif
 
namespace sbl {
namespace hal {
namespace interrupts {
 
// ---------------------------------------------------------------------------
// BASEPRI — the critical section that never blocks audio
// ---------------------------------------------------------------------------
 
/// Read BASEPRI (0 = no ceiling).
inline uint32_t get_basepri() {
#if defined(SBL_HAS_BASEPRI)
    uint32_t v;
    __asm volatile("mrs %0, basepri" : "=r"(v));
    return v;
#else
    return 0;
#endif
}
 
/// Write BASEPRI unconditionally (used to restore a saved value).
inline void set_basepri(uint32_t encoded) {
#if defined(SBL_HAS_BASEPRI)
    __asm volatile("msr basepri, %0" : : "r"(encoded) : "memory");
#else
    (void)encoded;
#endif
}
 
/// Raise BASEPRI to `encoded` only if that is a higher priority than the
/// current value — never lowers it, so nested sections compose.
inline void raise_basepri(uint32_t encoded) {
#if defined(SBL_HAS_BASEPRI)
    __asm volatile("msr basepri_max, %0" : : "r"(encoded) : "memory");
#else
    (void)encoded;
#endif
}
 
/**
 * @brief RAII critical section against the control tick and everything below.
 *
 * Raises BASEPRI to `kBasepriCeiling` (Level::ControlTick) for its scope and
 * restores the previous value on exit. Safe to nest. Handlers above the
 * ceiling — audio, USB/MIDI, other DMA — are unaffected by construction.
 *
 * Use it around any multi-word state shared between main and the control
 * tick. Do not use it from a handler above the ceiling (that handler must
 * not touch such state at all), and do not reach for PRIMASK instead.
 */
class ScopedControlCritical {
public:
    ScopedControlCritical() : saved_(get_basepri()) {
        raise_basepri(encode(kBasepriCeiling));
    }
    ~ScopedControlCritical() { set_basepri(saved_); }
    ScopedControlCritical(const ScopedControlCritical&) = delete;
    ScopedControlCritical& operator=(const ScopedControlCritical&) = delete;
 
private:
    uint32_t saved_;
};
 
// ---------------------------------------------------------------------------
// PRIMASK — everything off. Death paths only.
// ---------------------------------------------------------------------------
 
/**
 * @brief Disable all configurable exceptions and return the previous PRIMASK.
 *
 * This blocks the audio ISR. It exists for assert/fault handling, where the
 * system is already lost; a critical section wants ScopedControlCritical.
 */
inline uint32_t disable_and_save() {
#if defined(SBL_HAS_PRIMASK)
    uint32_t saved;
    __asm volatile("mrs %0, primask" : "=r"(saved));
    __asm volatile("cpsid i" : : : "memory");
    return saved;
#else
    return 0;
#endif
}
 
/// Restore PRIMASK from disable_and_save().
inline void restore(uint32_t saved_state) {
#if defined(SBL_HAS_PRIMASK)
    __asm volatile("msr primask, %0" : : "r"(saved_state) : "memory");
#else
    (void)saved_state;
#endif
}
 
/// Current PRIMASK (0 = enabled, 1 = disabled).
inline uint32_t get_state() {
#if defined(SBL_HAS_PRIMASK)
    uint32_t v;
    __asm volatile("mrs %0, primask" : "=r"(v));
    return v;
#else
    return 0;
#endif
}
 
/// True if configurable exceptions are enabled (PRIMASK clear).
inline bool are_enabled() { return get_state() == 0; }
 
} // namespace interrupts
} // namespace hal
} // namespace sbl
 
#endif // SBL_HW_HAL_INTERRUPTS_CONTROL_HPP_