Build System based on Makefile

Nuclei SDK’s build system is based on Makefile, user can build, run ordebug application in Windows and Linux.

Makefile Structure

Nuclei SDK’s Makefiles mainly placed in <NUCLEI_SDK_ROOT>/Build directory and an extra Makefile located in <NUCLEI_SDK_ROOT>/Makefile.

This extra <NUCLEI_SDK_ROOT>/Makefile introduce a new Make variable called PROGRAM to provide the ability to build or run application in <NUCLEI_SDK_ROOT>.

For example, if you want to rebuild and upload application application/baremetal/timer_test, you can run make PROGRAM=application/baremetal/timer_test clean upload to achieve it.

The <NUCLEI_SDK_ROOT>/Build directory content list as below:

gmsl/
Makefile.base
Makefile.conf
Makefile.core
Makefile.files
Makefile.files.gd32vf103
Makefile.files.hbird
Makefile.global  -> Created by user
Makefile.misc
Makefile.rtos
Makefile.rtos.FreeRTOS
Makefile.rtos.UCOSII
Makefile.rtos.RTThread
Makefile.rules
Makefile.soc
Makefile.soc.gd32vf103
Makefile.soc.hbird

The file or directory is used explained as below:

Makefile.base

This Makefile.base file is used as Nuclei SDK build system entry file, application’s Makefile need to include this file to use all the features of Nuclei SDK build system.

It will expose Make variables or options such as BOARD or SOC passed by make command, click Makefile variables passed by make command to learn more.

This file will include optional Makefile.global and Makefile.local which allow user to set custom global Makefile configurations and local application Makefile configurations.

This file will include the following makefiles:

• gmsl: additional library functions provided via gmsl

• Makefile.misc: misc functions and OS check helpers

• Makefile.conf: main Makefile configuration entry

• Makefile.rules: make rules of this build system

gmsl

The gmsl directory consist of the GNU Make Standard Library (GMSL), which is an a library of functions to be used with GNU Make’s $(call) that provides functionality not available in standard GNU Make.

We use this gmsl tool to make sure we help us achieve some linux command which is only supported in Linux.

Makefile.misc

This Makefile.misc file mainly provide these functions:

• Define get_csrcs, get_asmsrcs, get_cxxsrcs and check_item_exist make functions

  • get_csrcs: Function to get *.c or *.C source files from a list of directories, no ability to do recursive match. e.g. $(call get_csrcs, csrc csrc/abc) will return c source files in csrc and csrc/abc directories.

  • get_asmsrcs: Function to get *.s or *.S source files from a list of directories, no ability to do recursive match. e.g. $(call get_asmsrcs, asmsrc asmsrc/abc) will return asm source files in asmsrc and asmsrc/abc directories.

  • get_cxxsrcs: Function to get *.cpp or *.CPP source files from a list of directories, no ability to do recursive match. e.g. $(call get_cxxsrcs, cppsrc cppsrc/abc) will return cpp source files in cppsrc and cppsrc/abc directories.

  • check_item_exist: Function to check if item existed in a set of items. e.g. $(call check_item_exist, flash, flash ilm flashxip) will check flash whether existed in flash ilm flashxip, if existed, return flash, otherwise return empty.

• Check and define OS related functions, and also a set of trace print functions.

Makefile.conf

This Makefile.conf file will define the following items:

• Toolchain related variables used during compiling

• Debug related variables

• Include Makefile.files and Makefile.rtos

• Collect all the C/C++/ASM compiling and link options

Makefile.rules

This Makefile.rules file will do the following things:

• Collect all the sources during compiling

• Define all the rules used for building, uploading and debugging

• Print help message for build system

Makefile.files

This Makefile.files file will do the following things:

• Define common C/C++/ASM source and include directories

• Define common C/C++/ASM macros

• Include Makefile.files.<SOC> which will include all the source code related to the SOC and BOARD

  • Makefile.files.gd32vf103: Used to include source code for GD32VF103 SoC

  • Makefile.files.hbird: Used to include source code for HummingBird SoC

Makefile.soc

This Makefile.soc will just include Makefile.soc.<SOC> according to the SOC makefile variable setting.

It will define the following items:

• DOWNLOAD and CORE variables

  • For HummingBird SoC, we can support all the modes defined in DOWNLOAD, and CORE list defined in Makefile.core

  • For GD32VF103 SoC, The CORE is fixed to N205, since it is a real SoC chip, and only FlashXIP download mode is supported

