Toolchain is a set of tools for building the C/C++ source code, it includes the compiler, linker, disassembler, GDB, and other useful tools.

Download a version for Windows ("win32-x64" in the file name) from xPack GNU Arm Embedded GCC releases and extract it to a folder of your choice.

For the purpose of this guide we are using v13.2.1-1.1 and is extracted to "C:\devtools\xpack-arm-none-eabi-gcc-13.2.1-1.1"

Note

The official GNU Toolchain for Arm distribution is open source so there exists variants of it. We are using xPack's version in this guide, but you may prefer another, e.g. Arm's own version. There are other variants such as Linaro Arm GNU toolchain (Linux host only) which is abandoned, Code Sourcery ARM Toolchain (Linux host only), any of these can be used instead but may have small differences.

If you want to use GDB for debugging on Ubuntu, unfortunately, in Arm's own version (12.3.Rel1), their GDB binary (in latest version) is hardcoded to use Python v3.8, this bug prevents it working on the latest Ubuntu, which installs latest Python version through its update, as of writing Python v3.10. For Ubuntu I suggest you use the xPack version instead.

Eclipse IDE for Embedded is used by many microcontroller manufacturers. Most manufacturer's offer their own IDE but many are actually a customised version of this.

Download the Windows x86_64 installer from Eclipse IDE Installer

Run the installer, during the install select "Eclipse IDE for Embedded C/C++ Developers", which will install a version of Eclipse and plugins taylored for embedded C/C++ programming.

Note: On Ubuntu you must trust all source links, which you can do so within the installer from the menu and tick "Trust all content", or within Eclipse IDE from the menu "Windows/Preferences" then in the dialog "Install/Update/Trust" then tick "Trust all content"

In this guide we will simply call this Eclipse.

This is a Windows port of the GNU make utility.

The GNU make utility is a popular scripting tool for automating C/C++ development on Linux. It is the interpreter for GNU "make" scripts, which enables the script to run. On Linux the make scripting language is a popular choice for automating the task of executing tools to build programs. It provides prerequisite (timestamp update dependency) logic for rules (conditions) more suitable for updating the build process, e.g. you want to only compile objects that are out of date to the sources. The main problem is that scripting languages, e.g. Bash, KornShell, Borne shell, MSDOS, PowerShell do not provide such built-in logic.

Eclipse itself requires a build tool - one that it supports. We will set it up to use this tool.

We will use xPack's version which is a more complete port than the GnuWin32 one.

Download a release version from xPack Windows Build tools releases and extract it to a folder of your choice.

For the purpose of this guide we are using v4.4.1-2 and is extracted to "C:\devtools\xpack-windows-build-tools-4.4.1-2"

The USB Blaster II is the official programming JTAG adapter for Intel FPGAs, and it is already integrated on the DE10-Nano board. It requires a driver and the firmware file blaster_6810.hex to work. The driver and firmware file comes bundled with "Quartus Prime Programmer and Tools" and also "Quartus Prime Lite", and so you can install either one. If you're not going to use "Quartus Prime Lite", you may prefer the smaller size of "Quartus Prime Programmer and Tools". During the setup just make sure to include the driver as part of the installation.

OpenOCD requires the path to the blaster_6810.hex file to be specified. Since the installation of Quartus creates environment variable QUARTUS_ROOTDIR or QSYS_ROOTDIR for us, I've added TCL code to the default target script (altera-usb-blaster2.cfg) to use these to find the path of the blaster_6810.hex file.

In this guide we will simply call "Quartus Prime Lite" as "Quartus Prime".

This is a popular low level layer debugging software for embedded devices. It is able to communicate with hardware debug adapters and send debug commands or signals to control the target processor. It understands the low level industry standards JTAG/SWD/Arm CoreSight commands and has support for various debug adapters.

Eclipse supports the OpenOCD debugging software.

The github OpenOCD master branch contains the latest commits (changes) but normally is ongoing code so I prefer to use a Release version instead.

