Contributing

Contributing to Nuclei SDK project is always welcome.

You can always do a lot of things to help Nuclei SDK project improve and grow stronger.

Port your Nuclei SoC into Nuclei SDK

If you want to port you Nuclei Processor Core based Board to Nuclei SDK, you need to follow these steps:

Assume your SoC name is ncstar, based on Nuclei core n307, and RISCV_ARCH is rv32imafc, RISCV_ABI is ilp32f, and you made a new board called ncstar_eval, and this SoC only support FlashXIP download mode.

Make sure the SoC name and Board name used in this Nuclei SDK is all in lowercase.

  1. Create a folder named ncstar under SoC directory.

    • Create folder named Board and Common under ncstar

    • Create directory structure under ncstar/Common like below:

      <ncstar/Common>
      ├── Include
      │   ├── peripheral_or_device_headers.h
      │   ├── ......
      │   ├── ncstar.h
      │   ├── nuclei_sdk_soc.h
      │   └── system_ncstar.h
      └── Source
          ├── Drivers
          │   ├── peripheral_or_device_sources.c
          │   └── ......
          ├── GCC
          │   ├── intexc_ncstar.S
          │   └── startup_ncstar.S
          ├── Stubs
          │   ├── close.c
          │   ├── fstat.c
          │   ├── gettimeofday.c
          │   ├── isatty.c
          │   ├── lseek.c
          │   ├── read.c
          │   ├── sbrk.c
          │   ├── stub.h
          │   └── write.c
          ├── ncstar_soc.c
          └── system_ncstar.c
      

      Note

      • The directory structure is based on the NMSIS device template, please refer to https://doc.nucleisys.com/nmsis/core/core_templates.html

      • The folder names must be exactly the same as the directory structure showed

      • peripheral_or_device_sources.c means the SoC peripheral driver source code files, such as uart, gpio, i2c, spi driver sources, usually get from the SoC firmware library, it should be placed in Drivers folder.

      • peripheral_or_device_headers.h means the SoC peripheral driver header files, such as uart, gpio, i2c, spi driver headers, usually get from the SoC firmware library, it should be placed in Include folder.

      • The Stubs folder contains the stub code files for newlib c library porting code, mainly _write, _read, _sbrk stub function

      • The GCC folder contains startup and exeception/interrupt assemble code, if your board share the same linker script files, you can also put link script files here, the linker script files name rules can refer to previously supported hbird SoC.

      • The nuclei_sdk_soc.h file is very important, it is a Nuclei SoC Header file used by common application which can run accoss different SoC, it should include the SoC device header file ncstar.h

    • Create directory structure under ncstar/Board like below:

      <ncstar/Board>
      └── ncstar_eval
          ├── Include
          │   ├── ncstar_eval.h
          │   └── nuclei_sdk_hal.h
          ├── openocd_ncstar.cfg
          └── Source
              ├── GCC
              │   └── gcc_ncstar_flashxip.ld
              └── ncstar_eval.c
      

      Note

      • The ncstar_eval is the board folder name, if you have a new board, you can create a new folder in the same level

      • Include folder contains the board related header files

      • Source folder contains the board related source files

      • GCC folder is optional, if your linker script for the board is different to the SoC, you need to put your linker script here

      • openocd_ncstar.cfg file is the board related openocd debug configuration file

      • ncstar_eval.h file contains board related definition or APIs and also include the SoC header file, you can refer to previously supported board such as hbird_eval

      • nuclei_sdk_hal.h is very important, it includes the ncstar_eval.h header file. This file is used in application as entry header file to access board and SoC resources.

  2. Create Makefiles related to ncstar in Nuclei SDK build system

    • Create Build/Makefile.soc.ncstar, the file content should be like this:

      BOARD ?= ncstar_eval
      
      # override DOWNLOAD and CORE variable for NCSTAR SoC
      # even though it was set with a command argument
      override CORE := n307
      override DOWNLOAD := flashxip
      
      NCSTAR_SDK_SOC_BOARD=$(NUCLEI_SDK_SOC)/Board/$(BOARD)
      NCSTAR_SDK_SOC_COMMON=$(NUCLEI_SDK_SOC)/Common
      
      #no ilm on NCSTAR SoC
      LINKER_SCRIPT ?= $(NCSTAR_SDK_SOC_BOARD)/Source/GCC/gcc_ncstar_flashxip.ld
      OPENOCD_CFG ?= $(NCSTAR_SDK_SOC_BOARD)/openocd_ncstar.cfg
      
      RISCV_ARCH ?= rv32imafc
      RISCV_ABI ?= ilp32f
      
    • Create Makefile.files.ncstar, the file content should be like this:

      INCDIRS += $(NCSTAR_SDK_SOC_COMMON)/Include
      
      C_SRCDIRS += $(NCSTAR_SDK_SOC_COMMON)/Source \
                   $(NCSTAR_SDK_SOC_COMMON)/Source/Drivers \
                   $(NCSTAR_SDK_SOC_COMMON)/Source/Stubs
      
      ASM_SRCS += $(NCSTAR_SDK_SOC_COMMON)/Source/GCC/startup_ncstar.S \
                   $(NCSTAR_SDK_SOC_COMMON)/Source/GCC/intexc_ncstar.S
      
      # Add extra board related source files and header files
      VALID_NCSTAR_SDK_SOC_BOARD=$(wildcard $(NCSTAR_SDK_SOC_BOARD))
      ifneq ($(VALID_NCSTAR_SDK_SOC_BOARD),)
      INCDIRS += $(VALID_NCSTAR_SDK_SOC_BOARD)/Include
      C_SRCDIRS += $(VALID_NCSTAR_SDK_SOC_BOARD)/Source
      endif
      
  3. If you have setup the source code and build system correctly, then you can test your SoC using the common applications, e.g.

    # Test helloworld application for ncstar_eval board
    ## cd to helloworld application directory
    cd application/baremetal/helloworld
    ## clean and build helloworld application for ncstar_eval board
    make SOC=ncstar BOARD=ncstar_eval clean all
    ## connect your board to PC and install jtag driver, open UART terminal
    ## set baudrate to 115200bps and then upload the built application
    ## to the ncstar_eval board using openocd, and you can check the
    ## run messsage in UART terminal
    make SOC=ncstar BOARD=ncstar_eval upload
    