• Linker script used according to the DOWNLOAD mode settings

• OpenOCD debug configuration file used for the SoC and Board

• Some extra compiling or debugging options

Makefile.rtos

This Makefile.rtos will include Makefile.rtos.<RTOS> file according to our RTOS variable.

If no RTOS is chosen, then RTOS code will not be included during compiling, user will develop baremetal application.

If FreeRTOS, UCOSII or RTThread RTOS is chosen, then FreeRTOS UCOSII, or RTThread source code will be included during compiling, and extra compiler option -DRTOS_$(RTOS_UPPER) will be passed, then user can develop RTOS application.

For example, if FreeRTOS is selected, then -DRTOS_FREERTOS compiler option will be passed.

• Makefile.rtos.FreeRTOS: Include FreeRTOS related source code and header directories

• Makefile.rtos.UCOSII: Include UCOSII related source code and header directories

• Makefile.rtos.RTThread: Include RTThread related source code and header directories

Makefile.core

This Makefile.core is used to define the RISC-V ARCH and ABI used during compiling of the CORE list supported.

If you want to add a new CORE, you need to add a new line before SUPPORTED_CORES, and append the new CORE to SUPPORTED_CORES.

For example, if you want to add a new CORE called n308, and the n308’s ARCH and ABI are rv32imafdc and ilp32d, then you can add a new line like this N308_CORE_ARCH_ABI = rv32imafdc ilp32d, and append n308 to SUPPORTED_CORES like this SUPPORTED_CORES = n201 n201e n203 n203e n205 n205e n305 n307 n307fd n308 nx600

Note

• The appended new CORE need to lower-case, e.g. n308

• The new defined variable N308_CORE_ARCH_ABI need to be all upper-case.

Makefile.global

This Makefile.global file is an optional file, and will not be tracked by git, user can create own Makefile.global in <NUCLEI_SDK_ROOT>/Build directory.

In this file, user can define custom SOC, BOARD, DOWNLOAD options to overwrite the default configuration.

For example, if you will use only the GD32VF103V RV-STAR Kit, you can create the <NUCLEI_SDK_ROOT>/Build/Makefile.global as below:

SOC ?= gd32vf103
BOARD ?= gd32vf103v_rvstar
DOWNLOAD ?= flashxip

Note

• If you add above file, then you can build, run, debug application without passing SOC, BOARD and DOWNLOAD variables using make command for GD32VF103V RV-STAR Kit board, e.g.

  • Build and run application for GD32VF103V RV-STAR Kit: make run

  • Debug application for GD32VF103V RV-STAR Kit: make debug

• The GD32VF103V RV-STAR Kit only support FlashXIP download mode.

• If you create the Makefile.global like above sample code, you will also be able to use Nuclei SDK build system as usually, it will only change the default SOC, BOARD and DOWNLOAD, but you can still override the default variable using make command, such as make SOC=hbird BOARD=hbird_eval DOWNLOAD=ilm

Makefile.local

As the Makefile.global is used to override the default Makefile configurations, and the Makefile.local is used to override application level Makefile configurations, and also this file will not be tracked by git.

User can create Makefile.local file in any of the application folder, placed together with the application Makefile, for example, you can create Makefile.local in application/baremetal/helloworld to override default make configuration for this helloworld application.

If you want to change the default board for helloworld to use GD32VF103V RV-STAR Kit, you can create application/baremetal/helloworld/Makefile.local as below:

SOC ?= gd32vf103
BOARD ?= gd32vf103v_rvstar
DOWNLOAD ?= flashxip

Note

• This local make configuration will override global and default make configuration.

• If you just want to change only some applications’ makefile configuration, you can add and update Makefile.local for those applications.

Makefile targets of make command

Here is a list of the Make targets supported by Nuclei SDK Build System.

Make targets supported by Nuclei SDK Build System

target	description
help	display help message of Nuclei SDK build system
info	display selected configuration information
all	build application with selected configuration
clean	clean application with selected configuration
dasm	build and dissemble application with selected configuration
bin	build and generate application binary with selected configuration
upload	build and upload application with selected configuration
run_openocd	run openocd server with selected configuration
run_gdb	build and start gdb process with selected configuration
debug	build and debug application with selected configuration

Note

• The selected configuration is controlled by Makefile variables passed by make command

