System Device Configuration

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

Modules
	Interrupt and Exception and NMI Handling
	Functions for interrupt, exception and nmi handle available in system_<device>.c.

Macros
#define	FALLBACK_DEFAULT_ECLIC_BASE   0x0C000000UL
#define	FALLBACK_DEFAULT_SYSTIMER_BASE   0x02000000UL
#define	CLINT_MSIP(base, hartid)   (*(volatile uint32_t *)((uintptr_t)((base) + ((hartid) * 4))))
#define	SMP_CTRLREG(base, ofs)   (*(volatile uint32_t *)((uintptr_t)((base) + (ofs))))

Typedefs
typedef void(*	fnptr) (void)

Functions
void	default_intexc_handler (void)
	default eclic interrupt or exception interrupt handler More...
void	SystemCoreClockUpdate (void)
	Function to update the variable SystemCoreClock. More...
void	SystemInit (void)
	Function to Initialize the system. More...
void	SystemBannerPrint (void)
	Banner Print for Nuclei SDK. More...
void	ECLIC_Init (void)
	initialize eclic config More...
int32_t	ECLIC_Register_IRQ (IRQn_Type IRQn, uint8_t shv, ECLIC_TRIGGER_Type trig_mode, uint8_t lvl, uint8_t priority, void *handler)
	Initialize a specific IRQ and register the handler. More...
int32_t	ECLIC_Register_IRQ_S (IRQn_Type IRQn, uint8_t shv, ECLIC_TRIGGER_Type trig_mode, uint8_t lvl, uint8_t priority, void *handler)
	Initialize a specific IRQ and register the handler for supervisor mode. More...
static void	_get_iregion_info (IRegion_Info_Type *iregion)
	Get Nuclei Internal Region Information. More...
void	__sync_harts (void)
	Synchronize all harts. More...
static void	Trap_Init (void)
	do the init for trap(interrupt and exception) entry for supervisor mode More...
void	_premain_init (void)
	early init function before main More...
void	_postmain_fini (int status)
	finish function after main More...
void	_init (void)
	_init function called in __libc_init_array() More...
void	_fini (void)
	_fini function called in __libc_fini_array() More...

Variables
fnptr	irq_entry_s
	default entry for s-mode non-vector irq entry More...
fnptr	exc_entry_s
	default entry for s-mode exception entry More...
volatile uint32_t	SystemCoreClock = SYSTEM_CLOCK
	Variable to hold the system core clock value. More...
volatile IRegion_Info_Type	SystemIRegionInfo
	Nuclei RISC-V CPU IRegion Information Variable used to store probed info. More...

Detailed Description

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

Nuclei 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.
• Global c library _premain_init and _postmain_fini functions called right before calling main function.
  • A global variable that contains the system frequency, SystemCoreClock.
  • A global eclic configuration initialization, ECLIC_Init.
  • A global exception and trap configuration initialization, Trap_Init and Exception_Init.
• Vendor customized interrupt, exception and nmi handling code, see Interrupt and Exception and NMI 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 and NMI exception handling framework template, Silicon vendor can customize these template code as they want.

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.

Attention

Be aware that a value stored to SystemCoreClock during low level initialization (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.

Macro Definition Documentation

CLINT_MSIP

#define CLINT_MSIP	(		base,
			hartid
	)		(*(volatile uint32_t *)((uintptr_t)((base) + ((hartid) * 4))))

Definition at line 681 of file system_Device.c.

FALLBACK_DEFAULT_ECLIC_BASE

#define FALLBACK_DEFAULT_ECLIC_BASE   0x0C000000UL

Definition at line 649 of file system_Device.c.

FALLBACK_DEFAULT_SYSTIMER_BASE

#define FALLBACK_DEFAULT_SYSTIMER_BASE   0x02000000UL

Definition at line 650 of file system_Device.c.

SMP_CTRLREG

#define SMP_CTRLREG	(		base,
			ofs
	)		(*(volatile uint32_t *)((uintptr_t)((base) + (ofs))))

Definition at line 682 of file system_Device.c.

Typedef Documentation

fnptr

typedef void(* fnptr) (void)

Definition at line 74 of file system_Device.c.

Function Documentation

__sync_harts()

void __sync_harts

(

void

)

