关于各分支功能介绍 About each branch feature

[fanghuaqi]

请关注最新的issue评论，这里的文字说明可能不是最新版本，以具体代码为准

请注意 本issue与其他issue会经常更新，请点击上面的 edited 来获知最新的修改的变更

Note

点击这里还可以看到更多 Nuclei Linux SDK使用的各种技巧和场景的文章，持续不断更新完善中。

中文介绍

截止到2025.05.19起更新的代码，分支特性说明如下：

• 2025.05.19, 增加_v3系列分支，切换到2025.02-gcc14工具链，未来弃用其他分支: 关于各分支功能介绍 About each branch feature #2 (comment)
• 2024.12.06: 关于各分支功能介绍 About each branch feature #2 (comment)

主要支持如下SoC:

• demosoc: 比较早版本的评估用的SoC，不带有CPU IREGION特性，已经弃用，不再支持。
• evalsoc: 目前最新的评估用的SoC，带CPU IREGION特性，演进了两个版本
  • evalsoc v1: DDR Base为0xA0000000, 默认提供的FPGA Soft CPU Core Frequency 通常是 100MHz 或者 50Mhz，不再支持
  • evalsoc v2: DDR Base为0x80000000, 默认提供的FPGA Soft CPU Core Frequency 通常是 50Mhz, 2023.07引入作为evalsoc v1的替代。
  • 最新的 900 评估bitstream都是采用的evalsoc v2

分支说明

请注意：切换分支或者切换启动模式(sd/flash), 需要清理 work目录，删掉或者重命名，且切换分支的时候，需要同时更新submodule的代码

请注意: 如果你打算在你自己的SOC上bringup Linux环境，请先阅读我们准备好的bringup建议 #21

目前活跃开发的分支为 dev_nuclei_5.10/6.1/6.6/6.9/6.12_v3: 主要针对最新的900 CPU的FPGA evalsoc进行适配和优化。

提醒: 后续我们将只积极维护 _v3 分支，其他分支不再积极维护，其他特性功能我们也将逐步迁移到 2025.02-gcc14的工具链上开发

提醒: 目前 _v3 分支使用的是开发中的预编译好的2025.02 gcc14 glibc工具链，工具链的信息记录在 buildroot_initramfs_*_config文件中。

提醒: 计划使用 dev_nuclei_next / dev_nuclei_5.10分支的， 建议直接使用 dev_nuclei_5.10_v3 分支

提醒: 关于默认的CPU/Peripheral/Timer频率以选中的SoC中对应的dts(如nuclei_rv64imafdc.dts)和build.mk配置为准。

提醒: 请根据你当前拿到的bitstream的CPU版本以及CPU主频来选择分支，切换到对应分支，并确保代码是最新的，然后检查并修改对应的dts或者build.mk来满足你的bitstream的要求，再进行代码的构建。

以下是各个分支的情况说明

Note

下面这些分支是活跃维护分支

目前这些活跃分支都已经切到 2025.02-gcc14的工具链

• dev_nuclei_5.10_v3: 支持 evalsoc v2版本, 支持RV64 & RV32，用于评估 5.10 LTS内核版本
• dev_nuclei_6.1_v3: 支持 evalsoc v2版本, 支持RV64 & RV32，用于评估 6.1 LTS内核版本
• dev_nuclei_6.6_v3: 默认分支, 支持 evalsoc v2版本, 支持RV64 & RV32，用于评估 6.6 LTS内核版本
• dev_nuclei_6.9_v3: 支持 evalsoc v2版本, 支持RV64 & RV32，用于评估 6.9内核版本（这是非LTS版本）
• dev_nuclei_6.12_v3: 支持 evalsoc v2版本, 支持RV64 & RV32，用于评估 6.12 LTS内核版本

---

下面这些分支是一些特殊功能的分支，相对功能会复杂一些，请注意使用。
下面绝大部分都只在 CORE=ux900fd BOOT_MODE=sd的场景下进行了验证，请注意！

