hardware_exception

Methods for setting processor exception handlers. More...

Typedefs
typedef void(*	exception_handler_t) (void)
	Exception handler function type. More...

Enumerations
enum	exception_number {   MIN_EXCEPTION_NUM = 2 , NMI_EXCEPTION = 2 , HARDFAULT_EXCEPTION = 3 , SVCALL_EXCEPTION = 11 ,   PENDSV_EXCEPTION = 14 , SYSTICK_EXCEPTION = 15 , MAX_EXCEPTION_NUM = 15 }
	Exception number definitions. More...

Functions
exception_handler_t	exception_set_exclusive_handler (enum exception_number num, exception_handler_t handler)
	Set the exception handler for an exception on the executing core. More...
void	exception_restore_handler (enum exception_number num, exception_handler_t original_handler)
	Restore the original exception handler for an exception on this core. More...
exception_handler_t	exception_get_vtable_handler (enum exception_number num)
	Get the current exception handler for the specified exception from the currently installed vector table of the execution core. More...
bool	exception_set_priority (uint num, uint8_t hardware_priority)
	Set specified exception's priority. More...
uint	exception_get_priority (uint num)
	Get specified exception's priority. More...

Detailed Description

Methods for setting processor exception handlers.

Exceptions are identified by a exception_number which is a number from -15 to -1; these are the numbers relative to the index of the first IRQ vector in the vector table. (i.e. vector table index is exception_num plus 16)

There is one set of exception handlers per core, so the exception handlers for each core as set by these methods are independent.

Note

That all exception APIs affect the executing core only (i.e. the core calling the function).

Typedef Documentation

exception_handler_t

typedef void(* exception_handler_t) (void)

Exception handler function type.

All exception handlers should be of this type, and follow normal ARM EABI register saving conventions

Enumeration Type Documentation

exception_number

enum exception_number

Exception number definitions.

On Arm these are vector table indices:

Name	Value	Exception
NMI_EXCEPTION	2	Non Maskable Interrupt
HARDFAULT_EXCEPTION	3	HardFault
SVCALL_EXCEPTION	11	SV Call
PENDSV_EXCEPTION	14	Pend SV
SYSTICK_EXCEPTION	15	System Tick

On RISC-V these are exception cause numbers:

Name	Value	Exception
INSTR_ALIGN_EXCEPTION	0	Instruction fetch misaligned
INSTR_FAULT_EXCEPTION	1	Instruction fetch bus fault
INSTR_ILLEGAL_EXCEPTION	2	Invalid or illegal instruction
EBREAK_EXCEPTION	3	ebreak was not caught by an ex
LOAD_ALIGN_EXCEPTION	4	Load address not naturally ali
LOAD_FAULT_EXCEPTION	5	Load bus fault
STORE_ALIGN_EXCEPTION	6	Store or AMO address not natur
STORE_FAULT_EXCEPTION	7	Store or AMO bus fault
ECALL_UMODE_EXCEPTION	8	ecall was executed in U-mode
ECALL_SMODE_EXCEPTION	9	ecall was executed in S-mode
ECALL_MMODE_EXCEPTION	11	ecall was executed in M-mode

Enumerator
NMI_EXCEPTION	Non Maskable Interrupt.
HARDFAULT_EXCEPTION	HardFault Interrupt.
SVCALL_EXCEPTION	SV Call Interrupt.
PENDSV_EXCEPTION	Pend SV Interrupt.
SYSTICK_EXCEPTION	System Tick Interrupt.

Function Documentation

exception_get_priority()

uint exception_get_priority

(

uint

num

)

Get specified exception's priority.

Numerically-lower values indicate a higher priority. Hardware priorities range from 0 (highest priority) to 255 (lowest priority).

Only the top 2 bits are significant on ARM Cortex-M0+ on RP2040.

Only the top 4 bits are significant on ARM Cortex-M33 on RP2350, and exception priorities are not supported on RISC-V

Parameters

num	Exception number exception_number

Returns

the exception priority

exception_get_vtable_handler()

exception_handler_t exception_get_vtable_handler

(

enum exception_number

num

)

Get the current exception handler for the specified exception from the currently installed vector table of the execution core.

Parameters

num	Exception number

Returns

the address stored in the VTABLE for the given exception number

exception_restore_handler()

void exception_restore_handler	(	enum exception_number	num,
		exception_handler_t	original_handler
	)

Restore the original exception handler for an exception on this core.

This method may be used to restore the exception handler for an exception on this core to the state prior to the call to exception_set_exclusive_handler(), so that exception_set_exclusive_handler() may be called again in the future.

Parameters

num	Exception number exception_number
original_handler	The original handler returned from exception_set_exclusive_handler

See also

exception_set_exclusive_handler()

exception_set_exclusive_handler()

exception_handler_t exception_set_exclusive_handler	(	enum exception_number	num,
		exception_handler_t	handler
	)

Set the exception handler for an exception on the executing core.

This method will assert if an exception handler has been set for this exception number on this core via this method, without an intervening restore via exception_restore_handler.

Note

this method may not be used to override an exception handler that was specified at link time by providing a strong replacement for the weakly defined stub exception handlers. It will assert in this case too.

Parameters

num	Exception number
handler	The handler to set

See also

exception_number

exception_set_priority()

bool exception_set_priority	(	uint	num,
		uint8_t	hardware_priority
	)

Set specified exception's priority.

Parameters

num	Exception number exception_number
hardware_priority	Priority to set.

Numerically-lower values indicate a higher priority. Hardware priorities range from 0 (highest priority) to 255 (lowest priority).

Only the top 2 bits are significant on ARM Cortex-M0+ on RP2040.

Only the top 4 bits are significant on ARM Cortex-M33 on RP2350, and exception priorities are not supported on RISC-V