Getting_Started.md

Tock Getting Started Guide

This covers how to install the toolchain on your platform to start using and developing Tock.

• Super Quick Setup to Build the Tock Kernel
• Detailed Setup for Building the Tock Kernel
  • Installing Requirements
    • Rust (nightly)
  • Compiling the Kernel
• Hardware and Running Tock
  • Tockloader
  • Programming Adapter
    • Installing JLinkExe
    • Installing openocd
  • Loading the Kernel onto a Board
• Installing Applications
  • Compiling Your Own Applications
• Developing TockOS
  • Formatting Rust source code
  • Keeping build tools up to date

Super Quick Setup to Build the Tock Kernel

If you just want to get started quickly, follow these steps for your environment:

MacOS:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ pipx install tockloader
$ pipx ensurepath

Ubuntu:

$ sudo apt install -y build-essential python3-pip curl
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ pipx install tockloader
$ pipx ensurepath
$ grep -q dialout <(groups $(whoami)) || sudo usermod -a -G dialout $(whoami) # Note, will need to reboot if prompted for password

Nix:

$ nix-shell

Then build the kernel by running make in the boards/<platform> directory.

Detailed Setup for Building the Tock Kernel

To build the Tock kernel, you will need:

1. Rust
2. rustup (version >= 1.23.0) to install Rust
3. Host toolchain (gcc, glibc)
4. Command line utilities: make, find

Installing Requirements

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.

Rust (nightly)

We are using nightly-2024-05-26. We require installing it with rustup so you can manage multiple versions of Rust and continue using stable versions for other Rust code:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | 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-2024-05-26

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. e.g. cd boards/nordic/nrf52840dk ; 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.
• install: Load the kernel onto the board.

The board-specific READMEs in each board's subdirectory provide more details for each platform.

Hardware and Running Tock

To run the Tock kernel you need:

1. A supported board or QEMU configuration
2. Tockloader
3. A programming adapter for loading code (required for most boards)

If you are just starting to work with TockOS, you should look in the boards/ subdirectory and choose one of the options with tockloader support to load applications, as that is the configuration that most examples and tutorials assume.

If you do not have a supported hardware board, Tock has some limited support for running the kernel in QEMU. As of 01/08/2020, the SiFive HiFive1 RISC-V Board can be tested in QEMU.

Note: QEMU support in Tock is in the early stages. Please be sure to check whether and how QEMU is supported for a board based on the table in the boards/ subdirectory. The make ci-job-qemu target is the authority on QEMU support.

Tockloader

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 is a Python application and can be installed with the Python package manager for executables (pipx):

$ pipx install tockloader
$ pipx ensurepath

Programming Adapter

For some boards, you will need a programming adapter to flash code. Check the "Interface" column in the boards README for the board you have to see what the default programming adapter you need is. There are generally four options:

1. Bootloader: This means the board supports the Tock bootloader and you do not need any special programming adapter. Tockloader has built-in support.
2. jLink: This is a proprietary tool for loading code onto microcontrollers from Segger. You will need to install this if you do not already have it. See the instructions below.
3. openocd: This is a free programming adapter which you will need to install if you do not already have it. See the instructions below.
4. custom: The board uses some other programming adapter, likely a microcontroller-specific tool. See the board's README for how to get started.

Installing JLinkExe

JLink is available from the Segger website. You want to install the "J-Link Software and Documentation Pack". There are various packages available depending on operating system. We require a version greater than or equal to 5.0.

Installing openocd

Openocd works with various programming and debugging adapters. For most purposes, available distribution packages are sufficient and it can be installed with:

(Ubuntu): sudo apt-get install openocd
(MacOS): brew install open-ocd

We require at least version 0.10.0.

Loading the Kernel onto a Board

The process to load the kernel onto the board depends on the board. You should be able to program the kernel by changing to the correct board directory in tock/boards/ and running:

$ make install

Installing Applications

A kernel alone isn't much use, as an embedded developer you want to see some LEDs blink. Fortunately, there is an example blink app available from the TockOS app repository which tockloader can download and install.

To install blink, run:

$ tockloader install blink

Tockloader will automatically detect your board, download the app from the Tock website, and flash it for you.

If everything went well, the LEDs on your board should now display a binary counter. Congratulations, you have a working TockOS installation on your board!

Compiling Your Own Applications

You can also compile applications locally. All user-level code lives in two separate repositories:

• libtock-c: C and C++ apps.
• libtock-rs: Rust apps.

You can use either version by following the steps in their respective READMEs: libtock-c README and libtock-rs README.

Developing TockOS

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 rustc and 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.