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 instance that enters the critical section on construction and exits it on destruction. More...

Public Types
enum	ESessionFlags : uint8_t {   SESSION_FLAG_NONE = 0U ,   SESSION_FLAG_NPRIV = (1U << 0) }
	Collection of session flags. More...
typedef uint8_t	Session
	Opaque session token returned by Enter() and consumed by Exit().

Static Public Member Functions
static Session	Enter (const Session ses=DEFAULT_SESSION)
	Enter a critical section.
static void	Exit (const Session ses=DEFAULT_SESSION)
	Exit a critical section.

Static Public Attributes
static constexpr Session	DEFAULT_SESSION = SESSION_FLAG_NONE
	Default session value passed to Enter()/Exit() when the caller does not need to force a specific handling path.

Private Member Functions
	CriticalSection (const CriticalSection &)=delete
CriticalSection &	operator= (const CriticalSection &)=delete
	CriticalSection ()
	Protected constructor (instantiation is prohibited).

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 (s_StkCortexmCsuLock on the ARM Cortex-M back-end) 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 455 of file stk_arch.h.

Member Typedef Documentation

Session

typedef uint8_t stk::hw::CriticalSection::Session

Opaque session token returned by Enter() and consumed by Exit().

Note

Encodes the privileged/unprivileged handling path taken by Enter(), so that the matching Exit() can restore state correctly without re-detecting context.

Definition at line 471 of file stk_arch.h.

Member Enumeration Documentation

ESessionFlags

enum stk::hw::CriticalSection::ESessionFlags : uint8_t

Collection of session flags.

Enumerator
SESSION_FLAG_NONE	None.
SESSION_FLAG_NPRIV	Calling context is non-Privileged.

Definition at line 461 of file stk_arch.h.

    {
        SESSION_FLAG_NONE  = 0U,        
        SESSION_FLAG_NPRIV = (1U << 0), 
    };

Constructor & Destructor Documentation

CriticalSection() [1/2]

stk::hw::CriticalSection::CriticalSection ( const CriticalSection & )

privatedelete

References CriticalSection().

Referenced by CriticalSection(), and stk::hw::CriticalSection::ScopedLock::ScopedLock().

Here is the call graph for this function:

Here is the caller graph for this function:

CriticalSection() [2/2]

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

inlineexplicitprivate

Protected constructor (instantiation is prohibited).

Definition at line 544 of file stk_arch.h.

    {}

Member Function Documentation

Enter()

Session stk::hw::CriticalSection::Enter ( const Session ses = DEFAULT_SESSION )

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.

Parameters

[in]

ses

DEFAULT_SESSION to auto-detect the calling context's privilege level, or an explicit Session to force a specific handling path.

Returns

Opaque Session token to pass to the matching Exit() call. Encodes which handling path was taken (see SESSION_FLAG_NPRIV) - not to be interpreted as a plain privileged/unprivileged boolean.

References DEFAULT_SESSION.

Referenced by stk::sync::ScopedCriticalSection::Lock(), osKernelLock(), osKernelRestoreLock(), stk::hw::CriticalSection::ScopedLock::ScopedLock(), stk_critical_section_enter(), stk_critical_section_enter_ex(), vPortEnterCritical(), and vTaskSuspendAll().

Here is the caller graph for this function:

Exit()

void stk::hw::CriticalSection::Exit ( const Session ses = DEFAULT_SESSION )

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 behavior (nesting counter underflow, caught by assertion in debug builds).

Parameters

[in]

ses

Session value returned by the matching Enter() call.

References DEFAULT_SESSION.

Referenced by osKernelRestoreLock(), osKernelUnlock(), stk_critical_section_exit(), stk_critical_section_exit_ex(), stk::sync::ScopedCriticalSection::Unlock(), vPortExitCritical(), xTaskResumeAll(), and stk::hw::CriticalSection::ScopedLock::~ScopedLock().

Here is the caller graph for this function:

operator=()

CriticalSection & stk::hw::CriticalSection::operator= ( const CriticalSection & )

privatedelete

Member Data Documentation

DEFAULT_SESSION

Session stk::hw::CriticalSection::DEFAULT_SESSION = SESSION_FLAG_NONE

staticconstexpr

Default session value passed to Enter()/Exit() when the caller does not need to force a specific handling path.

Note

With this value, Enter() auto-detects whether the calling context is privileged or unprivileged.

Definition at line 478 of file stk_arch.h.

Referenced by Enter(), Exit(), stk_critical_section_enter(), and stk_critical_section_exit().

---

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

• stk_arch.h