Cortex-M support routines

Routines supporting access to Cortex-M core facilities. More...

Data Structures
struct	ExceptionFrame
	Exception frame without FPU context saved. More...
struct	ExceptionFrameFP
	Exception frame with FPU context saved. More...

Macros
#define	EXCEPTION_FRAME_ENTRIES   (sizeof(ExceptionFrame) / sizeof(uint32_t))
	How many stack slots does exception frame without FPU occupy.
#define	EXCEPTION_FRAME_FP_ENTRIES   (sizeof(ExceptionFrameFP) / sizeof(uint32_t))
	How many stack slots does exception frame with FPU occupy.
#define	ALWAYS_INLINE   __STATIC_FORCEINLINE
#define	SAVE_CONTEXT()
	Save application context.
#define	LOAD_CONTEXT()
	Load application context.

Functions
ALWAYS_INLINE void	__ISR_return ()
	Perform same actions as normal ISR return does.
uint32_t *	get_exception_arg_addr (ExceptionFrame *frame, unsigned argno, bool fp_active)
	Retrieve address of n-th argument from exception frame.
static unsigned	get_exception_argument (ExceptionFrame *frame, unsigned argno, bool fp_active)
	Retrieve value of exception frame function call argument.
static void	set_exception_argument (ExceptionFrame *frame, unsigned argno, unsigned value, bool fp_active)
	Set value of exception frame function call argument.
static void	set_exception_pc_lr (ExceptionFrame *frame, void *pc, void(*lr)(void))
	Configure PC and LR register values in exception frame.
ExceptionFrame *	push_exception_frame (ExceptionFrame *frame, unsigned args, bool fp_active)
	Duplicate exception frame on thread's stack.
ExceptionFrame *	shim_exception_frame (ExceptionFrame *frame, unsigned args, bool fp_active)
	Creates space for additional arguments under exception frame.
ExceptionFrame *	pop_exception_frame (ExceptionFrame *frame, unsigned args, bool fp_active)
	Remove exception frame from thread's stack.
ALWAYS_INLINE void *	__get_LR (void)
	Get value of process LR.
ALWAYS_INLINE void	__set_LR (void *lr)
	Set value of process LR.
ALWAYS_INLINE void	__forge_shutdown_exception_frame (void(*continue_here)(void))
	Forges shutdown exception frame.

Detailed Description

Routines supporting access to Cortex-M core facilities.

These routines allow kernel to perform some cricital tasks that the architecture support layer needs to be able to execute in order to support CMRX on Cortex-M.

Macro Definition Documentation

ALWAYS_INLINE

#define ALWAYS_INLINE   __STATIC_FORCEINLINE

EXCEPTION_FRAME_ENTRIES

#define EXCEPTION_FRAME_ENTRIES   (sizeof(ExceptionFrame) / sizeof(uint32_t))

How many stack slots does exception frame without FPU occupy.

EXCEPTION_FRAME_FP_ENTRIES

#define EXCEPTION_FRAME_FP_ENTRIES   (sizeof(ExceptionFrameFP) / sizeof(uint32_t))

How many stack slots does exception frame with FPU occupy.

LOAD_CONTEXT

#define LOAD_CONTEXT

(

)

Value:

asm ( \
    ".syntax unified\n\t" \
    "MRS r0, PSP\n\t" \
    "LDMFD r0!, {r4 - r7}\n\t" \
    "MOV r8, r4\n\t" \
    "MOV r9, r5\n\t" \
    "MOV r10, r6\n\t" \
    "MOV r11, r7\n\t" \
    "LDMFD r0!, {r4 - r7}\n\t" \
    "MSR PSP, r0\n\t" \
    : : : "r0", "r4", "r5", "r6", "r7", "memory" \
)

Load application context.

This function will grab process SP and load 8 registers from memory location pointed by the PSP. Process SP is updated to point to the new top of the stack. This operation will pop 32 bytes (8 registers * 4 bytes) from stack.

Note

This is defined as a macro so it can live inside naked functions.

Parameters

sp	address where top of the stack containing application context is

SAVE_CONTEXT

#define SAVE_CONTEXT

(

)

Value:

asm volatile( \
    ".syntax unified\n\t" \
    "MRS r0, PSP\n\t" \
    "SUBS r0, #16\n\t" \
    "STMEA r0!, {r4 - r7}\n\t" \
    "SUBS r0, #32\n\t" \
    "MOV r4, r8\n\t" \
    "MOV r5, r9\n\t" \
    "MOV r6, r10\n\t" \
    "MOV r7, r11\n\t" \
    "STMEA r0!, {r4 - r7}\n\t" \
    "SUBS r0, #16\n\t" \
    "MSR PSP, r0\n\t" \
    : : : "r0", "r4", "r5", "r6", "r7", "memory" \
)