Synchronize all harts.

This function is used to synchronize all the harts, especially to wait the boot hart finish initialization of data section, bss section and c runtines initialization This function must be placed in .text.init section, since section initialization is not ready, global variable and static variable should be avoid to use in this function, and avoid to call other functions

Definition at line 684 of file system_Device.c.

{
// Only do synchronize when SMP_CPU_CNT is defined and number > 0
#if defined(SMP_CPU_CNT) && (SMP_CPU_CNT > 1)
    unsigned long hartid = __get_hart_id();
    unsigned long tmr_hartid = __get_hart_index();
    unsigned long clint_base, irgb_base, smp_base;
    unsigned long mcfg_info;
 
    mcfg_info = __RV_CSR_READ(CSR_MCFG_INFO);
    if (mcfg_info & MCFG_INFO_IREGION_EXIST) { // IRegion Info present
        // clint base = system timer base + 0x1000
        irgb_base = (__RV_CSR_READ(CSR_MIRGB_INFO) >> 10) << 10;
        clint_base = irgb_base + IREGION_TIMER_OFS + 0x1000;
        smp_base = irgb_base + IREGION_SMP_OFS;
    } else {
        clint_base = FALLBACK_DEFAULT_SYSTIMER_BASE + 0x1000;
        smp_base = (__RV_CSR_READ(CSR_MSMPCFG_INFO) >> 4) << 4;
    }
    // Enable SMP and L2, disable cluster local memory
    SMP_CTRLREG(smp_base, 0xc) = 0xFFFFFFFF;
    SMP_CTRLREG(smp_base, 0x10) = 0x1;
    SMP_CTRLREG(smp_base, 0xd8) = 0x0;
    __SMP_RWMB();
 
    // pre-condition: interrupt must be disabled, this is done before calling this function
    // BOOT_HARTID is defined <Device.h>
    if (hartid == BOOT_HARTID) { // boot hart
        // clear msip pending
        for (int i = 0; i < SMP_CPU_CNT; i ++) {
            CLINT_MSIP(clint_base, i) = 0;
        }
        __SMP_RWMB();
    } else {
        // Set machine software interrupt pending to 1
        CLINT_MSIP(clint_base, tmr_hartid) = 1;
        __SMP_RWMB();
        // wait for pending bit cleared by boot hart
        while (CLINT_MSIP(clint_base, tmr_hartid) == 1);
    }
#endif
}

_fini()

void _fini

(

void

)

_fini function called in __libc_fini_array()

This __libc_fini_array() function is called when exit main. user need to implement this function, otherwise when link it will error fini.c:(.text.__libc_fini_array+0x28): undefined reference to ‘_fini’

Note

Please use _postmain_fini function now

Definition at line 884 of file system_Device.c.

{
    /* Don't put any code here, please use _postmain_fini now */
}

_get_iregion_info()

static void _get_iregion_info ( IRegion_Info_Type *  iregion )

static

Get Nuclei Internal Region Information.

This function is used to get nuclei cpu internal region information, such as iregion base, eclic base, smp base, timer base and idu base, and fallback to old evalsoc timer and eclic base if no iregion feature found

Definition at line 662 of file system_Device.c.

{
    unsigned long mcfg_info;
    if (iregion == NULL) {
        return;
    }
    mcfg_info = __RV_CSR_READ(CSR_MCFG_INFO);
    if (mcfg_info & MCFG_INFO_IREGION_EXIST) { // IRegion Info present
        iregion->iregion_base = (__RV_CSR_READ(CSR_MIRGB_INFO) >> 10) << 10;
        iregion->eclic_base = iregion->iregion_base + IREGION_ECLIC_OFS;
        iregion->systimer_base = iregion->iregion_base + IREGION_TIMER_OFS;
        iregion->smp_base = iregion->iregion_base + IREGION_SMP_OFS;
        iregion->idu_base = iregion->iregion_base + IREGION_IDU_OFS;
    } else {
        iregion->eclic_base = FALLBACK_DEFAULT_ECLIC_BASE;
        iregion->systimer_base = FALLBACK_DEFAULT_SYSTIMER_BASE;
    }
}

_init()

void _init

(

void

)

_init function called in __libc_init_array()

