Skip to content
This repository was archived by the owner on Sep 17, 2023. It is now read-only.

Using the Toolchain

Jump to bottom
Samuel Dewan edited this page Oct 5, 2021 · 7 revisions

Building the Project

Note: Before following the instructions on this page you will need to have cloned the avionics software Git repository as described on the getting started page.

To compile the avionics software, from within the repository folder run:

make build

If your toolchain is not on your PATH you will need to tell make where it is located. You can do that by specifying the CORTEX_TOOLCHAIN_BIN variable when calling make, like this:

make build CORTEX_TOOLCHAIN_BIN=<location_of_toolchain_binaries>

Replace <location_of_toolchain_binaries> with the path to the bin folder of your arm-none-eabi-gcc toolchain installation, for example /opt/cortex-toolchain/bin.

This command will create an obj folder. In this folder an object file and assembly listing for each source file will be created as well as a file called main.elf which is the binary to be loaded onto the microcontroller.

In order to speed up the build process, especially when building the entire project from scratch, you can use the -j <number of threads> flag with make build to compile multiple files concurrently. A good rule of thumb for how many threads to use is twice the number of CPU cores that your computer has. If you use -j without a number there will be no limit to the number of threads that make creates, which usually isn't the fastest jobs setting but will be faster than using a single job.

To delete everything in the obj folder in order to do a fresh build, you can run:

make clean

Boards and Variants

The avionics software can be build for a number of different boards and to fill a number of different roles. Supported boards include the revision A and revision B microcontroller boards (mcu/rev_a and mcu/rev_b) and the revision A SAME54 microcontroller board (big_mcu/rev_a) as well as the SAMD21 Xplained Pro development board (samd21_xplained_pro). Supported roles include a test roll (test), the rocket roll (rocket) and the ground station roll (ground).

By default the software will be built for the revision A microcontroller board with the test roll, but this can be changed by specifying the BOARD and/or VARIANT variables when calling make. For example, to build the rocket software for the SAME54 microcontroller board you would run the following command:

make build BOARD=big_mcu/rev_a VARIANT=rocket

Programming the Microcontroller

Atmel ICE, Segger J-Link and Xplained Pro

The makefile is able to automatically start GDB and OpenOCD when using a CMSIS compatible programmer or a Segger J-Link programmer. To do this run the following from the avionics repository folder:

make debug CORTEX_TOOLCHAIN_BIN=<location_of_toolchain_binaries> OPENOCD_PATH=<path_to_openocd_binary> OPENOCD_INTERFACE=<cmsis/jlink> BOARD=<board> VARIANT=<variant>

You will also need to add the correct BOARD and VARIANT variables.

Replace <location_of_toolchain_binaries> with the path to the bin folder of your arm-none-eabi-gcc toolchain installation (e.g. /opt/cortex-toolchain/bin). The CORTEX_TOOLCHAIN_BIN variable can be omitted from the command if arm-none-eabi-gdb is on your PATH.

<path_to_openocd_binary> must be replaced with the complete path to the OpenOCD program. On Windows this path should end in openocd.exe and must not contain any spaces (remember that from the Windows Subsystem for Linux your C drive is located at /mnt/c). If OpenOCD is on your PATH (when you open a terminal, you can run openocd without seeing a command not found message), which is quite likely if you are using Linux or macOS, you can leave the OPENOCD_PATH section out of the command entirely.

If you are using the Windows Subsystem for Linux too will need to add WSL=true to the command in order to indicate to the debugging script that OpenOCD will be a Windows executable.

Finally, <cmsis/jlink> should be replaced by either jlink if you are using a Segger J-Link programmer or cmsis otherwise.

After you run the make command you will be at the GDB prompt. Once in GDB, it is possible to run the following commands to program the microcontroller and start running the software:

monitor reset halt
load
continue

To exit GDB, press Ctrl+C to halt the microcontroller and run the quit command. The microcontroller will remain halted after GDB exits.

Segger J-Link GDB Server

Rarely, the Segger J-Link tools can be unstable when used with OpenOCD. If this happens, it may be worthwhile to try using Segger's own GDB server. The J-Link GDB server is available as part of the "J-Link Software and Documentation Pack" at this site.

