Skip to content

Latest commit

 

History

History
286 lines (212 loc) · 10.4 KB

Getting_Started.md

File metadata and controls

286 lines (212 loc) · 10.4 KB
Raw

Tock Getting Started Guide

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

Requirements

  1. Rust

  2. rustup (version >= 1.23.0) to install Rust

  3. Host toolchain (gcc, glibc)

  4. Command line utilities: make, find

  5. A supported board or QEMU configuration.

    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.

    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.

Super Quick Setup

Nix:

$ nix-shell

MacOS:

$ curl https://sh.rustup.rs -sSf | sh
$ pip3 install --upgrade tockloader

Ubuntu:

$ apt install -y build-essential python3-pip curl
$ 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 boards/<platform> directory.

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-2023-07-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 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-2023-07-30

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).

  1. tockloader (version >= 1.0)

Tockloader is a Python application and can be installed with the Python package manager (pip).

(Linux): pip3 install --upgrade tockloader --user
(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. 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.
  • flash: Load code using JTAG, if available.
  • program: Load code using a bootloader, if available.

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

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 running:

$ make install

For some boards, you will need a programming adapter to flash code. Depending on the board and which adapter it supports, you will need either the free openocd or Segger's proprietary JLinkExe. Programming adapters are available as standalone devices (for example the JLink EDU JTAG debugger available on Digikey), but most development boards come with an onboard programming and debugging adapter. In that case, the board you use determines which software you will need and the Makefile in the board directory will know which one to call. Again, the board-specific READMEs provide the required details.

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:

(Linux/Debian): sudo apt-get install openocd
(MacOS): brew install open-ocd

We require at least version 0.8.0 to support the SAM4L on imix if you choose to flash it using an adapter instead of the bootloader. Some boards (at the time of writing the HiFive1 RISC-V board) may require newer or unreleased versions, in that case you should follow the installation instructions on the openocd website.

(Linux): Adding a udev rule

Depending on which programming adapter you use, you may want to add a udev rule in /etc/udev/rules.d that allows you to interact with the board as a user instead of as root. If you install the deb packet of the JLink software it will automatically install a /etc/udev/rules.d/99-jlink.rules that allows everyone to access the adapter. If you use something else, like for example the onboard programmer of a ST Nucleo board, you could install something like this as /etc/udev/rules.d/99-stlinkv2-1.rules:

# stm32 nucleo boards, with onboard st/linkv2-1
# ie, STM32F0, STM32F4.
# STM32VL has st/linkv1, which is quite different

SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", \
    MODE:="0660", GROUP="dialout", \
    SYMLINK+="stlinkv2-1_%n"

Installing your first application

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 (if you are using a board that is supported by tockloader).

For certain boards (e.g. Hail and imix), tockloader can read attributes from the board to configure how it communicates with the board. For many boards, however, tockloader cannot know which board and communication method you want to use, so you have to tell it explicitly. For example:

$ tockloader install --board nrf52dk --jlink blink
Could not find TAB named "blink" locally.

[0]     No
[1]     Yes

Would you like to check the online TAB repository for that app?[0] 1
Installing apps on the board...
Using known arch and jtag-device for known board nrf52dk
Finished in 2.567 seconds

Boards that use openocd will of course require the parameter --openocd instead of --jlink. If your board has a serial bootloader, tockloader should work without any additional arguments:

$ tockloader install blink

However, you can specify the board type manually as well:

$ tockloader install --board imix blink

You can also tell it which serial port to use (which is useful if you have multiple boards plugged in) by passing it the --port parameter like --port /dev/ttyACM0 to use /dev/ttyACM0:

$ tockloader --port /dev/ttyACM0 install blink

To see the list of boards tockloader knows about you can run:

$ tockloader list-known-boards

If everything has worked until here, the LEDs on your board should now display a binary counter. Congratulations, you have a working TockOS installation on your board!

Compiling applications

The last remaining step is to compile applications locally. All user-level code lives in two separate repositories:

The C version of the Tock library and the example applications is older and more stable, so it is a good idea to look at these first. So look at the libtock-c README and follow the steps therein. Then you can do the same for the libtock-rs README. This should give you a first impression of how to build and deploy applications for TockOS.

For an introduction on how applications work in TockOS, have a look at the "Userland" document in this directory.

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.