This __libc_init_array() function is called during startup code, user need to implement this function, otherwise when link it will error init.c:(.text.__libc_init_array+0x26): undefined reference to ‘_init’

Note

Please use _premain_init function now

Definition at line 870 of file system_Device.c.

{
    /* Don't put any code here, please use _premain_init now */
}

_postmain_fini()

void _postmain_fini

(

int

status

)

finish function after main

Parameters

[in]

status

status code return from main

This function is executed right after main function. For RISC-V gnu toolchain, _fini function might not be called by __libc_fini_array function, so we defined a new function to do initialization

Definition at line 854 of file system_Device.c.

{
    /* TODO: Add your own finishing code here, called after main */
    extern void simulation_exit(int status);
    simulation_exit(status);
}

_premain_init()

void _premain_init

(

void

)

early init function before main

This function is executed right before main function. For RISC-V gnu toolchain, _init function might not be called by __libc_init_array function, so we defined a new function to do initialization.

Definition at line 774 of file system_Device.c.

{
    // TODO to make it possible for configurable boot hartid
    unsigned long hartid = __get_hart_id();
 
    // BOOT_HARTID is defined <Device.h>
    if (hartid == BOOT_HARTID) { // only done in boot hart
        // IREGION INFO MUST BE SET BEFORE ANY PREMAIN INIT STEPS
        _get_iregion_info((IRegion_Info_Type *)(&SystemIRegionInfo));
    }
    /* TODO: Add your own initialization code here, called before main */
    // This code located in RUNMODE_CONTROL ifdef endif block just for internal usage
    // No need to use in your code
#ifdef RUNMODE_CONTROL
#if defined(RUNMODE_ILM_EN) && RUNMODE_ILM_EN == 0
    // Only disable ilm when it is present
    if (__RV_CSR_READ(CSR_MCFG_INFO) & MCFG_INFO_ILM) {
        __RV_CSR_CLEAR(CSR_MILM_CTL, MILM_CTL_ILM_EN);
    }
#endif
#if defined(RUNMODE_DLM_EN) && RUNMODE_DLM_EN == 0
    // Only disable dlm when it is present
    if (__RV_CSR_READ(CSR_MCFG_INFO) & MCFG_INFO_DLM) {
        __RV_CSR_CLEAR(CSR_MDLM_CTL, MDLM_CTL_DLM_EN);
    }
#endif
#endif
 
    /* __ICACHE_PRESENT and __DCACHE_PRESENT are defined in demosoc.h */
    // For our internal cpu testing, they want to set demosoc __ICACHE_PRESENT/__DCACHE_PRESENT to be 1
    // __CCM_PRESENT is still default to 0 in demosoc.h, since it is used in core_feature_eclic.h to register interrupt, if set to 1, it might cause exception
    // but in the cpu, icache or dcache might not exist due to cpu configuration, so here
    // we need to check whether icache/dcache really exist, if yes, then turn on it
#if defined(__ICACHE_PRESENT) && (__ICACHE_PRESENT == 1)
    if (ICachePresent()) { // Check whether icache real present or not
        EnableICache();
    }
#endif
#if defined(__DCACHE_PRESENT) && (__DCACHE_PRESENT == 1)
    if (DCachePresent()) { // Check whether dcache real present or not
        EnableDCache();
    }
#endif
 
    /* Do fence and fence.i to make sure previous ilm/dlm/icache/dcache control done */
    __RWMB();
    __FENCE_I();
 
    if (hartid == BOOT_HARTID) { // only required for boot hartid
        // TODO implement get_cpu_freq function to get real cpu clock freq in HZ or directly give the real cpu HZ
        SystemCoreClock = get_cpu_freq();
        uart_init(SOC_DEBUG_UART, 115200);
        /* Display banner after UART initialized */
        SystemBannerPrint();
        /* Initialize exception default handlers */
        Exception_Init();
        /* ECLIC initialization, mainly MTH and NLBIT */
        ECLIC_Init();
        Trap_Init();
        // TODO: internal usage for Nuclei
#ifdef RUNMODE_CONTROL
        printf("Current RUNMODE=%s, ilm:%d, dlm %d, icache %d, dcache %d, ccm %d\n", \
            RUNMODE_STRING, RUNMODE_ILM_EN, RUNMODE_DLM_EN, \
            RUNMODE_IC_EN, RUNMODE_DC_EN, RUNMODE_CCM_EN);
        printf("CSR: MILM_CTL 0x%x, MDLM_CTL 0x%x, MCACHE_CTL 0x%x\n", \
            __RV_CSR_READ(CSR_MILM_CTL), __RV_CSR_READ(CSR_MDLM_CTL), \
            __RV_CSR_READ(CSR_MCACHE_CTL));
#endif
    }
}