I am too lazy to build OpenOCD from the source files so will use xPacks's binary release. Download a version from xPack OpenOCD releases and extract it to a folder of your choice.

For the purpose of this guide we are using v0.12.0-2 and is extracted to "C:\devtools\xpack-openocd-0.12.0-2"

At this time, OpenOCD does not include a target script file for the DE10-Nano, download it from my github: DE10-Nano scripts.

Download and extract the script "altera_fpgasoc_de.cfg" (from the openocd-config-scripts/target folder) into the "target" of your OpenOCD installed folder. In this guide the location is:
"C:\devtools\xpack-openocd-0.12.0-2\share\openocd\scripts\target"

Also:

In newer versions of OpenOCD it no longer searches for the USB Blaster II firmware (blaster_6810.hex found inside bin, bin64 or linux64 in the Quartus Prime installation folder), so you have two options:

1. Extract the script "altera-usb-blaster2.cfg" into the "interface" folder of your OpenOCD folder. In this guide the location is:
   "C:\devtools\xpack-openocd-0.12.0-2\share\openocd\scripts\interface". My TCL script attempts to search for the firmware using the environment variables QSYS_ROOTDIR or QUARTUS_ROOTDIR, which is set by the Quartus Prime installation.
2. Or, alternatively, you can use the default OpenOCD "altera-usb-blaster2.cfg" script and simply set the correct path on this line:
   usb_blaster firmware /path/to/quartus/blaster_6810.hex

This contains my example source code with Eclipse project.

Download from the pre-requisite list above.

Extract it to a folder of your choice. For the purpose of this guide it is extracted to "D:\Documents\de10nano-baremetal-guide"

When starting Eclipse it will prompt for a workspace location. We will use the default, just click the "Launch" button, and tick remember my decision if you would like.

• Select from the menu "Windows/Preferences". The dialog displayed is for configuring all of the global and workspace settings.
• We are interested in the MCU tree, click the greater than icon ">" to open up the tree

• In the MCU tree, click the "Global Arm Toolchains Paths"
• For the "Default toolchain", select "xPack GNU Arm Embedded GCC (arm-none-eabi-gcc)"
• Click the "Browse" button and select the bin folder of the "Arm GNU toolchain". In this guide the location is: "C:\devtools\xpack-arm-none-eabi-gcc-13.2.1-1.1\bin"

• In the MCU tree, click the "Global Build Tools Path"
• Click the "Browse" button and select the bin folder of the make utility. In this guide the location is: "C:\devtools\xpack-windows-build-tools-4.4.1-2\bin"

• In the MCU tree, click the "Global OpenOCD Path"
• For the "Executable" box, leave it defaulted as "openocd.exe", or if no default (empty) then type it in
• Click the "Browse" button and select the bin folder of the OpenOCD. In this guide the location is: "C:\devtools\xpack-openocd-0.12.0-2\bin"

• Start "Eclipse IDE for Embedded C/C++ Developers"
• The "Eclipse IDE Launcher" is displayed and prompts "select a directory as workspace". The default path is fine, just click the "Launch" button
• In Eclipse, select from the menu "File/Open Projects from File System..."
• On the "Import Projects" dialog window, click the "Directory..." button and select the parent directory of the example, in this guide it is "D:\Documents\de10nano-baremetal-guide"
• Notice that the parent folder is listed as a selectable option (a tick box item) - this enables a single folder (parent folder) to store & manage settings for multiple projects, but I think is not ideal for our use case. All my projects are independent so should have their own settings. Click the "Deselect All" button and tick only "..\hello_world_semihosting" project (see the picture)
• Click the "Finish" button

On the toolbar there is a hammer icon - this is the build icon. Also, just next to it is a down-arrow icon - this is the build configuration select icon. It should be defaulted to the Debug configuration, let's change it. Click the dropdown next to the hammer and select "DebugSemihosting" to switch. Notice switching automatically starts building the source code.

If successful, you should see a message in the build console like this: "Build Finished. 0 errors, 1 warnings. (took 885ms)"