After starting the J-Link GDB server application, in the Config window choose the option to connect to the J-Link device over USB. The target device on the revision A and B MCU boards is an ATSAMD21J18 and is Little Endian. The target interface is SWD. The command line options at the bottom of the window should look like this when you are done configuring the GDB server:

-select USB -device ATSAMD21J18 -endian little -if SWD -speed 4000 -noir -LocalhostOnly

For the newer Big-MCU board the target device is an ATSAME54P20 and the following command line options should be used.

-select USB -device ATSAME54P20 -endian little -if SWD -speed 4000 -noir -LocalhostOnly

Once the J-Link GDB Server is running, start GDB with the following command:

make debug CORTEX_TOOLCHAIN_BIN=<location_of_toolchain_binaries> BOARD=<board> VARIANT=<variant>

Replace <location_of_toolchain_binarys> with the path to the bin folder of your arm-none-eabi-gcc toolchain installation (e.g. /opt/cortex-toolchain/bin). The CORTEX_TOOLCHAIN_BIN variable can be omitted from the command if arm-none-eabi-gdb is on your PATH.

Once in GDB, it is possible to run the following commands to program the microcontroller and start running the software:

monitor reset
load
continue

To exit GDB, press Ctrl+C to halt the microcontroller and run the quit command. The microcontroller will remain halted after GDB exits.

MPLAB Snap and PICkit 4

The MPLAB Snap or PICkit 4 programmers can be used to program the microcontroller through Microchip's MDB tool, which is part of MPLAB X.

Launch MDB by running the script appropriate for your operating system:

Platform MDB path
Linux /opt/microchip/mplabx/vn.nn/mplab_platform/bin/mdb.sh
macOS /Applications/microchip/mplabx/vn.nn/mplab_platform/bin/mdb.sh
Windows (64 bit) c:\Program Files (x86)\Microchip\MPLABX\vn.nn\mplab_platform\bin>mdb.bat
Windows (32 bit) c:\Program Files\Microchip\MPLABX\vn.nn\mplab_platform\bin>mdb.bat

Replace vn.nn with the version number of your MPLAB X installation, for example v5.25. Note that on Linux the installer will place a symlink to MDB on your PATH so you can simply run mdb from a command line.

Once MDB is running, to program the microcontroller, launch MDB and run the following commands:

device ATSAMD21J18A
hwtool <tool>
program "<path to main.elf>"
run

Replace <tool> with the name of the tool you are using, snap or PICkit4. Replace <path to main.elf> with the path to main.elf, which will be generated by the Makefile in the obj directory of the avionics project.

It is also possible to program the board with the MPLAB X IPE (Integrated Programming Environment), which is essentially a graphical frontend for MDB. The IPE does not accept elf files though, so you have to create a hex file. This can be done using the CU InSpace Makefile's hex target.

For more information on MDB, see the MDB User's Guide.

Environment Variables and Targets

Targets

Target Description
build This is the default target. It compiles the avionics software and creates main.elf, which can be programmed onto a microcontroller.
all Performs a clean build and uploads it to a microcontroller.
elf Creates main.elf.
hex Creates main.hex, which is useful for programming a microcontroller with the Microchip IPE.
gccversion Prints out version information for gcc.
info Prints out the compiler flags used for the build as well as a list of all the source files to be compiled and the object files that will be created. Useful for debugging the Makefile.
program Programs the software onto a microcontroller using OpenOCD and resets the microcontroller so that the software will start running.
upload Programs the software onto a microcontroller using OpenOCD and leaves the microcontroller in a halted state.
reset Resets a microcontroller using OpenOCD and lets it start running the software.
halt Resets a microcontroller using OpenOCD and leaves it in a halted state.
debug Launch a debugging session in GDB.
openocf.cfg Creates OpenOCD configuration file.

Environment Variables

