System Device Configuration

group NMSIS_Core_SystemConfig

Functions for system and clock setup available in system_<device>.c.

HummingBird provides a template file system_Device.c that must be adapted by the silicon vendor to match their actual device. As a minimum requirement, this file must provide:

• A device-specific system configuration function, SystemInit.

• A global variable that contains the system frequency, SystemCoreClock.

• Global c library _premain_init and _postmain_fini functions called right before and after calling main function.

• Vendor customized interrupt, exception handling code, see Interrupt and Exception Handling

The file configures the device and, typically, initializes the oscillator (PLL) that is part of the microcontroller device. This file might export other functions or variables that provide a more flexible configuration of the microcontroller system.

And this file also provided common interrupt, exception exception handling framework template, Silicon vendor can customize these template code as they want.

Attention

Be aware that a value stored to SystemCoreClock during low level initializaton (i.e. SystemInit()) might get overwritten by C libray startup code and/or .bss section initialization. Thus its highly recommended to call SystemCoreClockUpdate at the beginning of the user main() routine.

Note

Please pay special attention to the static variable SystemCoreClock. This variable might be used throughout the whole system initialization and runtime to calculate frequency/time related values. Thus one must assure that the variable always reflects the actual system clock speed.

Functions

void SystemCoreClockUpdate(void)

Function to update the variable SystemCoreClock.

Updates the variable SystemCoreClock and must be called whenever the core clock is changed during program execution. The function evaluates the clock register settings and calculates the current core clock.

void SystemInit(void)

Function to Initialize the system.

Initializes the microcontroller system. Typically, this function configures the oscillator (PLL) that is part of the microcontroller device. For systems with a variable clock speed, it updates the variable SystemCoreClock. SystemInit is called from the file startup.

void SystemBannerPrint(void)

Banner Print for HummingBird SDK.

int32_t Core_Register_IRQ(uint32_t irqn, void *handler)

Register a riscv core interrupt and register the handler.

This function set interrupt handler for core interrupt

Remark

• This function use to configure riscv core interrupt and register its interrupt handler and enable its interrupt.

Parameters

• irqn – [in] interrupt number

• handler – [in] interrupt handler, if NULL, handler will not be installed

Returns

-1 means invalid input parameter. 0 means successful.

int32_t PLIC_Register_IRQ(uint32_t source, uint8_t priority, void *handler)

Register a specific plic interrupt and register the handler.

This function set priority and handler for plic interrupt

Remark

• This function use to configure specific plic interrupt and register its interrupt handler and enable its interrupt.

Parameters

• source – [in] interrupt source

• priority – [in] interrupt priority

• handler – [in] interrupt handler, if NULL, handler will not be installed

Returns

-1 means invalid input parameter. 0 means successful.

Variables

uint32_t SystemCoreClock = SYSTEM_CLOCK

Variable to hold the system core clock value.

Holds the system core clock, which is the system clock frequency supplied to the SysTick timer and the processor core clock. This variable can be used by debuggers to query the frequency of the debug timer or to configure the trace clock speed.

Attention

Compilers must be configured to avoid removing this variable in case the application program is not using it. Debugging systems require the variable to be physically present in memory so that it can be examined to configure the debugger.

Interrupt Exception NMI Handling

group NMSIS_Core_IntExcNMI_Handling

Functions for interrupt, exception handle available in system_<device>.c.

HBIRD provide a template for interrupt, exception handling. Silicon Vendor could adapat according to their requirement. Silicon vendor could implement interface for different exception code and replace current implementation.

Defines

MAX_SYSTEM_EXCEPTION_NUM 11

Max exception handler number.

Typedefs

typedef void (*EXC_HANDLER)(unsigned long mcause, unsigned long sp)

Exception Handler Function Typedef.

Note

This typedef is only used internal in this system_<Device>.c file. It is used to do type conversion for registered exception handler before calling it.

typedef void (*INT_HANDLER)(unsigned long mcause, unsigned long sp)

Functions

static uint32_t core_exception_handler(unsigned long mcause, unsigned long sp)

Common Exception handler entry.