Ignore the 1 warning regarding the load segment with RWX permissions. That refers to the permissions of the On-Chip RAM load section defined in the linker file.

As an exercise, we will set a breakpoint, this will halt the execution at that point (location), and will enable us to begin stepping lines of code within the counting loop.

• Within the Project Explorer, double-click main.c file to open it
• Double-click the space to the left of line 65 to set a breakpoint, indicated by a round dot if set, see the picture

Note: A breakpoint will only work where there is code. Eclipse is not able to prevent setting invalid breakpoint locations - it is not within their control, the toolchain would need to support such a feature.

The compiled elf program will not run on your PC, if we wish to run and debug the elf from the PC we will need to use an emulator, such as QEMU, or use debug tools, such as OpenOCD and GDB, we will use this latter option.

• If there is a SD card in the slot, remove it
• Set the mode switches on the DE10-Nano for booting from SD card so that nothing boots (this is the default if you didn't change these switches before)
• Attach a USB 2.0 cable between the USB Blaster II connector and your PC (the USB port on the same side as the 5V power supply socket)
• Apply power to the DE10-Nano board

In the hello world project you will find my pre-configured GDB & OpenOCD eclipse debug configurations.

• From the menu, select "Run" and then "Debug Configurations..."
• In the tree of "GDB OpenOCD Debugging", click the "hello_world_semihosting_debug" profile
• Click the "Debug" button and some magic stuff happens
• If prompted to switch into debug perspective, click "Switch" (also tick "Remember my decision" if you want)

1. Issues a soft processor reset
2. Loads and executes U-Boot-SPL to initialise the DE10-Nano processor system (HPS), which also enables the SD-RAM to be used
3. Finally, loads and executes your elf program

When ready, your program should now be running on the DE10-Nano board. The execution is halted at a breakpoint as indicated in Eclipse by a green line in the main.c source file.

Note: By default a breakpoint is set at the start of main within the debug configuration profile, but this can be turned off. Also there is a bug in Eclipse OpenOCD & GDB plugin. When disabling the "Set breakpoint at: main" doesn't work, i.e. checkbox is unticked but it still breaks on main, you need to select "Remove all breakpoints" from the Run menu. I think this setting creates an invisible breakpoint in main, which is not synched (a round dot not shown) in the IDE source editor

Noticed the layout, panels and toolbars have changed, Eclipse has switched into the debug perspective. Perspective is Eclipse's jargon for layout profile

At the top the toolbar contains useful debug controls: resume, suspend, terminate, step into (F5) and step over (F6).

Click the resume button to continue the execution.

Semihosting is a mechanism which allows us to view and input debug messages through the debug adapter and a console. Eclipse conveniently includes a built-in console panel at the bottom.

You should be able to see "Hello, World" as a debug message inside the console panel. This comes directly from the elf running on the DE10-Nano.

Execution should be prompting for an input. Click inside the console panel and enter a number, for example 10, then press enter.

The execution should reach our breakpoint we made earlier and is now halted. We will use the toolbar at the top to step each line of the for loop.

Click on the "step over" button (or press F6) to advance a step. Keep stepping and notice the console at the bottom outputs the for loop count sequence. Also, the variables panel displays a table of variables with their live content, these are read automatically from the target Arm processor on DE10-Nano via GDB & OpenOCD through the USB Blaster II (JTAG) adapter.

Keep stepping, until you see "Test completed" message. Stepping any further will get you into the infinity loop function.

Click the red button in the toolbar at the top, this terminates the debug session and also stops the debug connection (OpenOCD and GDB) between the USB Blaster II and Eclipse.

The layout is not automatically restored, click the C/C++ perspective button on the top right corner (see the picture). This restores the layout back to the C/C++ perspective.

Note, although the debug session has stopped, the execution continues to run on the DE10-Nano's processor. *Update*, in newer Eclipse GDB/OpenOCD it now halts the execution when session is stopped. But this is not an issue because my OpenOCD script sends a soft processor reset when another debug session is started.

• Select from the menu "File/New/C/C++ Project"
• Select "C Managed Build"
• Click "Next"

• Enter helloworld_uart for the project name
• Uncheck "Use default location"
• Browse and select your preferred location for this project. In this guide, create a new folder called helloworld_uart2 and select that for the location: D:\Documents\de10nano-baremetal-guide\helloworld_uart2
• Select "Empty Project" for project type
• Select "Arm Cross GCC" for toolchain
• Click "Next"

• For the toolchain name, use the dropdown to select "xPack GNU Arm Embedded GCC (arm-none-eabi-gcc)"
• The path should be filled in automatically because we've previously set this toolchain up in the global settings
• Click "Finish"

We cannot do much with an empty project, let's add in some files from the "Hello, World!" UART example.

• bsp_generated (entire folder)
• hwlib (entire folder)
• utils (entire folder)
• main.c
• u-boot-spl-nocache

Maximise Eclipse, then within Project Explorer, open up the tree, right-click the project name and select "Refresh" (or press F5)

Note, if you prefer to download the HWLib source from the official site, get it from here: Intel SoC FPGA HWLib. You will need the hwlib located inside the armv7a folder.

The project cannot be compiled yet, it needs the correct build settings.

• In "Project Explorer", right-click the project name and select "Properties"
• A dialog displays the current build configuration, in this case is "Debug" indicated at the top by the dropdown
• Open up "C/C++ Build" tree
• Click on "Settings"
• Click on "Target Processor" (If it is not already selected)
• For the "Arm family" setting, select "cortex-a9"
• For the "Instruction set" setting, select "Toolchain default" or "Arm". "Thumb" will not work
• For the "Float ABI" setting, select any option you prefer. In this guide we select "FP instructions (hard)"
• For the "FPU Type" setting, select "neon". This is only for hardware float, otherwise it is disabled
• For the "Unaligned access" setting, select "Disabled (-mnu-unaligned-access)", which disables the triggerring of exception when accessing unaligned addresses

HWLib needs these defined symbols set when using a Cyclone V SoC-FPGA.

• Click on "Preprocessor" under "GNU Arm Cross C Compiler"
• In "Defined symbols", use the "Add.." button to add the following defines
• soc_cv_av
• CYCLONEV

In my source files, the header includes don't use absolute paths so we need set the search paths here to tell it where to look for header files during a build.

• Click on "Includes" under "GNU Arm Cross C Compiler"
• In the "Includes paths", use the "Add.." button add the following paths:
• "${workspace_loc:/${ProjName}/bsp_generated}"
• "${workspace_loc:/${ProjName}/hwlib/include}"
• "${workspace_loc:/${ProjName}/hwlib/include/soc_cv_av}"
• "${workspace_loc:/${ProjName}/util/include}"

Bare-metal require a suitable linker script for your board and processor, we will use HWLib's linker file.

• Click on "General" under "GNU Arm Cross C Linker"
• In "script files", use the "Add.." button to add the file: "${workspace_loc:/${ProjName}/hwlib/src/linkerscripts/cvav-ddr.ld}"

• Click on "Miscellaneous" under "GNU Arm Cross C Linker"
• Tick the "Do not use syscalls" checkbox

By default the "Create flash image" option is enabled with "Intel HEX" format. This option outputs an additional compiled file useful for creating images. It is not required now, but it will be required when creating a SD card image or a flash memory image, and this is because U-Boot-SPL does not support the .elf format, however it is able to load and start a binary file.

• Click on "General" under "GNU Arm Cross Create Flash Image"
• For "Output file format" select "Raw binary"

• Click on "Toolchains" tab
• Untick the "Create flash image" checkbox

Ok, let's switch to the Release configuration. Using the dropdown at the top, switch to the Release. The Release configuration requires the same changes we made for the Debug configuration, unfortunately you have to manually repeat the process.

We could have selected the "All configurations" at the beginning and then make our changes, but there is no indication (e.g. no colour coding or emphasis) to show which options are the same or different - I believe this is accident-prone for beginners.

Note: Don't forget to click "Apply" at the end, and if prompted rebuild the index.

If we want to use Semihosting debug functionality we need to set linker library settings. We can set them in the Debug configuration but I prefer to create a separate build configuration for it.

• Click "Manage Configurations..." button
• Click "New..." button
• For the "Name" enter "DebugSemihosting"
• Under the "Copy settings from" and "Existing configuration" ensure "Debug" is selected
• Click "OK" button
• In the "Manage Configuration also click the "OK" button

We will add a user defined symbol (a made up symbol) for use in our code to conditionally enable and disable semihosting code.

• Use the dropdown at the top to switch to DebugSemihosting
• Click on "Preprocessor" under "GNU Arm Cross C Compiler"
• In "Defined symbols", select the last symbol so that we can add to the end of the list
• Use the "Add.." button to add the define "SEMIHOSTING"

To use semihosting we need to link to the rdimon library and also set specs flag for rdimon. The rdimon library comes with the GNU C/C++ Arm cross toolchain we are using so no need to install anything.

• Click on "Libraries" under "GNU Arm Cross C Linker"
• In "Libraries", use the "Add.." button and enter "rdimon" and press "OK"
• Click on "Miscellaneous" and for "Other linker flags" input box enter "--specs=rdimon.specs"
• Click "Apply" button, and if prompted rebuild the index

If you find semihosting too slow, you may prefer to output debug messages to UART instead. I have written code to support this and is enabled by defining symbol TRU_DEBUG_PRINTF. We will create a separate build configuration for this.

• In "Manage Configurations..." dialog
• Click "New..." button
• For the "Name" enter "DebugUART"
• Under the "Copy settings from" and "Existing configuration" ensure "Debug" is selected
• Click "OK" button
• In the "Manage Configuration also click the "OK" button

We will add a user defined symbol (a made up symbol) to enable the TRU_DEBUG_PRINTF to output to UART0.

• Use the dropdown at the top to switch to DebugUART
• Click on "Preprocessor" under "GNU Arm Cross C Compiler"
• In "Defined symbols", select the last symbol so that we can add to the end of the list
• Use the "Add.." button to add the define "TRU_PRINTF_UART"
• Click "Apply and Close" button, and if prompted rebuild the index

At this point, starting the build (compile) process results in several errors. This is because of the HWLib library, to eliminate these errors we need to exclude some source files.

• In "Project Explorer" open up the tree for "hwlib/src/hwmgr"
• Right-click "soc_a10" folder and select "Resource Configurations/Exclude from Build..."
• Click "Select All" to exclude from all build configurations
• Click "OK"

• Within the same folder "hwlib/src/hwmgr", exclude the file "alt_eth_phy_ksz9031.c"
• Within the same folder "hwlib/src/hwmgr", exclude the file "alt_ethernet.c"

• Within the folder "hwlib/src/utils", exclude the file "alt_base.S"

• Within the folder "hwlib/src/utils", exclude the file "alt_printf.c"

Let's create a debug configuration for any currently active build configuration.

• From the menu select "Run/Debug Configurations..."
• Right-click "GDB OpenOCD Debugging" and select "New Configuration"
• In the "C/C++ Application:" input box, type in: "${config_name:${project_name}}/${project_name}.elf"
• For "Build Configuration", select "Use Active"
• Click the "Debugger" tab (the second tab)
• In "Config options" type in:
  -f interface/altera-usb-blaster2.cfg -f target/altera_fpgasoc_de.cfg -c "init; halt; c5_reset; halt; c5_spl u-boot-spl-nocache"
• Click the "Startup" tab
• Untick "Initial Reset" checkbox
• Untick "Pre-run/Restart reset" checkbox
• Untick "Set breakpoint at: main" checkbox
• Click the "Common" tab
• Under "Save as" select "Shared file" so that the config is saved inside your project instead of the workspace
• Click "Apply" button to save the settings, then click "Close"