Variable Description
BOARD Selects which board the software should be compiled for. Valid options include mcu/rev_b, big_mcu/rev_a and samd21_xplained_pro.
VARIANT Selects which variant of the software should be built. Valid options include test, rocket and ground.
CORTEX_TOOLCHAIN_BIN Specifies the location of the toolchain. The value of this variable should be the path to the folder in which arm-none-eabi-gcc is located. If this variable is not specified the Makefile will look for the toolchain on the PATH. Note that if this variable is specified the debugging script will use the version of GDB from the specified toolchain rather than the system GDB.
OPENOCD_PATH Path to the OpenOCD binary. For example /usr/local/bin/openocd or /mnt/c/Program\ Files/openocd/bin/openocd.exe. If this variable is not specified the Makefile look for OpenOCD on the PATH.
OPENOCD_INTERFACE Specifies the type of debugging interface to be used by OpenOCD. Valid options include cmsis and jlink. If an unknown value is passed in this variable it will be directly inserted into the OpenOCD configuration file in the line adapter driver $OPENOCD_INTERFACE. If this variable is not set the debugging script will default to attempting to use a CMSIS-DAP compliant debugger.
WSL Defining this variable to any value (for example WSL=true) will indicate to the debugging script that it is running on the Windows Subsystem for Linux. This will cause it to create its temporary OpenOCD configuration file in the current working directly rather than as a generic temporary file and to pass the configuration file path to OpenOCD as a relative path. This makes it possible for the debugging script to run a Windows version of OpenOCD from within WSL.
GDB_FILE If this variable is specified, instead of launching OpenOCD the debugging script will simply have GDB open the specified file. This file should be a pipe or a serial interface with a GDB server on the other end. This variable can be used to debug with a Black Magic Probe.

Examples

Compile firmware for rocket to run on rev. A Big MCU board using a toolchain located in /Applications/ARM/bin. Use 8 parallel jobs.

make build CORTEX_TOOLCHAIN_BIN=/Applications/ARM/bin BOARD=big_mcu/rev_a VARIANT=rocket -j 8

Compile firmware for ground station to run on rev. B MCU board using a toolchain that is on the PATH.

make build BOARD=mcu/rev_b VARIANT=ground

Debug test variant firmware running on rev. A Big MCU board using CMSIS-DAP compliant debugger, toolchain located in /opt/cortex-toolchain/bin and OpenOCD located on the PATH.

make debug CORTEX_TOOLCHAIN_BIN=/opt/cortex-toolchain/bin BOARD=big_mcu/rev_a VARIANT=test

Debug ground firmware running on rev. A MCU board with J-Link debugger using the Windows Subsystem for Linux. Toolchain located in /opt/cortex-toolchain/bin, OpenOCD is /mnt/c/Program\ Files/openocd/bin/openocd.exe.

make debug CORTEX_TOOLCHAIN_BIN=/opt/cortex-toolchain/bin BOARD=mcu/rev_a VARIANT=ground OPENOCD_PATH=/mnt/c/Program\ Files/openocd/bin/openocd.exe OPENOCD_INTERFACE=jlink WSL=true

Debug rocket firmware running on rev. A Big MCU board using a GDB server that is already accessible at localhost port 2331. Toolchain located on PATH.

make debug BOARD=big_mcu/rev_a VARIANT=rocket

Debug the test firmware running on a SAMD21 Xplained Pro board. Toolchain located in /Applications/ARM/bin and OpenOCD located on the PATH. The Xplained Pro board's onboard EDBG debugging is CMSIS-DAP compliant.

make debug CORTEX_TOOLCHAIN_BIN=/Applications/ARM/bin BOARD=samd21_xplained_pro VARIANT=test

In-Circuit Debugging

The project can be debugged while running with GDB. To halt the program while it is running, use Ctrl+C. Some useful GDB commands are listed in the table below.

Command Usage
load Load the program onto the target
continue or c Continue running the program on the target
bt or bt full Print out the call stack, optionally including the values of local variables
break <file>:<line_number> Insert a breakpoint
info break List all breakpoints
disable <breakpoint_number> Disable a breakpoint
delete <breakpoint_number> Delete a breakpoint

You can find a reference sheet with many more useful GDB commands here.

Note that the SAM D21 microcontroller only has support for four hardware breakpoints and two hardware watchpoints. The SAM E54 supports 6 breakpoints and 4 watchpoints. If you need more, a software breakpoint can be inserted anywhere in the code with the following inline assembly:

__asm__ __volatile__ ("bkpt #0");

NOTE: It is important that software breakpoints are removed as soon as they are no longer needed. They should not be committed to the repository because if a breakpoint instruction left in the code is executed when a debugger is not attached to the microcontroller a hard fault will occur.

It is also theoretically possible to debug with MDB. In practice this is very difficult and many features do not work at all. If you want to try it you can find the documentation for MDB here.

Clone this wiki locally