default_intexc_handler()

void default_intexc_handler

(

void

)

default eclic interrupt or exception interrupt handler

ECLIC_Init()

void ECLIC_Init

(

void

)

initialize eclic config

ECLIC needs be initialized after boot up, Vendor could also change the initialization configuration.

Definition at line 553 of file system_Device.c.

{
    /* Global Configuration about MTH and NLBits.
     * TODO: Please adapt it according to your system requirement.
     * This function is called in _init function */
    ECLIC_SetMth(0);
    ECLIC_SetCfgNlbits(__ECLIC_INTCTLBITS);
 
#if defined(__TEE_PRESENT) && (__TEE_PRESENT == 1)
    /* Global Configuration about STH */
    ECLIC_SetSth(0);
#endif
}

ECLIC_Register_IRQ()

int32_t ECLIC_Register_IRQ	(	IRQn_Type	IRQn,
		uint8_t	shv,
		ECLIC_TRIGGER_Type	trig_mode,
		uint8_t	lvl,
		uint8_t	priority,
		void *	handler
	)

Initialize a specific IRQ and register the handler.

This function set vector mode, trigger mode and polarity, interrupt level and priority, assign handler for specific IRQn.

Parameters

[in]	IRQn	NMI interrupt handler address
[in]	shv	ECLIC_NON_VECTOR_INTERRUPT means non-vector mode, and ECLIC_VECTOR_INTERRUPT is vector mode
[in]	trig_mode	see ECLIC_TRIGGER_Type
[in]	lvl	interupt level
[in]	priority	interrupt priority
[in]	handler	interrupt handler, if NULL, handler will not be installed

Returns

-1 means invalid input parameter. 0 means successful.

Remarks

• This function use to configure specific eclic interrupt and register its interrupt handler and enable its interrupt.
• If the vector table is placed in read-only section(FLASHXIP mode), handler could not be installed

Definition at line 583 of file system_Device.c.

{
    if ((IRQn > SOC_INT_MAX) || (shv > ECLIC_VECTOR_INTERRUPT) \
        || (trig_mode > ECLIC_NEGTIVE_EDGE_TRIGGER)) {
        return -1;
    }
 
    /* set interrupt vector mode */
    ECLIC_SetShvIRQ(IRQn, shv);
    /* set interrupt trigger mode and polarity */
    ECLIC_SetTrigIRQ(IRQn, trig_mode);
    /* set interrupt level */
    ECLIC_SetLevelIRQ(IRQn, lvl);
    /* set interrupt priority */
    ECLIC_SetPriorityIRQ(IRQn, priority);
    if (handler != NULL) {
        /* set interrupt handler entry to vector table */
        ECLIC_SetVector(IRQn, (rv_csr_t)handler);
    }
    /* enable interrupt */
    ECLIC_EnableIRQ(IRQn);
    return 0;
}

ECLIC_Register_IRQ_S()

int32_t ECLIC_Register_IRQ_S	(	IRQn_Type	IRQn,
		uint8_t	shv,
		ECLIC_TRIGGER_Type	trig_mode,
		uint8_t	lvl,
		uint8_t	priority,
		void *	handler
	)

Initialize a specific IRQ and register the handler for supervisor mode.

This function set vector mode, trigger mode and polarity, interrupt level and priority, assign handler for specific IRQn.

Parameters

[in]	IRQn	NMI interrupt handler address
[in]	shv	ECLIC_NON_VECTOR_INTERRUPT means non-vector mode, and ECLIC_VECTOR_INTERRUPT is vector mode
[in]	trig_mode	see ECLIC_TRIGGER_Type
[in]	lvl	interupt level
[in]	priority	interrupt priority
[in]	handler	interrupt handler, if NULL, handler will not be installed

Returns