• For run_openocd and run_gdb target, if you want to change a new gdb port, you can pass the variable GDB_PORT

Makefile variables passed by make command

In Nuclei SDK build system, we exposed the following Makefile variables which can be passed via make command.

• SOC

• BOARD

• DOWNLOAD

• CORE

• SIMULATION

• GDB_PORT

• V

• SILENT

Note

• These variables can also be used and defined in application Makefile

• If you just want to fix your running board of your application, you can just define these variables in application Makefile, if defined, then you can simply use make clean, make upload or make debug, etc.

SOC

SOC variable is used to declare which SoC is used in application during compiling.

You can easily find the supported SoCs in the <NUCLEI_SDK_ROOT>/SoC directory.

Currently we support the following SoCs, see Supported SoCs.

Supported SoCs

SOC	Reference
gd32vf103	GD32VF103 SoC
hbird	HummingBird SoC

BOARD

Board variable is used to declare which Board is used in application during compiling.

The BOARD variable should match the supported boards of chosen SOC. You can easily find the supported Boards in the <NUCLEI_SDK_ROOT>/<SOC>/Board/ directory.

• Supported Boards when SOC=gd32vf103

• Supported Boards when SOC=hbird

Currently we support the following SoCs.

Supported Boards when SOC=gd32vf103

BOARD	Reference
gd32vf103v_rvstar	GD32VF103V RV-STAR Kit
gd32vf103v_eval	GD32VF103V Evaluation Kit

Supported Boards when SOC=hbird

BOARD	Reference
hbird_eval	HummingBird Evaluation Kit

Note

• If you only specify SOC variable in make command, it will use default BOARD and CORE option defined in Makefile.soc.<SOC>

DOWNLOAD

DOWNLOAD variable is used to declare the download mode of the application, currently it has these modes supported as described in table Supported download modes

Supported download modes

DOWNLOAD	Description
ilm	Program will be download into ilm/ram and run directly in ilm/ram, program will lost when poweroff
flash	Program will be download into flash, when running, program will be copied to ilm/ram and run in ilm/ram
flashxip	Program will to be download into flash and run directly in flash
ddr	Program will to be download into ddr and run directly in ddr, program will lost when poweroff

Note

• GD32VF103 SoC only support DOWNLOAD=flashxip

• HummingBird SoC support all the download modes.

• flashxip mode in HummingBird SoC is very slow due to the CORE frequency is very slow, and flash execution speed is slow

• ddr mode is introduced in release 0.2.5 of Nuclei SDK

CORE

CORE variable is used to declare the Nuclei processor core of the application.

Currently it has these cores supported as described in table Supported Nuclei Processor cores.

Supported Nuclei Processor cores

CORE	ARCH	ABI
n201	rv32iac	ilp32
n201e	rv32eac	ilp32e
n203	rv32imac	ilp32
n203e	rv32emac	ilp32e
n205	rv32imac	ilp32
n205e	rv32emac	ilp32e
n305	rv32imac	ilp32
n307	rv32imafc	ilp32f
n307fd	rv32imafdc	ilp32d
n600	rv32imac	ilp32
n600f	rv32imafc	ilp32f
n600fd	rv32imafdc	ilp32d
nx600	rv64imac	lp64
nx600f	rv64imafc	lp64f
nx600fd	rv64imafdc	lp64d
ux600	rv64imac	lp64
ux600f	rv64imafc	lp64f
ux600fd	rv64imafdc	lp64d

SIMULATION

If SIMULATION=1, it means the program is optimized for hardware simulation environment.

Currently if SIMULATION=1, it will pass compile option -DCFG_SIMULATION, application can use this CFG_SIMULATION to optimize program for hardware simulation environment.

Note

• Currently the benchmark applications in application/baremetal/benchmark used this optimization

GDB_PORT

Note

• This new variable GDB_PORT is added in Nuclei SDK since version 0.2.4

This variable is not used usually, by default the GDB_PORT variable is 3333.

If you want to change a debug gdb port for openocd and gdb when run run_openocd and run_gdb target, you can pass a new port such as 3344 to this variable.

For example, if you want to debug application using run_openocd and run_gdb and specify a different port other than 3333.

You can do it like this, take hbird_eval board for example, such as port 3344:

• Open openocd server: make SOC=hbird BOARD=hbird_eval CORE=n307 GDB_PORT=3344 run_openocd

