arm-m-switch.h File Reference

Cortex-M context-switch support helpers. More...

#include <stdint.h>
#include <zephyr/kernel_structs.h>
#include <zephyr/kernel/thread.h>

Go to the source code of this file.

Functions
void *	arm_m_new_stack (char *base, uint32_t sz, void *entry, void *arg0, void *arg1, void *arg2, void *arg3)
	Create an initial switch frame on a new thread's stack.
bool	arm_m_must_switch (void)
	Evaluate whether an interrupt should trigger a context switch.
void	arm_m_exc_exit (void)
	Assembly stub that completes the Cortex-M context restore.
bool	arm_m_iciit_check (uint32_t msp, uint32_t psp, uint32_t lr)
	Recover an interrupted IT/ICI instruction after a context switch.
void	arm_m_iciit_stub (void)
	Undefined-instruction stub used to force IT/ICI recovery.
static void	arm_m_exc_tail (void)
	ISR-tail helper that patches the stacked LR for deferred switch fixup.
static ALWAYS_INLINE void	arm_m_switch (void *switch_to, void **switched_from)
	Core Cortex-M context switch routine.
static ALWAYS_INLINE void	arch_switch (void *switch_to, void **switched_from)
	Public arch-level wrapper for the Cortex-M switch routine.

Variables
uint32_t *	arm_m_exc_lr_ptr
	Pointer to the stacked LR word used by the ISR tail fixup path.
uint32_t	arm_m_switch_stack_buffer
	Backing storage used when relocating stacks during switch operations.
struct arm_m_cs_ptrs	arm_m_cs_ptrs
	Global instance with current callee-saved frame pointers.

Detailed Description

Cortex-M context-switch support helpers.

The routines in this header back Zephyr's Cortex-M context-switch path when CONFIG_USE_SWITCH is enabled. They build and manipulate the stack frames consumed by the hand-written assembly in arm_m_switch() and the ISR tail-fixup logic, and expose a small interface to the scheduler and fault handlers.

Function Documentation

arch_switch()

ALWAYS_INLINE void arch_switch ( void * switch_to, void ** switched_from )

static

Public arch-level wrapper for the Cortex-M switch routine.

Thin inline that forwards to arm_m_switch() when the architecture uses the CONFIG_USE_SWITCH mechanism.

Parameters

switch_to	Switch handle for the next thread.
switched_from	Storage for the outgoing switch handle.

arm_m_exc_exit()

void arm_m_exc_exit

(

void

)

Assembly stub that completes the Cortex-M context restore.

This routine is patched into the LR saved on the ISR stack by arm_m_exc_tail() so that callee-saved registers can be fixed up and control returned to the correct thread context.

arm_m_exc_tail()

void arm_m_exc_tail ( void )

inlinestatic

ISR-tail helper that patches the stacked LR for deferred switch fixup.

Called near the end of interrupt handling, this routine optionally rewrites the topmost LR on the active stack to branch to arm_m_exc_exit() instead of the original return site. Doing so defers the expensive callee-saved register handling until just before returning to thread mode. Stack sentinel checking is also performed here when enabled.

arm_m_iciit_check()

bool arm_m_iciit_check	(	uint32_t	msp,
		uint32_t	psp,
		uint32_t	lr )

Recover an interrupted IT/ICI instruction after a context switch.

The function is called from the fault handler that follows the deliberate UDF in arm_m_iciit_stub(). It detects whether the undefined instruction came from our stub and, if so, restores the saved PC/xPSR to re-execute the original instruction.

Parameters

msp	Exception entry stack pointer for MSP.
psp	Exception entry stack pointer for PSP.
lr	EXC_RETURN value captured on exception entry.

Return values

true	The fault corresponded to the IT/ICI recovery stub and was handled.
false	The fault was unrelated and should be processed normally.

arm_m_iciit_stub()

void arm_m_iciit_stub

(

void

)

Undefined-instruction stub used to force IT/ICI recovery.

When an interrupt preempts certain conditional instructions inside an IT/ICI block and a context switch occurs, returning directly can violate architectural rules. The handler patches the stacked PC to this stub so the subsequent fault can repair and resume the original instruction.

arm_m_must_switch()

bool arm_m_must_switch

(

void

)

Evaluate whether an interrupt should trigger a context switch.

Invoked from the ISR tail path to decide if the scheduler selected a new thread. If a switch is needed, this saves the current callee-saved frame pointers in arm_m_cs_ptrs and initiates the hand-off to arm_m_do_switch().

Return values

true	A switch was performed or scheduled.
false	No switch requested; continue returning from the interrupt.

arm_m_new_stack()

void * arm_m_new_stack	(	char *	base,
		uint32_t	sz,
		void *	entry,
		void *	arg0,
		void *	arg1,
		void *	arg2,
		void *	arg3 )

Create an initial switch frame on a new thread's stack.

The stack contents are prepared so that the first invocation of arm_m_switch() can restore directly into entry with arguments arg0 through arg3. The stack base and size are aligned to the 8-byte requirement mandated by the ARM EABI.

Parameters

base	Start address of the stack buffer (lowest address).
sz	Size of the stack buffer in bytes.
entry	Entry point the thread should begin executing.
arg0	First argument passed to entry.
arg1	Second argument passed to entry.
arg2	Third argument passed to entry.
arg3	Fourth argument passed to entry.

Returns

Pointer to the synthesized switch handle to store in struct k_thread::switch_handle, or NULL if the stack is too small to hold the frame.

arm_m_switch()

ALWAYS_INLINE void arm_m_switch ( void * switch_to, void ** switched_from )

static

Core Cortex-M context switch routine.

Performs the low-level swap between the outgoing and incoming thread switch handles. Implemented with inline assembly to manage stacked frames, optional FPU/DSP state, privilege level, and stack guards. Called by arch_switch() and scheduler paths only.

Parameters

switch_to	Switch handle (typically PSP) for the next thread.
switched_from	Storage location to write the outgoing switch handle.

Variable Documentation

arm_m_cs_ptrs

struct arm_m_cs_ptrs arm_m_cs_ptrs

extern

Global instance with current callee-saved frame pointers.

arm_m_exc_lr_ptr

uint32_t* arm_m_exc_lr_ptr

extern

Pointer to the stacked LR word used by the ISR tail fixup path.

arm_m_switch_stack_buffer

uint32_t arm_m_switch_stack_buffer

extern

Backing storage used when relocating stacks during switch operations.