stk::hw::CriticalSection Class Reference

Nestable, SMP-safe critical section that combines local interrupt masking with a global cross-core spinlock. More...

#include <stk_arch.h>

Classes
class	ScopedLock
	RAII guard that enters the critical section on construction and exits it on destruction. More...

Static Public Member Functions
static void	Enter ()
	Enter a critical section.
static void	Exit ()
	Exit a critical section.

Private Member Functions
	CriticalSection ()
	STK_NONCOPYABLE_CLASS (CriticalSection)

Detailed Description

Nestable, SMP-safe critical section that combines local interrupt masking with a global cross-core spinlock.

Note

Mechanism (two-layer protocol):

1. Local interrupts are masked on the calling core (via PRIMASK / CPSID on Cortex-M, or equivalent on other architectures) to prevent re-entrant ISR access on this core.
2. A global spinlock (g_CsuLock) is then acquired to block any other core from entering the same critical section concurrently. On Enter() the spinlock is only acquired at nesting depth 0 so that nested Enter() calls from the same core do not deadlock. On Exit(), the spinlock is released and interrupts are restored only when the outermost Exit() brings the nesting counter back to zero.

SMP support: safe across multiple cores. The global spinlock ensures that only one core at a time can hold the section, regardless of interrupt state on other cores. On RP2040, the global lock is a hardware SIO peripheral spinlock rather than a software atomic, providing the cross-core guarantee with no software polling overhead until contention occurs.

Unprivileged mode: on Cortex-M targets with TrustZone / privilege separation, Enter() and Exit() escalate via SVC when called from an unprivileged thread, so the mechanism works correctly in both privileged and unprivileged task contexts.

Keep critical sections as short as possible. Every cycle spent holding the section blocks all other cores and increases interrupt latency, which can cause missed deadlines in HRT mode.

See also

SpinLock

Definition at line 201 of file stk_arch.h.

Constructor & Destructor Documentation

CriticalSection()

stk::hw::CriticalSection::CriticalSection ( )

inlineexplicitprivate

Definition at line 253 of file stk_arch.h.

{}

Referenced by STK_NONCOPYABLE_CLASS().

Here is the caller graph for this function:

Member Function Documentation

Enter()

void stk::hw::CriticalSection::Enter ( )

static

Enter a critical section.

Note

Masks local interrupts on this core and, at nesting depth 0, acquires the global cross-core spinlock. Subsequent nested Enter() calls on the same core increment the nesting counter without re-acquiring the spinlock, so nesting is safe.

Warning

Every Enter() must be paired with exactly one Exit(). A missing Exit() leaves local interrupts masked and the global spinlock held permanently, stalling all other cores and the scheduler. Prefer ScopedLock to avoid mismatched pairs.

Definition at line 74 of file stktest.cpp.

{
    ++g_CriticalSectionState;
}

References stk::test::g_CriticalSectionState.

Referenced by stk::sync::ScopedCriticalSection::Lock(), stk::hw::CriticalSection::ScopedLock::ScopedLock(), and stk_critical_section_enter().

Here is the caller graph for this function:

Exit()

void stk::hw::CriticalSection::Exit ( )

static

Exit a critical section.

Note

Decrements the nesting counter. When it reaches zero (outermost Exit()), releases the global cross-core spinlock first and then restores local interrupt masking to the state captured at the matching Enter().

Warning

Must only be called after a matching Enter(). Calling Exit() without a prior Enter() produces undefined behaviour (nesting counter underflow, caught by assertion in debug builds).

Definition at line 78 of file stktest.cpp.

{
    --g_CriticalSectionState;
 
    CHECK_TRUE(g_CriticalSectionState >= 0);
}

References stk::test::g_CriticalSectionState.

Referenced by stk_critical_section_exit(), stk::sync::ScopedCriticalSection::Unlock(), and stk::hw::CriticalSection::ScopedLock::~ScopedLock().

Here is the caller graph for this function:

STK_NONCOPYABLE_CLASS()

stk::hw::CriticalSection::STK_NONCOPYABLE_CLASS ( CriticalSection )

private

References CriticalSection().

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• stk_arch.h
• stktest.cpp