• connect gdb with openocd server: make SOC=hbird BOARD=hbird_eval CORE=n307 GDB_PORT=3344 run_gdb

V

If V=1, it will display compiling message in verbose including compiling options.

By default, no compiling options will be displayed in make console message just to print less message and make the console message cleaner. If you want to see what compiling option is used, please pass V=1 in your make command.

SILENT

If SILENT=1, it will not display any compiling messsage.

If you don’t want to see any compiling message, you can pass SILENT=1 in your make command.

Makefile variables used only in Application Makefile

The following variables should be used in application Makefile at your demand, e.g. application/baremetal/timer_test/Makefile.

• TARGET

• NUCLEI_SDK_ROOT

• RTOS

• PFLOAT

• NEWLIB

• NOGC

TARGET

This is a necessary variable which must be defined in application Makefile.

It is used to set the name of the application, it will affect the generated target filenames.

Warning

• Please don’t put any spaces in TARGET variable

• The variable shouldn’t contain any space

# invalid case 1
TARGET ?= hello world
# invalid case 2
TARGET ?= helloworld # before this # there is a extra space

NUCLEI_SDK_ROOT

This is a necessary variable which must be defined in application Makefile.

It is used to set the path of Nuclei SDK Root, usually it should be set as relative path, but you can also set absolute path to point to Nuclei SDK.

RTOS

RTOS variable is used to choose which RTOS will be used in this application.

You can easily find the supported RTOSes in the <NUCLEI_SDK_ROOT>/OS directory.

• If RTOS is not defined, then baremetal service will be enabled with this application. See examples in application/baremetal.

• If RTOS is set the the following values, RTOS service will be enabled with this application.

  • FreeRTOS: FreeRTOS service will be enabled, extra macro RTOS_FREERTOS will be defined, you can include FreeRTOS header files now, and use FreeRTOS API, for FreeRTOS application, you need to have an FreeRTOSConfig.h header file prepared in you application. See examples in application/freertos.

  • UCOSII: UCOSII service will be enabled, extra macro RTOS_UCOSII will be defined, you can include UCOSII header files now, and use UCOSII API, for UCOSII application, you need to have app_cfg.h, os_cfg.h and app_hooks.c files prepared in you application. See examples in application/ucosii.

  • RTThread: RT-Thread service will be enabled, extra macro RTOS_RTTHREAD will be defined, you can include RT-Thread header files now, and use RT-Thread API, for UCOSII application, you need to have an rtconfig.h header file prepared in you application. See examples in application/rtthread.

PFLOAT

PFLOAT variable is used to enable floating point value print when using the newlib nano(NEWLIB=nano).

If you don’t use newlib nano, this variable will have no affect.

NEWLIB

NEWLIB variable is used to select which newlib version will be chosen.

If NEWLIB=nano, then newlib nano will be selected. About newlib, please visit https://sourceware.org/newlib/README.

If NEWLIB=, then normal newlib will be used.

NOGC

NOGC variable is used to control whether to enable gc sections to reduce program code size or not, by default GC is enabled to reduce code size.

When GC is enabled, these options will be added:

• Adding to compiler options: -ffunction-sections -fdata-sections

• Adding to linker options: -Wl,--gc-sections -Wl,--check-sections

If you don’t want disable this GC feature, you can set NOGC=1, GC feature will remove sections for you, but sometimes it might remove sections that are useful, e.g. For Nuclei SDK test cases, we use ctest framework, and we need to set NOGC=1 to disable GC feature.

Build Related Makefile variables used only in Application Makefile

If you want to specify additional compiler flags, please follow this guidance to modify your application Makefile.

Nuclei SDK build system defined the following variables to control the build options or flags.

• INCDIRS

• C_INCDIRS

• CXX_INCDIRS

• ASM_INCDIRS

• SRCDIRS

• C_SRCDIRS

• CXX_SRCDIRS

• ASM_SRCDIRS

• C_SRCS

• CXX_SRCS

• ASM_SRCS

• COMMON_FLAGS

• CFLAGS

• CXXFLAGS

• ASMFLAGS

• LDFLAGS

• LDLIBS

• LIBDIRS

• LINKER_SCRIPT

INCDIRS

This INCDIRS is used to pass C/CPP/ASM include directories.

e.g. To include current directory . and inc for C/CPP/ASM

INCDIRS = . inc