• dev_nuclei_6.6_v3_rt: 支持evalsoc v2版本，支持RV64 & RV32，用于评估 6.6 LTS内核 + PREEMPT_RT Patch 的内核版本
• dev_nuclei_6.6_v3_customsoc: 不支持Nuclei Qemu，支持Nuclei内部做的一个参考子系统，用于开发子系统中各种IP驱动(Uboot/Kernel)支持，支持的驱动参见dts，采用 freeloader 加载并引导 uboot-spl，然后uboot-spl加载its格式 opensbi + uboot的镜像并引导，然后uboot引导 kernel+rootfs its格式镜像, 只验证了rv64imafdc + SD启动模式，不建议以这个为开始，建议使用 dev_nuclei_6.6_v3 作为起始点移植，然后熟悉环境后，迁移到这个分支
• dev_nuclei_6.6_v3_optee: 支持evalsoc v2版本，但是需要硬件支持TEE + Worldguard(可选), 本分支用于验证OpTEE在6.6内核上的功能，详细参见 https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_6.6_v3_optee/optee#readme
• dev_nuclei_6.6_v3_hsm: 不支持Nuclei Qemu，支持Nuclei内部做的一个HSM + Linux参考子系统，用于验证 HSM + OpTEE安全启动流程，只验证了rv64imafdc + SD启动模式，详细流程参见 https://github.com/Nuclei-Software/nuclei-linux-sdk/blob/dev_nuclei_6.6_v3_hsm/conf/evalsoc/Nuclei_HSM_Secure_Boot.md

---

Caution

下面这些分支将不会积极维护

• dev_nuclei_next: 支持SD卡启动和Flash启动, 请切换到 dev_nuclei_5.10_v2 分支。
  • 支持demosoc 和 evalsoc v1，基于Kernel 5.10, 支持RV64
  • 从flash启动，并借助sd卡启动linux，freeloader整合了opensbi+uboot，sd卡加载kernel+rootfs+dtb
  • 从flash直接启动，不需要依赖sd卡，freeloader整合了opensbi+uboot+kernel+rootfs+dtb（对spiflash大小有要求>=8M），也可以在uboot阶段打断启动后从SD卡启动（运行 run distro_bootcmd）
• feature/fsl: 用于评估FSL91030M 开发板，使用参见 https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/feature/fsl/conf/fsl91030m
• dev_nuclei_keystone: 主要用于评估Keystone TEE相关的方案，基于 Kernel 5.10, 支持RV64
• dev_nuclei_penglai: 主要用于评估Penglai TEE相关的方案，基于 Kernel 5.10, 支持RV64
• dev_nuclei_5.10 & dev_nuclei_6.1: 分别用于评估最新的5.10 或者 6.1 LTS版本内核，支持 evalsoc v1版本, 支持RV64
• dev_nuclei_5.10_v2 & dev_nuclei_6.1_v2: 分别用于评估最新的5.10 或者 6.1 LTS版本内核，支持 evalsoc v2版本, 支持RV64 & RV32
• dev_nuclei_6.6_v2: 用于评估6.6版本的内核，目前dts里面默认带上了 _zicbom_svpbmt 扩展(请注意)， 采用我们最新的预编译的gcc13 glibc 2.38的工具链(开发中)，支持evalsoc v2, 支持rv32 & rv64, 支持 Svnapot/Svpbmt/Zbb/Zicbom/Zicboz/Vector 特性，demosoc支持已经被删除了
• dev_nuclei_6.9_v2: 用于评估6.9版本的内核，采用我们最新的预编译的gcc13 glibc 2.38的工具链(开发中)，支持evalsoc v2, 支持rv32 & rv64, 支持 Svnapot/Svpbmt/Zbb/Zicbom/Zicboz/Vector 特性，demosoc支持已经被删除了
• dev_nuclei_6.6_v2_customsoc: 基于6.6内核增加对Nuclei SoC IP Driver的支持和测试（持续增加中），测试使用本地参考平台，支持位于 conf/customsoc, 修改的内核位于 dev_nuclei_6.6.y分支
• dev_nuclei_6.6_v2_android: 基于Android Linux Kernel 6.6版本针对 CORE=ux900fd 进行的移植和适配，用于测试AOSP的Bringup，详细使用参见该分支下的 conf/evalsoc/README.md
• feature/optee_5.10: 主要用于评估OpTEE 相关的方案，基于Kernel 5.10, , 支持RV64, 参见 Introduce OpTEE complete solution for RISC-V and looking for how to contribute it OP-TEE/optee_os#6173 和 Quick steps to evaluate optee solution on nuclei qemu #13
• feature/optee_5.10_wg: 主要用于评估OpTEE 相关的方案，基于Kernel 5.10, , 支持RV64, 同时需要CPU硬件支持更多安全特性
• dev_nuclei_6.4_v2_rt: 基于Linux 6.4内核 + RT Patches用于评估实时内核
• feature/5.10_ccm: 基于 5.10内核，增加了Linux CCM的cache 管理的适配， 代码适配，可以boot，但是需要带DMA的设备来测试这个
• dev_nuclei_5.10_v2_64baddr: 基于 5.10内核，用于测试ddr基地址大于 32位，uboot加载镜像采用FIT格式来解决之前方式只能加载32位地址空间内的镜像问题，这个分支只适配了 ux900fd - sd 模式
• dev_nuclei_5.10_v2_fit: 基于 5.10内核，用于测试ddr基地址大于 32位，uboot加载镜像采用FIT格式来解决之前方式只能加载32位地址空间内的镜像问题
• dev_nuclei_6.1_v2_fit: 基于 6.1内核，用于测试ddr基地址大于 32位，uboot加载镜像采用FIT格式来解决之前方式只能加载32位地址空间内的镜像问题
• dev_nuclei_6.6_v2_fit: 基于 6.6内核，用于测试ddr基地址大于 32位，uboot加载镜像采用FIT格式来解决之前方式只能加载32位地址空间内的镜像问题