-1 means invalid input parameter. 0 means successful.

Remarks

• This function use to configure specific eclic S-mode interrupt and register its interrupt handler and enable its interrupt.
• If the vector table is placed in read-only section (FLASHXIP mode), handler could not be installed.

Definition at line 624 of file system_Device.c.

{
    if ((IRQn > SOC_INT_MAX) || (shv > ECLIC_VECTOR_INTERRUPT) \
        || (trig_mode > ECLIC_NEGTIVE_EDGE_TRIGGER)) {
        return -1;
    }
 
    /* set interrupt vector mode */
    ECLIC_SetShvIRQ_S(IRQn, shv);
    /* set interrupt trigger mode and polarity */
    ECLIC_SetTrigIRQ_S(IRQn, trig_mode);
    /* set interrupt level */
    ECLIC_SetLevelIRQ_S(IRQn, lvl);
    /* set interrupt priority */
    ECLIC_SetPriorityIRQ_S(IRQn, priority);
    if (handler != NULL) {
        /* set interrupt handler entry to vector table */
        ECLIC_SetVector_S(IRQn, (rv_csr_t)handler);
    }
    /* enable interrupt */
    ECLIC_EnableIRQ_S(IRQn);
    return 0;
}

SystemBannerPrint()

void SystemBannerPrint

(

void

)

Banner Print for Nuclei SDK.

Definition at line 534 of file system_Device.c.

{
#if defined(NUCLEI_BANNER) && (NUCLEI_BANNER == 1)
    printf("Nuclei SDK Build Time: %s, %s\r\n", __DATE__, __TIME__);
#ifdef DOWNLOAD_MODE_STRING
    printf("Download Mode: %s\r\n", DOWNLOAD_MODE_STRING);
#endif
    printf("CPU Frequency %u Hz\r\n", (unsigned int)SystemCoreClock);
    printf("CPU HartID: %u\r\n", (unsigned int)__get_hart_id());
#endif
}

SystemCoreClockUpdate()

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.

Definition at line 231 of file system_Device.c.

{
    /* ToDo: add code to calculate the system frequency based upon the current
     *    register settings.
     * Note: This function can be used to retrieve the system core clock frequeny
     *    after user changed register settings.
     */
    SystemCoreClock = SYSTEM_CLOCK;
}

SystemInit()

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_device.

Definition at line 249 of file system_Device.c.

{
    /* ToDo: add code to initialize the system
     * Warn: do not use global variables because this function is called before
     * reaching pre-main. RW section maybe overwritten afterwards.
     */
    SystemCoreClock = SYSTEM_CLOCK;
}

Trap_Init()

static void Trap_Init ( void  )

static

do the init for trap(interrupt and exception) entry for supervisor mode

This function provide initialization of CSR_STVT CSR_STVT2 and CSR_STVEC.

Definition at line 744 of file system_Device.c.

{
#if defined(__TEE_PRESENT) && (__TEE_PRESENT == 1)
    /*
     * Intialize ECLIC supervisor mode vector interrupt
     * base address stvt to vector_table_s
     */
    __RV_CSR_WRITE(CSR_STVT, (unsigned long)&vector_table_s);
    /*
     * Set ECLIC supervisor mode non-vector entry to be controlled
     * by stvt2 CSR register.
     * Intialize supervisor mode ECLIC non-vector interrupt
     * base address stvt2 to irq_entry_s.
    */
    __RV_CSR_WRITE(CSR_STVT2, (unsigned long)&irq_entry_s);
    __RV_CSR_SET(CSR_STVT2, 0x01);
    /*
     * Set supervisor exception entry stvec to exc_entry_s */
    __RV_CSR_WRITE(CSR_STVEC, (unsigned long)&exc_entry_s);
#endif
}

Variable Documentation

exc_entry_s

fnptr exc_entry_s

default entry for s-mode exception entry

irq_entry_s

fnptr irq_entry_s

default entry for s-mode non-vector irq entry

SystemCoreClock

volatile 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.

Definition at line 218 of file system_Device.c.

SystemIRegionInfo

volatile IRegion_Info_Type SystemIRegionInfo

Nuclei RISC-V CPU IRegion Information Variable used to store probed info.

Definition at line 653 of file system_Device.c.