Save application context.

This function will grab process SP and save 8 registers at the memory location pointed by the PSP. Process SP is updated to point to the new top of stack. This operation will push 32 bytes (8 registers * 4 bytes) on stack.

Note

This is defined as a macro so it can live inside naked functions.

Function Documentation

__forge_shutdown_exception_frame()

ALWAYS_INLINE void __forge_shutdown_exception_frame

(

void(*)(void)

continue_here

)

Forges shutdown exception frame.

This exception frame sets CPU state to state similar to boot: Privileged thread mode, MSP used as the stack. Then exception return is used to load this frame and effectively shutdown the remainder of the kernel. After this function is executed, processor will continue running code pointed to by continue_here in privileged thread mode.

__get_LR()

ALWAYS_INLINE void * __get_LR

(

void

)

Get value of process LR.

Returns

top of application stack

__ISR_return()

ALWAYS_INLINE void __ISR_return

(

)

Perform same actions as normal ISR return does.

When ISR performs return, then Cortex-M core does some specific steps to exit the ISR and return into thread whose execution has been interrupted. The ISR frame stored in thread stack is loaded back into registers. Perform the same steps.

__set_LR()

ALWAYS_INLINE void __set_LR

(

void *

lr

)

Set value of process LR.

Parameters

lr	The new value of LR to set

get_exception_arg_addr()

uint32_t * get_exception_arg_addr	(	ExceptionFrame *	frame,
		unsigned	argno,
		bool	fp_active
	)

Retrieve address of n-th argument from exception frame.

This function calculates address of n-th argument of function call from exception frame. This is used whenever it is known, that exception frame was stored as an effect of __SVC() call. It will automatically handle exception frame padding.

Parameters

frame	exception frame base address (usually value of SP)
argno	number of argument retrieved

Returns

address of argument relative to exception frame

get_exception_argument()

static unsigned get_exception_argument ( ExceptionFrame *  frame, unsigned  argno, bool  fp_active  )

inlinestatic

Retrieve value of exception frame function call argument.

Retrieves value of n-th argument of function call calling __SVC()

Parameters

frame	exception frame base address
argno	number of argument retrieved

Returns

value of function argument

pop_exception_frame()

ExceptionFrame * pop_exception_frame	(	ExceptionFrame *	frame,
		unsigned	args,
		bool	fp_active
	)

Remove exception frame from thread's stack.

This function will revert effects of calling push_exception_frame. It will handle frame padding automatically.

Parameters

frame	exception frame base address
args	number of function arguments passed onto stack (function args - 4)
fp_active	if true then floating point unit is actively used in the thread exception is for

Returns

new address of stack top after frame has been removed from it

push_exception_frame()

ExceptionFrame * push_exception_frame	(	ExceptionFrame *	frame,
		unsigned	args,
		bool	fp_active
	)

Duplicate exception frame on thread's stack.

Parameters

frame	pointer of frame currently residing on top of process' stack
args	amount of arguments pushed onto stack (first four come into R0-R3, fifth and following are pushed onto stack)
fp_active	if true then floating point unit is actively used in the thread exception is for

Returns

address of duplicated exception frame

set_exception_argument()

static void set_exception_argument ( ExceptionFrame *  frame, unsigned  argno, unsigned  value, bool  fp_active  )

inlinestatic

Set value of exception frame function call argument.

Sets value of n-th argument in exception frame.

Parameters

frame	exception frame base address
argno	number of argument retrieved
value	new value of function argument

set_exception_pc_lr()

static void set_exception_pc_lr ( ExceptionFrame *  frame, void *  pc, void(*)(void)  lr  )

inlinestatic

Configure PC and LR register values in exception frame.

This function sets values for PC and LR upon usage of given exception frame.

Parameters

frame	exception frame base address
pc	new value for PC register in exception frame
lr	new value for LR register in exception frame

shim_exception_frame()

ExceptionFrame * shim_exception_frame	(	ExceptionFrame *	frame,
		unsigned	args,
		bool	fp_active
	)

Creates space for additional arguments under exception frame.

This function will move exception frame content args * 4 bytes lower. If resulting address won't be 8-byt aligned, then additional alignment is applied to it. Content of exception frame is copied automatically.

Parameters

frame	address of exception frame in memory
args	amount of additional arguments for which space should be created under exception frame
fp_active	if true then floating point unit is actively used in the thread exception is for

Returns

address of shimmed exception frame.