Building Your First Tock App

Setting up the Toolchain

The Tock kernel requires the following toolchain:

• Rust nightly (install rustup so the Tock buildsystem will choose the right version automatically)

• Xargo (Rust cargo wrapper that installs core library for embedded targets)

• arm-none-eabi toolchain (version >= 5.2)

• tockbootloader (version >= 0.6.1)

• Standard command line utilities: wget, sed, make

Installing Rust (nightly)

We are using rustc 1.19.0-nightly (f1140a331 2017-05-08) . 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-2017-05-09

Xargo

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

arm-none-eabi toolchain

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.

MacOS

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

Linux

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.

Ubuntu:

$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
$ sudo apt-get update
$ sudo apt-get install gcc-arm-embedded

Arch Linux:

$ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib arm-none-eabi-gdb

Windows:

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 are some unexpected pitfalls.

Installing tockbootloader

$ pip3 install tockloader --user

If you want tab completions:

$ register-python-argcomplete tockloader >> ~/.bashrc

Compiling the Kernel

Grab the Tock kernel from GitHub:

$ git clone git://github.com/helena-project/tock 

To build the kernel, just type make in the project root directory.

The root Makefile selects a board and architecture to build the kernel for and routes all calls to that board's specific Makefile. The root Makefile is set up with the following defaults:

TOCK_BOARD ?= hail

Thus it compiles for the Hail board by default.

$ make
make -C boards/hail/
make[1]: Entering directory '/var/local/alevy/hack/helena/tock/boards/hail'
info: component 'rust-src' is up to date
  Compiling hail v0.1.0 (file:///var/local/alevy/hack/helena/tock/boards/hail)
  Compiling kernel v0.1.0 (file:///var/local/alevy/hack/helena/tock/kernel)
  Compiling capsules v0.1.0 (file:///var/local/alevy/hack/helena/tock/capsules)
  Compiling cortexm4 v0.1.0 (file:///var/local/alevy/hack/helena/tock/arch/cortex-m4)
  Compiling sam4l v0.1.0 (file:///var/local/alevy/hack/helena/tock/chips/sam4l)
   Finished release [optimized] target(s) in 8.19 secs
  text    data     bss     dec     hex filename
 83332    4936   60592  148860   2457c target/thumbv7em-none-eabi/release/hail
make[1]: Leaving directory '/var/local/alevy/hack/helena/tock/boards/hail'
make  10.16s user 0.23s system 122% cpu 8.491 total

Programming the Kernel onto the Hail

Connect your Hail board to your computer with a micro-USB cable. tockbootloader should do all the rest, including identifying which serial port the board is connected to:

$ make program 

Which, under the hood, is really just running tockloader like this:

$ tockloader flash --address 0x10000 boards/hail/target/thumbv7em-none-eabi/release/hail.bin

Writing the Blink App

Create a new directory for your app, with a Makefile and main.c.

The Makefile uses boilerplate Makefile rules from the Tock userland library, and only needs to specify which C files to compile and a package name (which defaults to the directory name):

TOCK_USERLAND_BASE_DIR = /path/to/tock/project/root/userland

# Which files to compile.
C_SRCS := $(wildcard *.c)

PACKAGE_NAME := blink

# Include userland master makefile. Contains rules and flags for actually
# building the application.
include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk

A simple blink app is pretty straight-forward, and can be written in just a few lines in main.c:

#include <led.h>
#include <timer.h>
int main(void) {
 for (;;) {
   led_toggle(0);
   delay_ms(500);
 }
}

Of course, you can get fancier if you want. The led.h header exposes the functions led_on and led_off which, given an index of an LED on the board turns it on or off respectively, as well as led_count() which returns the total number of LEDs on the board. So get creative!

To build the app, simple run

$ make

This will build the app and create a Tock Binary (.tbf) for several supported architectures and create a cross-board Tock Archive Binary (.tab).

Programming the Blink App onto the Hail

First, for simplicity, make sure there are no other apps on the board:

$ tockloader erase-apps

Then, install the blink app

$ tockloader install build/blink.tab

And your done! You should see a red LED blinking once a second!