[fanghuaqi]

Please pay attention to the latest issue comments, the text descriptions here may not be the latest version, refer to the specific code for accuracy.

Introduction

As of May 2025, the updated code features are as follows:

• 2025.05.19: 关于各分支功能介绍 About each branch feature #2 (comment)
• 2024.12.06: 关于各分支功能介绍 About each branch feature #2 (comment)

Mainly supports the following SoCs:

• demosoc: An earlier evaluation SoC without CPU IREGION features, now deprecated and removed.

• evalsoc: The latest evaluation SoC with CPU IREGION features, evolved in two versions, with DDR base at 0xA0000000 (v1) and 0x80000000 (v2) respectively, v1 support removed.

Branches introduction:

Please note: When switching branches or switching boot modes (sd/flash), you need to clean the work directory, delete or rename it. Also when switching branches, you need to update the submodule code at the same time.
Please note: If you plan to bringup a Linux environment on your own SOC, please read our prepared bringup advice #21 first

Currently, actively development branches are dev_nuclei_5.10/6.1/6.6/6.12_v3

Note

The following branches are actively maintained branches

Currently, these active branches have all switched to the 2025.02 - gcc14 toolchain.

• dev_nuclei_5.10_v3: Supports the evalsoc v2 version, supports RV64 & RV32, and is used to evaluate the 5.10 LTS kernel version.
• dev_nuclei_6.1_v3: Supports the evalsoc v2 version, supports RV64 & RV32, and is used to evaluate the 6.1 LTS kernel version.
• dev_nuclei_6.6_v3: Default branch, supports the evalsoc v2 version, supports RV64 & RV32, and is used to evaluate the 6.6 LTS kernel version.
• dev_nuclei_6.9_v3: Supports the evalsoc v2 version, supports RV64 & RV32, and is used to evaluate the 6.9 kernel version (this is a non - LTS version).
• dev_nuclei_6.12_v3: Supports the evalsoc v2 version, supports RV64 & RV32, and is used to evaluate the 6.12 LTS kernel version.

---

The following branches are for special functions and their functions are relatively more complex. Please pay attention when using them.
Most of the following branches have only been verified in the scenario of CORE=ux900fd BOOT_MODE=sd. Please take care！

• dev_nuclei_6.6_v3_rt: Supports evalsoc v2 version, RV64 & RV32, and is used to evaluate the kernel version of 6.6 LTS kernel + PREEMPT_RT Patch.
• dev_nuclei_6.6_v3_customsoc: Supports a reference subsystem developed internally by Nuclei. It is used to develop the support for various IP drivers (Uboot/Kernel) in the subsystem. For the supported drivers, please refer to dts. It uses freeloader to load and boot uboot-spl, then uboot-spl loads and boots the opensbi + uboot image in its format, and then uboot boots the kernel+rootfs image in its format. Only the rv64imafdc + SD boot mode has been verified. It is not recommended to start with this. It is recommended to use dev_nuclei_6.6_v3 as the starting point for transplantation. After getting familiar with the environment, migrate to this branch.
• dev_nuclei_6.6_v3_optee: Supports the evalsoc v2 version, but requires hardware support for TEE + Worldguard (optional). This branch is used to verify the functionality of OpTEE on the 6.6 kernel, refer to https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_6.6_v3_optee/optee#readme
• dev_nuclei_6.6_v3_hsm: Supports an HSM + Linux reference subsystem developed internally by Nuclei, and is used to verify the HSM + OpTEE secure boot process. For the detailed process, please refer to https://github.com/Nuclei-Software/nuclei-linux-sdk/blob/dev_nuclei_6.6_v3_hsm/conf/evalsoc/Nuclei_HSM_Secure_Boot.md

