docs: add README for Nuclei 100 Series Core Device Templates

Author: fanghuaqi

SoC/evalsoc/README.md

@@ -0,0 +1,119 @@
+# Nuclei 100 Series Core Device Templates
+
+The [**evalsoc**][4] implementation in Nuclei N100 SDK serves as a **latest reference implementation** using Nuclei 100 series CPU.
+
+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 100 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]
+
+* 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
+  - Provide sample linker script in GCC/Clang toolchain:
+    - `gcc_evalsoc_sram.ld`: code and data all placed in sram
+  - Provide sample linker script in IAR toolchain:
+    - `iar_evalsoc_sram.icf`: code and data all placed in sram
+
+### 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(IRQC) 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`
+    - IAR version: M-Mode -> `IAR/intexc_evalsoc.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, 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_n100_sdk/develop/buildsystem.html#develop-buildsystem-var-core
+  - Select which CPU extensions you are using, see https://doc.nucleisys.com/nuclei_n100_sdk/develop/buildsystem.html#arch-ext
+  - Used by `build.mk`
+
+
+[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_n100_sdk/design/soc/evalsoc.html