Note

  • You can always refer to previously supported SoCs for reference, such as the hbird and gd32vf103 SoC.

  • The hbird SoC is a FPGA based evaluation platform, it have ilm and dlm, so it support three download modes

  • The gd32vf103 SoC is a real silicon chip, it only have RAM and onchip flash, it only support FlashXIP mode.

  • The nuclei_sdk_soc.h must be created in SoC include directory, it must include the device header file <device>.h and SoC firmware library header files.

  • The nuclei_sdk_hal.h must be created in Board include directory, it must include nuclei_sdk_soc.h and board related header files.

Submit your issue

If you find any issue related to Nuclei SDK project, you can open an issue in https://github.com/Nuclei-Software/nuclei-sdk/issues

Submit your pull request

If you want to contribute your code to Nuclei SDK project, you can open an pull request in https://github.com/Nuclei-Software/nuclei-sdk/pulls

Regarding to code style, please refer to Code Style.

Git commit guide

If you want to contribute your code, make sure you follow the guidance of git commit, see here https://chris.beams.io/posts/git-commit/ for details

  • Use the present tense (“Add feature” not “Added feature”)

  • Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)

  • Limit the first line to 80 characters or less

  • Refer github issues and pull requests liberally using #

  • Write the commit message with an category name and colon:

    • soc: changes related to soc

    • board: changes related to board support packages

    • nmsis: changes related to NMSIS

    • build: changes releated to build system

    • library: changes related to libraries

    • rtos: changes related to rtoses

    • test: changes related to test cases

    • doc: changes related to documentation

    • ci: changes related to ci environment

    • application: changes related to applications

    • misc: changes not categorized

    • env: changes related to environment