---

Caution

The following branches will not be actively maintained.

• dev_nuclei_next: supports SD card boot and Flash boot

  • Supports demosoc and evalsoc v1, based on Kernel 5.10(RV64 only)

  • Boots from flash, and borrows SD card to boot Linux, freeloader integrates opensbi+uboot, SD card loads kernel+rootfs+dtb

  • Boots directly from flash, no dependency on SD card, freeloader integrates opensbi+uboot+kernel+rootfs+dtb (requires flash >=8M), or can boot from SD card in uboot (run run distro_bootcmd)

• feature/fsl: For evaluation of FSL91030M board, see usage at https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/feature/fsl/conf/fsl91030m

• dev_nuclei_keystone: Mainly for evaluation of Keystone TEE related solutions, based on Kernel 5.10(RV64 only)

• dev_nuclei_penglai: Mainly for evaluation of Penglai TEE related solutions, based on Kernel 5.10(RV64 only)

• dev_nuclei_5.10 & dev_nuclei_6.1: For evaluation of latest 5.10 or 6.1 LTS kernel versions, supports evalsoc v1(RV64 only)

• dev_nuclei_5.10_v2 & dev_nuclei_6.1_v2: For evaluation of latest 5.10 or 6.1 LTS kernel versions, supports evalsoc v2(RV32&RV64)

• dev_nuclei_6.6_v2: For evaluation of linux kernel 6.6，which use our latest gcc13 glibc 2.38 toolchain(WIP)，support evalsoc v2, support rv32 & rv64, support Svnapot/Svpbmt/Zbb/Zicbom/Zicboz/Vector extension，demosoc removed and dropped

• dev_nuclei_6.9_v2: For evaluation of linux kernel 6.9，which use our latest gcc13 glibc 2.38 toolchain(WIP)，support evalsoc v2, support rv32 & rv64, support Svnapot/Svpbmt/Zbb/Zicbom/Zicboz/Vector extension，demosoc removed and dropped

• dev_nuclei_6.6_v2_customsoc: Built upon the 6.6 kernel, this version includes support for Nuclei SoC IP Driver, with ongoing additions and testing. Local reference platforms are used for testing, and it supports configurations located in conf/customsoc. The modified kernel is located in the dev_nuclei_6.6.y branch.

• dev_nuclei_6.6_v2_android: Based on the Android Linux Kernel version 6.6, the porting and adaptation for CORE=ux900fd has been conducted to test the Bringup of AOSP. For detailed usage, please refer to the README.md in the conf/evalsoc branch.

• feature/optee_5.10: Mainly for evaluation of OpTEE solutions, based on Kernel 5.10(RV64 only), see Introduce OpTEE complete solution for RISC-V and looking for how to contribute it OP-TEE/optee_os#6173 and Quick steps to evaluate optee solution on nuclei qemu #13

• feature/optee_5.10_wg: Mainly for evaluation of OpTEE solutions, based on Kernel 5.10(RV64 only), requires more CPU security features

• dev_nuclei_6.4_v2_rt: Based on Linux 6.4 Kernel + RT Patches used to evaluate Realtime feature

• feature/5.10_ccm: Based on the 5.10 kernel, added the adaptation of Linux CCM cache management, code adaptation, can boot, but need a device with DMA to test this

• dev_nuclei_5.10_v2_64baddr: Based on the 5.10 kernel, used to test the ddr base address greater than 32 bits, uboot loads the image using FIT formatto solve the problem that the previous method can only load images in the 32-bit address space, this branch only adapts the ux900fd - sd mode

• dev_nuclei_5 10_v2_fit: Based on the 5.10 kernel, used to test the ddr base address is greater than 32 bits, uboot loads the image using FIT format to solve the problem that the previous method can only load the image in the 32-bit address space

• dev_nuclei_6 1_v2_fit: Based on the 6.1 kernel, used to test the ddr base address is greater than 32 bits, uboot loads the image using FIT format to solve the problem that the previous method can only load the image in the 32-bit address space

