# NMSIS Core Device Templates

The [**evalsoc**][4] implementation in Nuclei SDK serves as a **latest reference implementation** of the [**NMSIS Core Device Templates**][1].

Device templates located in https://github.com/Nuclei-Software/NMSIS/tree/master/Device/_Template_Vendor will not be updated anymore.

We support the following toolchains in this evalsoc implementation:

- **Nuclei RISC-V GNU Toolchain**: https://doc.nucleisys.com/nuclei_tools/toolchain/gnu/index.html
- **Nuclei RISC-V LLVM Toolchain**: https://doc.nucleisys.com/nuclei_tools/toolchain/llvm/index.html
- **IAR RISC-V Toolchain**: http://iar.com/riscv
- **Terapines ZCC Toolchain**: https://www.terapines.com/products/zcc

## Quick Porting Guide

To quickly port this SDK to your custom SoC (designed with Nuclei 200/300/600/900/1000 series CPU), please refer to our comprehensive porting guide:

[Porting Guide: From EvalSoC to Custom SoC](https://doc.nucleisys.com/nuclei_studio_supply/28-quick_porting_from_evalsoc_to_customsoc_based_on_Nuclei_SDK)

## Directory Structure 

### Board Support (`Board/nuclei_fpga_eval/`)

* Configuration Files
  - `npk.yml`: Board Support Package Configuration File for [NPK][2]
  - `openocd_evalsoc.cfg`: OpenOCD configuration for on-board debugging using [HummingBird Debugger][3]
  - `openocd_xlspike.cfg`: Nuclei internal use only. OpenOCD configuration for xlspike simulation, not for general use

* Header Files (`Include/`)
  - `nuclei_sdk_hal.h`: Hardware abstraction layer interface
    - Defines debug UART (UART0)
    - Configures debug output or suppress debug output via `NMSIS_DISABLE_DEBUG`
  - `board_nuclei_fpga_eval.h`: Board specific header file for peripheral access if needed

* Linker Scripts (`Source/GCC/` and `Source/IAR/`)
  - `Source/GCC`: Linker Scripts for GCC/Clang toolchain
  - `Source/IAR`: Linker Scripts for IAR toolchain
  - Support for multiple download modes in GCC/Clang toolchain:
    - `gcc_evalsoc_ilm.ld`: code placed in ilm, data placed in dlm
    - `gcc_evalsoc_flash.ld`: code and data in flash, but code will be copied to ilm, data will be copied to dlm when running
    - `gcc_evalsoc_flashxip.ld`: code and data in flash, but code will still in flash, data will be copied to dlm when running
    - `gcc_evalsoc_ddr.ld`: code and data all placed in ddr
    - `gcc_evalsoc_sram.ld`: code and data all placed in sram
  - Support for multiple run modes in IAR toolchain:
    - `flash` download mode is not supported

### SoC Support (`Common/`)

#### Core Definition Files

* `evalsoc.svd`: System View Description file, provided by SoC vendor
  - Peripheral register definitions
  - Interrupt configurations
  - Memory map details

* `npk.yml`: SoC Support Package Configuration File for [NPK][2]

#### Include Files (`Common/Include/`)

* `cpufeature.h`: Nuclei RISC-V CPU feature header file
  - This file is generated by `nuclei_gen` tool
  - Used by `evalsoc.h` to define CPU feature macros used in NMSIS Core header files

* `evalsoc.h`: Core SoC definitions
  - Base addresses for peripherals
  - Interrupt definitions
  - Nuclei RISC-V CPU feature macros
  - You can customize this file to add more SoC definitions

* `evalsoc_uart.h`: UART driver interface

* `system_evalsoc.h`: System configuration
  - Clock initialization
  - Core initialization routines
  - System frequency setup
  - Interrupt(ECLIC/PLIC/CLINT) and Exception API

* `nuclei_sdk_soc.h`: SDK SoC common header file
  - Includes all peripheral headers
  - Common definitions for the SoC
  - Include `evalsoc.h`

#### Source Files (`Common/Source/`)

* Startup/Interrupt and Exception Code
  - Startup Code:
    - GCC/Clang version: `GCC/startup_evalsoc.S`
    - IAR version: `IAR/startup.S` and `IAR/startup_evalsoc.c`
  - Interrupt and Exception Code:
    - GCC/Clang version: M-Mode -> `GCC/intexc_evalsoc.S`, S-Mode -> `GCC/intexc_evalsoc_s.S`
    - IAR version: M-Mode -> `IAR/intexc_evalsoc.S`, S-Mode -> `IAR/intexc_evalsoc_s.S`

* System Configuration Code
  - `evalsoc_common.c`: get soc frequency via timer freq, and delay function and etc,
    which can be deleted if not needed
  - `system_evalsoc.c`: template code for system configuration,
    it will do premain initialization, smp bringup, cache initialization, interrupt and exception initialization,
    uart initialization and print banner, you can customize it as needed

* Driver Implementations(`Drivers`)
  - UART driver: `evalsoc_uart.c`

* Standard C Library Stub Code(`Stubs`)
  - Newlib stubs: `Stubs/newlib`
  - IAR DLib stubs: `Stubs/iardlib`
  - Nuclei C Runtime Library(libncrt) stubs: `Stubs/libncrt`
  - You only need one of them depending on your which c library you are using

### Build Configuration

* `build.mk`: Main build rules for the SoC
  - CPU ARCH related compiler flags such as `march`, `mabi` and `mtune`
  - Include paths
  - Source files
  - Support code if you have qemu or other simulators supported

* `cpufeature.mk`: CPU extension configuration
  - Select which CPU Core you are using, see https://doc.nucleisys.com/nuclei_sdk/develop/buildsystem.html#develop-buildsystem-var-core
  - Select which CPU extensions you are using, see https://doc.nucleisys.com/nuclei_sdk/develop/buildsystem.html#arch-ext
  - Used by `build.mk`

* `runmode.mk`: Nuclei internal use only.
  - Make variables to control ilm/dlm/icache/dcache on/off mode
  - Make variables to control Nuclei CPU features such as eclic/plic/tee/smpu/cidu present or not
  - **WARNING**: This is not recommended for general use, it is only for Nuclei internal use

[1]: https://doc.nucleisys.com/nmsis/core/core_templates.html
[2]: https://doc.nucleisys.com/nuclei_tools/ide/npkoverview.html
[3]: https://nucleisys.com/developboard.php#debuggerkit
[4]: https://doc.nucleisys.com/nuclei_sdk/design/soc/evalsoc.html