critical_section.hpp

Go to the documentation of this file.

#ifndef SBL_PATTERNS_SYNCHRONIZATION_CRITICAL_SECTION_HPP_
#define SBL_PATTERNS_SYNCHRONIZATION_CRITICAL_SECTION_HPP_
 
/**
 * @file critical_section.hpp
 * @brief ARM Cortex-M RAII critical section for interrupt disable/restore
 * @ingroup patterns
 * 
 * Provides automatic ARM interrupt disable/restore using HAL interrupt primitives.
 * RAII wrapper that ensures interrupt state is always restored properly.
 */
 
#include <sbl/hal/interrupts/control.hpp>
 
namespace sbl {
namespace patterns {
namespace synchronization {
 
/**
 * @brief ARM Cortex-M RAII critical section using PRIMASK
 * 
 * Disables all interrupts (except NMI/Hard Fault) using ARM PRIMASK register.
 * Automatically restores interrupt state when object goes out of scope.
 * Compiles to minimal ARM Thumb-2 instructions using CMSIS intrinsics.
 * 
 * Usage:
 * @code
 * volatile uint32_t shared_counter = 0;
 * 
 * void increment_from_main() {
 *     CriticalSection cs;
 *     shared_counter++;  // Safe from interrupt interference
 * } // Interrupts automatically restored here
 * @endcode
 * 
 * Design principles:
 * - Optimized abstraction - compiles to 2 ARM instructions
 * - ARM Cortex-M native - uses PRIMASK register directly
 * - Exception-safe - interrupts restored even if exceptions thrown
 * - Efficient - only saves/restores actual PRIMASK state
 *
 * @note ISR-safe — compiles to 2 ARM instructions (MRS/MSR PRIMASK).
 */
class CriticalSection {
public:
    /**
     * @brief Construct critical section and disable ARM interrupts
     * 
     * Saves current PRIMASK state and disables all interrupts except
     * NMI and Hard Fault. Uses HAL interrupt primitives.
     */
    CriticalSection() : saved_primask_(sbl::hal::interrupts::disable_and_save()) {
    }
    
    /**
     * @brief Destructor - restore ARM PRIMASK state
     * 
     * Restores PRIMASK to state before critical section was entered.
     * Guarantees proper interrupt restoration even in error conditions.
     */
    ~CriticalSection() {
        sbl::hal::interrupts::restore(saved_primask_);
    }
    
    // Non-copyable to prevent accidental duplication
    CriticalSection(const CriticalSection&) = delete;
    CriticalSection& operator=(const CriticalSection&) = delete;
    
    // Non-movable to maintain RAII semantics  
    CriticalSection(CriticalSection&&) = delete;
    CriticalSection& operator=(CriticalSection&&) = delete;
    
private:
    const uint32_t saved_primask_;
};
 
/**
 * @brief Convenience macro for ARM critical sections
 * 
 * Creates an ARM critical section with automatic variable naming.
 * Simplified for ARM-only usage without controller parameter.
 * 
 * Usage:
 * @code
 * CRITICAL_SECTION {
 *     // Protected code here - ARM interrupts disabled
 *     shared_data++;
 * } // Automatically restored
 * @endcode
 */
#define CRITICAL_SECTION \
    if (auto cs = sbl::patterns::synchronization::CriticalSection(); true)
 
} // namespace synchronization
} // namespace patterns
} // namespace sbl
 
#endif // SBL_PATTERNS_SYNCHRONIZATION_CRITICAL_SECTION_HPP_