• dev_nuclei_6 6_v2_fit: Based on the 6.6 kernel, used to test the ddr base address is greater than 32 bits, uboot loads the image using FIT format to solve the problem that the previous method can only load the image in the 32-bit address space

[fanghuaqi]

The documentation can be found in each branch's README.md, which can be reviewed online.

[fanghuaqi]

We have introduced OpTEE support, please check this issue OP-TEE/optee_os#6173

The related branches:

• feature/optee_5.10 : https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/feature/optee_5.10

• feature/optee_5.10_wg : https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/feature/optee_5.10_wg

feature/optee_5.10_wg branch introduce the support with world-guard and secure mode feature of Nuclei CPU. Currently only run on hardware, no qemu emulation support.

[fanghuaqi]

Since 2023.07, the ddr base address of our fpga emulation platform for 900 series changed from 0xA0000000 to 0x80000000, so we are able to have totally 2GB DDR RAM to use, instead of 1.5G.

If you want to try that features, please use these branches:

• dev_nuclei_5.10_v2 : https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_5.10_v2

• dev_nuclei_6.1_v2 : https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_6.1_v2

• These two branches required a new version of Nuclei QEMU > 2022.12, please contact with our AE to get it.
• These two branches are for Linux Kernel 5.10 LTS version and 6.1 LTS version.

There are also branches without _v2 naming in it, it is used for old DDR base is 0xA0000000

[fanghuaqi]

We have just introduced with no-mmu linux support for riscv64 processors.

You can evaluate it using Nuclei Qemu 2023.10 downloaded from https://www.nucleisys.com/upload/files/toochain/qemu/nuclei-qemu-2023.10-linux-x64.tar.gz

Just extract it, and add its binary path to existing system PATH.

You can find this feature in branch: https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_6.1_nommu

The freeloader will consist with loader, dts and kernel binary, when you clone this repo, and switch to this branch, and update the submodule, then you can evaluate this on qemu or hardware.

export PATH=/path/to/qemu/bin:$PATH
# choose rv64imafdc
# clean previous build if existed
make CORE=ux900fd clean
# build freeloader is enough, no need to build boot images, sd card is not needed
# bitstream with 50MHz CPU is expected by default
make CORE=ux900fd freeloader
# run on qemu
make CORE=ux900fd run_qemu
# upload to hardware board, hardware need to be power on and jtag connected
# boot need a few minutes depended on cpu frequency
make CORE=ux900fd upload_freeloader

Sample output on qemu is attached here:
rv64imafdc_nommu_linux_bootlog.txt

[matthewgui]

We have just introduced with preempt_rt linux support for riscv64 processors.

You can evaluate it using Nuclei Qemu 2023.10 downloaded from https://www.nucleisys.com/upload/files/toochain/qemu/nuclei-qemu-2023.10-linux-x64.tar.gz

Just extract it, and add its binary path to existing system PATH.

You can find this feature in branch: https://github.com/Nuclei-Software/nuclei-linux-sdk/tree/dev_nuclei_6.4_v2_rt

The freeloader will consist with loader, dts and kernel binary, when you clone this repo, and switch to this branch, and update the submodule, then you can evaluate this on qemu or hardware.

export PATH=/path/to/qemu/bin:$PATH
# choose rv64imafdc
# clean previous build if existed
make CORE=ux900fd clean
# build freeloader is enough, no need to build boot images, sd card is not needed
# bitstream with 50MHz CPU is expected by default
make CORE=ux900fd freeloader
# run on qemu
make CORE=ux900fd run_qemu
# upload to hardware board, hardware need to be power on and jtag connected
# boot need a few minutes depended on cpu frequency
make CORE=ux900fd upload_freeloader

Sample output on qemu is attached here:
rv64imafdc_rt_linux_bootlog.txt

cyclictest program which we use to test rtlinux, is built from rt-test source code,

rt-test git source : git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git

here is our rv64fd binary built from rt-test 2.0 ,numa library is master branch
cyclictest.gz

[fanghuaqi]

We just introduced support of Linux Kernel 6.6 in branch dev_nuclei_6.6_v2, which is using prebuilt gcc 13 + glibc 2.38 toolchain, the buildroot/uboot are also upgraded to latest stable branch.

The riscv features linux kernel 6.6 supported:

[fanghuaqi]

We introduced dev_nuclei_6.6_v2_customsoc branch, mainly used to demonstrate our Nuclei SoC IP linux driver code and how to use it.