-
Notifications
You must be signed in to change notification settings - Fork 4
Installing the Toolchain
In order to compile the CU InSpace avionics software, download it to a microcontroller and debug it a number of programs are required. This document describes the tools that are needed and how to install and configure a development environment on Linux, macOS or Windows. If you are just looking for instructions to set up the toolchain on Windows skip right to the step by step instructions further down on this page.
The following tools and libraries are required to compile and debug the CU InSpace avionics firmware:
- GCC for arm-none-eabi (GCC 7 or new required, 10.3 recommended)
- Newlib for ARM
- Binutils for arm-none-eabi
- GDB for arm-none-eabi or a multi-architecture version of GDB
- OpenOCD (0.11.0 or newer)
- Make
- Python3
- sed
Additionally, Git is required in order to clone the project from GitHub and make contributions.
There are few different options for where to get GCC. If you are running Linux it is probably easiest to get the toolchain from your distributions repositories, as described below. If you are running macOS you can get GCC from MacPorts or Homebrew (also described below).
It is also possible to get the toolchain directly from ARM. The GNU Embedded Toolchain for Arm includes GCC, GDB and binutils. Microchip, the vendor of the microcontroller we are using, also provides their own ARM toolchain distribution. Don't use the toolchain provided by Microchip, it is based on a very old version of GCC and will not work for our project.
If the binaries for ARM toolchain you wish to use are not on your PATH, you can specify the directory in which they are located by setting the environment variable CORTEX_TOOLCHAIN_BIN when building the project (see Using the ARM toolchain).
On Linux, all of the required tools should be available from your distribution's repositories. The exact packages required to install all of the toolchain requirements differ, but here are a few examples for popular distributions are shown below in this section.
Some Linux distributions package older version of GCC which are not suitable for our project. We require at least GCC 7. If your distribution does not packages a new enough version of arm-none-eabi-gcc then you can use the distribution of GCC provided by ARM as described at the end of this section.
apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi gdb-multiarch openocd git build-essential sed
zypper install cross-arm-none-gcc10 cross-arm-binutils cross-arm-none-newlib-devel gdb openocd git make sed
On openSUSE Leap the version available version of GCC will likely be older. For instance on openSUSE Leap 15.1 the package is cross-arm-none-gcc7.
Arch Linux need a udev rule to run openocd with the J-Link debuggerwithout root access. See udev Rule for J-Link Debugger.
pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-gdb arm-none-eabi-newlib openocd git make sed
Other distributions will have similarly named packages. It is a good idea to search the repositories for 'arm-none' to find all of the toolchain components which are available. You might need to add a udev rule to work without root.
ARM provides a suitable toolchain which can be downloaded here. Once downloaded, the tar archive can be extracted and the toolchain folder can be moved to a convenient location.
To quickly downloading and install the toolchain you can run the following commands:
wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.07/gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2
tar xf gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2
sudo mv gcc-arm-none-eabi-10.3-2021.07 /opt/cortex-toolchain
rm gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2This will install the toolchain to /opt/cortex-toolchain, the tools will be located in the folder /opt/cortex-toolchain/bin. You can check that the toolchain is installed properly by running /opt/cortex-toolchain/bin/arm-none-eabi-gcc --version. When building or debugging the project you will need to use the CORTEX_TOOLCHAIN_BIN environment variable to tell the makefile where the toolchain is located (see Using the ARM toolchain). For example, make build CORETEX_TOOLCHAIN_BIN=/opt/cortex-toolchain/bin.
Some Linux distos do not allow non-root users to connect to the J-Link debugger. This error looks like this:
$ openocd -f openocd-jlink.cfg
Open On-Chip Debugger 0.10.0
adapter speed: 400 kHz
cortex_m reset_config sysresetreq
Warn : Failed to open device: LIBUSB_ERROR_ACCESS.
Info : No device selected, using first device.
Error: No J-Link device found.
To fix this you must add a udev rule:
ACTION=="add", SUBSYSTEM=="usb", ATTR{product}=="J-Link", ATTR{manufacturer}=="SEGGER", GROUP="jlink", MODE="0660"
to /etc/udev/rules.d/40-jlink.rules then creating a group by running sudo groupadd jlink that the user can join to gain access to the debugger by running usermod -aG jlink $USER. You will need to log out and log back in to refresh the user groups. You can run the groups command to see if you're part of the group.
If you already have MacPorts or Homebrew installed it is probably easiest to install the toolchain through the repository you are already using. Instructions for each are provided below. Note however that the toolchains provided by MacPorts and Homebrew are not always completely up to date.
If you don't have a repository already set up, I recommend looking into it. Having MacPorts or Homebrew makes it a lot easier to get a variety of open source software on macOS. If you don't want to install a package manager, or want a newer version of GCC than is available through the package manager you are using, you can install the toolchain distributed by ARM.
The toolchain for macOS can be installed with MacPorts, which is a package manager and software repository for macOS. To install MacPorts follow the instructions from the MacPorts website.
Once MacPorts is installed, to install the required tools run the following command:
sudo port install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-gdb openocd +cmsisGit and Make are available for macOS as part of the Xcode command line tools. The process for installing the Xcode command line tools is detailed here as part of the process for installing MacPorts.
Note: these instructions have not been tested, if you try them out please updated this page to either remove this warning or fix the instructions
You can install Homebrew using the instructions from https://brew.sh.
Once Homebrew is installed use the follow command to install the required tools:
brew install --cask gcc-arm-embedded
brew install open-ocdARM provides a distribution of the toolchain from their website. Conveniently, they provide a signed and notarized version for macOS as a standard .pkg installer. All you have to do is download it from their downloads page and install the package as you would with any other macOS installer.
The ARM toolchain installer puts the toolchain in /Applications/ARM. When building or debugging the project you will need to use the CORTEX_TOOLCHAIN_BIN environment variable to tell the makefile where the toolchain is located (see Using the ARM toolchain). For example, make build CORETEX_TOOLCHAIN_BIN=/Applications/ARM/bin.
While all of the required software is available natively, our makefile does not currently support Windows. The recommended way to setup a development environment on Windows is by using the Windows Subsystem for Linux. All of the tools except for OpenOCD should be installed inside the Windows Subsystem for Linux and the repository should be cloned somewhere that is accessible to the subsystem, it generally works best to clone the repository somewhere that is also accessible to Windows software so that the OpenOCD configuration files can be used.
A binary release of OpenOCD for Windows is available here. An OpenOCD server can be run on Windows and connected to by an instance of GDB running within the Windows Subsystem for Linux.
In order to get all of the required tools working under Windows we use the Windows Subsystem for Linux, which allows Windows to run Linux software.
Follow the instruction from Microsoft here to install the Windows Subsystem for Linux. After the feature is enabled, you will be able to install a Linux distribution from the Microsoft store, searching for "Linux" should bring you to a page that shows all of the avaliable distributions, you can choose any Linux distribution you want. If you are not sure which distribution to use, Ubuntu is usually a good option for beginners.
Git and Make will be available in the repositories of the distribution you choose. How exactly to install them will differ slightly by distribution, here's how to do it for some of the more common ones:
openSUSE or SUSE Linux Enterprise:
sudo zypper install git make libncurses5
Debian, Ubuntu, Kali or Pengwin:
sudo apt install git make
Fedora:
sudo dnf install git make
Alpine Linux:
sudo apk add git make
ARM provides a suitable toolchain which can be downloaded here. Once downloaded, the tar archive can be extracted from within the Windows Subsystem for Linux and the toolchain folder can be moved to a convenient location. Note that the Windows C drive is accessible from within Linux as /mnt/c.
To quickly downloading and instal the toolchain you can run the following commands from within the Windows Subsystem for Linux:
wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.07/gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2
tar xf gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2
sudo mv gcc-arm-none-eabi-10.3-2021.07 /opt/cortex-toolchain
rm gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2This will install the toolchain to /opt/cortex-toolchain, the tools will be located in the folder /opt/cortex-toolchain/bin. You can check that the toolchain is installed properly by running /opt/cortex-toolchain/bin/arm-none-eabi-gcc --version.
Versions of OpenOCD compiled for Windows are available from the releases page of the OpenOCD GitHub mirror. Uncompress the archive and place its contents in Program Files/openocd. You should be able to run OpenOCD from inside WSL like this: /mnt/c/Program\ Files/openocd/bin/openocd.exe.
If you want to put OpenOCD in a different location you can, but you will have to remember where you put it and may need to use some extra arguments when debugging and/or change some configuration files.
That's all the tools that you need to install in order to build and debug the CU InSpace avionics firmware. To test the toolchain, make sure you have the avionics software repository cloned within WSL as described on our getting started page, then follow the instructions on the using the toolchain page to build the project.
On Windows, it is necessary to ensure that the J-Link adapter is using the WinUSB driver before it can be used with OpenOCD. This can be done with a tool called Zadig, which is available here. When the J-Link device is connected it is possible to open Zadig, select "J-Link" from Zadig's menu (it may be necessary to check "List All Devices" in the Options menu) and click the "Replace Driver" button to switch to the WinUSB driver. OpenOCD will then be able to communicate with the J-Link device.
OpenOCD does not have very frequent releases. The 0.11.0 release or newer should work for our purposes, but if you run into problems it may be worth building the very latest version of OpenOCD from source.
You can get the OpenOCD source code from their official GitHub mirror. The main OpenOCD repository is hosted on source forge, but the GitHub mirror is much more reliable.
After cloning the OpenOCD repository you can use the following commands on to build and install OpenOCD on Linux or macOS:
./bootstrap
./configure
make
make installYou will want to look at the output from the configure script carefully to make sure that support for CMSIS-DAP Compliant Debuggers and SEGGER J-Link Programmers is enabled (it should be by default unless you are missing required libraries).
This can also be done on Windows using MSYS2. Unfortunately it is not a particularly easy task, if you want to compile from source to Windows the easier approach is to cross compile for Windows from a Linux system.
There are a couple of other tools which you may want, depending on what programmer you are using.
Sometimes Segger J-Link debuggers can be unreliable when used with OpenOCD (particularly on Windows). If is possible to use Segger's own GDB server instead of OpenOCD, which works better in some circumstances. The J-Link GDB server is available as part of the "J-Link Software and Documentation Pack" at this site.
Note that on Window if you switch the driver used for the J-Link, as described above, the Segger J-Link GDB serve will not work. To get the J-Link GDB server working you will need to run its installer again.
Microchip PICkit 4 and MPLAB snap debuggers can be used to program the microcontroller, but are not compatible with OpenOCD. This means that it is not currently possible to use the Microchip debuggers with GDB. Instead, we use Microchip's MDB, which is modelled after GDB. MDB is available as part of Microchip's MPLAB X IDE, which can be found here. When installing MPLAB X, you may want to install the MPLAB IPE (Integrated Programming Environment) as well as the IDE, the IPE provides a graphical user interface over MDB for programming chips with Microchip tools.
If you are not comfortable with using Git from the command line and would prefer a graphical interface, you can try GitHubs graphical Git client, GitHub Desktop.
If you are familiar with VS Code on Windows and would like to use it for the CU InSpace avionics software, you can use the Remote - WSL extension to access the Windows Subsystem for Linux's shell from within VS Code.