This function provided a command entry for exception. Silicon Vendor could modify this template implementation according to requirement.

Remark

• RISCV provided common entry for all types of exception. This is proposed code template for exception entry function, Silicon Vendor could modify the implementation.

• For the core_exception_handler template, we provided exception register function Exception_Register_EXC which can help developer to register your exception handler for specific exception number.

static void system_default_exception_handler(unsigned long mcause, unsigned long sp)

System Default Exception Handler.

This function provided a default exception handling code for all exception ids. By default, It will just print some information for debug, Vendor can customize it according to its requirements.

static void system_default_interrupt_handler(unsigned long mcause, unsigned long sp)

System Default Interrupt Handler.

This function provided a default interrupt handling code for all interrupt ids.

static void Exception_Init(void)

Initialize all the default core exception handlers.

The core exception handler for each exception id will be initialized to system_default_exception_handler.

Note

Called in _init function, used to initialize default exception handlers for all exception IDs

static void Interrupt_Init(void)

Initialize all the default interrupt handlers.

The interrupt handler for each exception id will be initialized to system_default_interrupt_handler.

Note

Called in _init function, used to initialize default interrupt handlers for all interrupt IDs

void Exception_Register_EXC(uint32_t EXCn, unsigned long exc_handler)

Register an exception handler for exception code EXCn.

• For EXCn < MAX_SYSTEM_EXCEPTION_NUM, it will be registered into SystemExceptionHandlers[EXCn-1].

Parameters

• EXCn – See EXCn_Type

• exc_handler – The exception handler for this exception code EXCn

void Interrupt_Register_CoreIRQ(uint32_t irqn, unsigned long int_handler)

Register an core interrupt handler for core interrupt number.

• For irqn <= 10, it will be registered into SystemCoreInterruptHandlers[irqn-1].

Parameters

• irqn – See IRQn

• int_handler – The core interrupt handler for this interrupt code irqn

void Interrupt_Register_ExtIRQ(uint32_t irqn, unsigned long int_handler)

Register an external interrupt handler for plic external interrupt number.

• For irqn <= __PLIC_INTNUM, it will be registered into SystemExtInterruptHandlers[irqn-1].

Parameters

• irqn – See IRQn

• int_handler – The external interrupt handler for this interrupt code irqn

unsigned long Interrupt_Get_CoreIRQ(uint32_t irqn)

Get an core interrupt handler for core interrupt number.

Parameters

irqn – See IRQn

Returns

The core interrupt handler for this interrupt code irqn

unsigned long Interrupt_Get_ExtIRQ(uint32_t irqn)

Get an external interrupt handler for external interrupt number.

Parameters

irqn – See IRQn

Returns

The external interrupt handler for this interrupt code irqn

unsigned long Exception_Get_EXC(uint32_t EXCn)

Get current exception handler for exception code EXCn.

• For EXCn < MAX_SYSTEM_EXCEPTION_NUM, it will return SystemExceptionHandlers[EXCn-1].

Parameters

EXCn – See EXCn_Type

Returns

Current exception handler for exception code EXCn, if not found, return 0.

uint32_t core_trap_handler(unsigned long mcause, unsigned long sp)

Common trap entry.

This function provided a command entry for trap. Silicon Vendor could modify this template implementation according to requirement.

Remark

• RISCV provided common entry for all types of exception including exception and interrupt. This is proposed code template for exception entry function, Silicon Vendor could modify the implementation.

• If you want to register core exception handler, please use Exception_Register_EXC

• If you want to register core interrupt handler, please use Interrupt_Register_CoreIRQ

• If you want to register external interrupt handler, please use Interrupt_Register_ExtIRQ

Variables

static unsigned long SystemExceptionHandlers[MAX_SYSTEM_EXCEPTION_NUM]

Store the exception handlers for each exception ID.

Note

• This SystemExceptionHandlers are used to store all the handlers for all the exception codes RISC-V core provided.

• Exception code 0 - 11, totally 12 exceptions are mapped to SystemExceptionHandlers[0:11]

static unsigned long SystemExtInterruptHandlers[__PLIC_INTNUM]

static unsigned long SystemCoreInterruptHandlers[10]