v2.0.0
Typedefs | Enumerations | Functions
hardware_exception
Hardware APIs

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