This covers how to get the toolchain setup on your platform to start using and developing Tock.
- Rust (install
rustup
so Tock will choose the right version automatically) - Xargo (Rust
cargo
wrapper that installs core library for embedded targets) - arm-none-eabi toolchain (version >= 5.2)
- Command line utilities: wget, sed, make, cmake
MacOS:
$ curl https://sh.rustup.rs -sSf | sh
$ brew tap ARMmbed/homebrew-formulae && brew update && brew install arm-none-eabi-gcc
$ pip3 install tockloader
Ubuntu:
$ curl https://sh.rustup.rs -sSf | sh
$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa && sudo apt update && sudo apt install gcc-arm-embedded
$ pip3 install tockloader --user
$ grep -q dialout <(groups $(whoami)) || sudo usermod -a -G dialout $(whoami) # Note, will need to reboot if prompted for password
Then build the kernel by running make
in the boards/<platform>
directory.
These steps go into a little more depth. Note that the build system is capable of installing some of these tools, but you can also install them yourself.
We are using rustc 1.24.0-nightly (8e7a609e6 2018-01-04)
. We recommend
installing it with rustup so you can manage multiple
versions of Rust and continue using stable versions for other Rust code:
$ curl https://sh.rustup.rs -sSf | sh
This will install rustup
in your home directory, so you will need to
source ~/.profile
or open a new shell to add the .cargo/bin
directory
to your $PATH
.
Then install the correct nightly version of Rust:
$ rustup install nightly-2018-03-07
Rust core libraries for ARM Cortex-M target do not come with rustup
by
default, so we use xargo
, a wrapper
around cargo
, which compiles these libraries.
$ cargo install xargo
We generally track the latest version of arm-none-eabi-gcc as released by ARM.
There are known issues with arm-none-eabi-gcc version 5.1 and older, or other
versions packaged with a newlib version earlier than 2.3, as they will run into
problems with missing ARM intrinsics (e.g., __aeabi_memclr
). Tock does not
support these versions.
Pre-compiled binaries are available from ARM. The recommendations below will set up your operating system's package manager to track the latest release from ARM.
With Homebrew (preferred):
$ brew tap ARMmbed/homebrew-formulae
$ brew update
$ brew install arm-none-eabi-gcc
or with MacPorts:
$ port install arm-none-eabi-gcc
The make debug
target asks the Tock build system to generate a listings
(disassembly) file. Some developers have noticed that arm-none-eabi-objdump
takes a long time (order several minutes) on a mac while Activity Monitor
reports that opendirectoryd
pegs the CPU.
This is a known issue that you can
resolve by commenting out the /home
line from /etc/auto_master
and then
running sudo automount -vc
to apply the changes.
If you install the binaries but get a "no such file or directory" error when trying to run them, then you are most likely missing needed libraries. Check that you have a 64-bit version of libc installed.
$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
$ sudo apt update
$ sudo apt install gcc-arm-embedded
On Arch Linux the arm-none-eabi-newlib
package in pacman contains a
sufficiently up-to-date version of newlibc.
$ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib arm-none-eabi-gdb
You can download precompiled binaries for Windows from the ARM site listed above. While we expect things should work on Windows, none of the active Tock developers currently develop on Windows, so it is possible that there are some unexpected pitfalls.
Alternatively, if you would like simulator mode in arm-none-eabi-gdb
,
you can use the build scripts in the tools
directory, in this order:
build-arm-binutils
then build-arm-gcc
then build-arm-gdb
.
Tock builds a unique kernel for every board it supports. Boards include
details like pulling together the correct chips and pin assignments. To
build a kernel, first choose a board, then navigate to that board directory.
e.g. cd boards/hail ; make
.
Some boards have special build options that can only be used within the board's directory. All boards share a few common targets:
all
(default): Compile Tock for this board.debug
: Generate build(s) for debugging support, details vary per board.doc
: Build documentation for this board.clean
: Remove built artifacts for this board.flash
: Load code using JTAG, if available.program
: Load code using a bootloader, if available.
The READMEs in each board provide more details for each platform.
All user-level code lives in the userland
subdirectory. This
includes a specially compiled version of newlib, a user-level library
for talking to the kernel and specific drivers and a variety of
example applications.
Compiled applications are architecture-specific (e.g. cortex-m4
,
cortex-m0
) since the compiler emits slightly different instructions
for each variant. Compiled applications can also depend on specific
drivers, which not all boards provide; if you load an application onto
a board that does not support every driver/system call it uses, some
system calls with return error codes (ENODEVICE
or ENOSUPPORT
).
Applications are built for all architectures Tock supports, currently
cortex-m0
and cortex-m4
. Boards select an appropriate architecture when
uploading code (e.g. cortex-m4
for the SAM4L on the imix
board).
To compile an app, cd
to the desired app and make
. For example:
$ cd userland/examples/blink/
$ make
This will build the app and generate a binary in Tock Binary Format
(using the elf2tbf
utility):
userland/examples/blink/build/cortex-m4/cortex-m4.bin
.
For some boards, currently Hail
and imix
, you will need tockloader
.
tockloader
also has features that are generally useful to all Tock boards,
such as easy to manage serial connections, and the ability to list, add,
replace, and remove applications over JTAG (or USB if a bootloader is
installed).
- tockloader (version >= 0.8)
Installing applications over JTAG, depending on your JTAG Debugger, you will need one of:
Tock requires tockloader
. To install:
(Linux): sudo pip3 install tockloader
(MacOS): pip3 install tockloader
Works with various JTAG debuggers. We require at least version 0.8.0
to
support the SAM4L on imix
.
(Linux): sudo apt-get install openocd
(MacOS): brew install open-ocd
If you want to upload code through a JLink JTAG
debugger (available on
Digikey), you should install JLinkExe. We require a version greater than or equal to 5.0
.
It is available here. You want to the "J-Link Software and Documentation Pack". There are various packages available depending on operating system.
This is generally done with make program
and make flash
, but is board
specific. To learn how to program your specific hardware, please see
the board specific READMEs:
Rust includes a tool for automatically formatting Rust source
code. This requires a cargo
tool:
$ cargo install rustfmt
Then run:
$ make format
to format the repository.