Tock Getting Started Guide
This covers how to install the toolchain on your platform to start using and developing Tock.
Super Quick Setup
$ curl https://sh.rustup.rs -sSf | sh $ pip3 install --upgrade tockloader
$ curl https://sh.rustup.rs -sSf | sh $ pip3 install --upgrade 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
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
nightly-2018-11-30. We require
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
~/.profile or open a new shell to add the
Then install the correct nightly version of Rust:
$ rustup install nightly-2018-11-30
tockloader programs the kernel and applications onto boards, and also has
features that are generally useful for all Tock boards, such as easy-to-manage
serial connections, along with the ability to list, add, replace, and remove
applications over JTAG (or USB if a bootloader is installed).
- tockloader (version >= 1.0)
Tockloader is a Python application and can be installed with the Python package manager (pip).
(Linux): sudo pip3 install --upgrade tockloader (MacOS): pip3 install --upgrade tockloader
Compiling the Kernel
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.
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 separate repositories:
Compiled applications are architecture-specific (e.g.
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 (
Applications are built for all architectures Tock supports. Boards select an
appropriate architecture when uploading code (e.g.
cortex-m4 for the SAM4L on
imix board). Apps are packaged into .tab files that contain compiled
binaries for all supported architectures.
Loading the kernel and applications onto a board
To load a kernel onto a board using a serial bootloader, run
$ make program
in the board's directory. To load the kernel using JTAG, run
$ make flash
Tockloader can help with installing a test app. For example, to install
blink app, simply run:
$ tockloader install blink
This will fetch it from the TockOS app repository and load it onto the board.
Some boards in Tock support other tools to load code and debug.
Works with various JTAG debuggers. We require at least version
support the SAM4L on
(Linux): sudo apt-get install openocd (MacOS): brew install open-ocd
It is available here. You want to install the "J-Link Software and Documentation Pack". There are various packages available depending on operating system.
Loading code onto a board
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.
Formatting Rust source code
Rust includes a tool for automatically formatting Rust source code. Simply run:
$ make format
from the root of the repository to format all rust code in the repository.
Keeping build tools up to date
Occasionally, Tock updates to a new nightly version of Rust. The build system
automatically checks whether the versions of
rustup are correct
for the build requirements, and updates them when necessary. After the
installation of the initial four requirements, you shouldn't have to worry
about keeping them up to date.