C_INCDIRS

This C_INCDIRS is used to pass C only include directories.

e.g. To include current directory . and cinc for C only

C_INCDIRS = . cinc

CXX_INCDIRS

This CXX_INCDIRS is used to pass CPP only include directories.

e.g. To include current directory . and cppinc for CPP only

CXX_INCDIRS = . cppinc

ASM_INCDIRS

This ASM_INCDIRS is used to pass ASM only include directories.

e.g. To include current directory . and asminc for ASM only

ASM_INCDIRS = . asminc

SRCDIRS

This SRCDIRS is used to set the source directories used to search the C/CPP/ASM source code files, it will not do recursively.

e.g. To search C/CPP/ASM source files in directory . and src

SRCDIRS = . src

C_SRCDIRS

This C_SRCDIRS is used to set the source directories used to search the C only source code files(*.c, *.C), it will not do recursively.

e.g. To search C only source files in directory . and csrc

C_SRCDIRS = . csrc

CXX_SRCDIRS

This CXX_SRCDIRS is used to set the source directories used to search the CPP only source code files(*.cpp, *.CPP), it will not do recursively.

e.g. To search CPP only source files in directory . and cppsrc

CXX_SRCDIRS = . cppsrc

ASM_SRCDIRS

This ASM_SRCDIRS is used to set the source directories used to search the ASM only source code files(*.s, *.S), it will not do recursively.

e.g. To search ASM only source files in directory . and asmsrc

ASM_SRCDIRS = . asmsrc

C_SRCS

If you just want to include a few of C source files in directories, you can use this C_SRCS variable.

e.g. To include main.c and src/hello.c

C_SRCS = main.c src/hello.c

CXX_SRCS

If you just want to include a few of CPP source files in directories, you can use this CXX_SRCS variable.

e.g. To include main.cpp and src/hello.cpp

CXX_SRCS = main.cpp src/hello.cpp

ASM_SRCS

If you just want to include a few of ASM source files in directories, you can use this ASM_SRCS variable.

e.g. To include asm.s and src/test.s

ASM_SRCS = asm.s src/test.s

COMMON_FLAGS

This COMMON_FLAGS variable is used to define common compiler flags to all c/asm/cpp compiler.

For example, you can add a newline COMMON_FLAGS += -O3 -funroll-loops -fpeel-loops in your application Makefile and these options will be passed to C/ASM/CPP compiler.

CFLAGS

Different to COMMON_FLAGS, this CFLAGS variable is used to define common compiler flags to C compiler only.

For example, you can add a newline CFLAGS += -O3 -funroll-loops -fpeel-loops in your application Makefile and these options will be passed to C compiler.

CXXFLAGS

Different to COMMON_FLAGS, this CXXFLAGS variable is used to define common compiler flags to cpp compiler only.

For example, you can add a newline CXXFLAGS += -O3 -funroll-loops -fpeel-loops in your application Makefile and these options will be passed to cpp compiler.

ASMFLAGS

Different to COMMON_FLAGS, this ASMFLAGS variable is used to define common compiler flags to asm compiler only.

For example, you can add a newline ASMFLAGS += -O3 -funroll-loops -fpeel-loops in your application Makefile and these options will be passed to asm compiler.

LDFLAGS

This LDFLAGS is used to pass extra linker flags, for example, if you want to link extra math library, you can add a newline LDFLAGS += -lm in you application Makefile.

Libraries (-lfoo) could also be added to the LDLIBS variable instead.

LDLIBS

This LDLIBS variable is library flags or names given to compilers when they are supposed to invoke the linker.

Non-library linker flags, such as -L, should go in the LDFLAGS variable.

LIBDIRS

This LIBDIRS variable is used to store the library directories, which could be used together with LDLIBS.

For example, if you have a library located in $(NUCLEI_SDK_ROOT)/Library/DSP/libnmsis_dsp_rv32imac.a, and you want to link it, then you can define these lines:

LDLIBS = -lnmsis_dsp_rv32imac
LIBDIRS = $(NUCLEI_SDK_ROOT)/Library/DSP

LINKER_SCRIPT

This LINKER_SCRIPT variable could be used to set the link script of the application.

By default, there is no need to set this variable, since the build system will define a default linker script for application according to the build configuration. If you want to define your own linker script, you can set this variable.

For example, LINKER_SCRIPT := gcc.ld.