TamaGo - bare metal Go for ARM/RISCV-V SoCs - example application

tamago | https://github.com/usbarmory/tamago

Copyright (c) WithSecure Corporation
https://foundry.withsecure.com

Authors

Andrea Barisani
[email protected] | [email protected]

Andrej Rosano
[email protected] | [email protected]

Introduction

TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal ARM/RISC-V System-on-Chip (SoC) components.

This example Go application illustrates use of the tamago package execute bare metal Go code on the following platforms:

SoC	Board	SoC package	Board package
NXP i.MX6ULZ	USB armory Mk II	imx6ul	usbarmory/mk2
NXP i.MX6ULL	MCIMX6ULL-EVK	imx6ul	nxp/mx6ullevk
SiFive FU540	QEMU sifive_u	fu540	qemu/sifive_u

Documentation

For more information about TamaGo see its repository and project wiki.

Operation

The example application performs a variety of simple test procedures, each in its separate goroutine, to demonstrate bare metal execution of Go standard and external libraries:

• Directory and file write/read from an in-memory filesystem.
• SD/MMC card detection and read (only on non-emulated runs).
• Timer operation.
• Sleep operation.
• Random bytes collection (gathered from SoC TRNG on non-emulated runs).
• ECDSA signing and verification.
• Test BTC transaction creation and signing.
• Test post-quantum key encapsulation (KEM).
• Hardware accelerated encryption, hashing, key derivation (on non-emulated runs).
• Large memory allocation.

The following network services are started:

• SSH server on 10.0.0.1:22
• HTTP server on 10.0.0.1:80
• HTTPS server on 10.0.0.1:443

For the USB armory Mk II the network interface is exposed over Ethernet over USB (ECM protocol, supported on Linux and macOS hosts).

For the MCIMX6ULL-EVK the second Ethernet port is used.

The web servers expose the following routes:

• /: a welcome message
• /tamago-example.log: log output
• /dir: in-memory filesystem test directory (available after test is issued)
• /debug/pprof: Go runtime profiling data through pprof
• /debug/statsviz: Go runtime profiling data through statsviz

The SSH server exposes a console with the following commands (i.MX6UL boards):

aes             <size> <sec> (soft)?                             # benchmark CAAM/DCP hardware encryption
bee             <hex region0> <hex region1>                      # BEE OTF AES memory encryption
ble                                                              # BLE serial console
date            (time in RFC339 format)?                         # show/change runtime date and time
dns             <fqdn>                                           # resolve domain (requires routing)
exit, quit                                                       # close session
help                                                             # this help
huk                                                              # CAAM/DCP hardware unique key derivation
i2c             <n> <hex target> <hex addr> <size>               # I²C bus read
info                                                             # device information
kem                                                              # benchmark post-quantum KEM
led             (white|blue) (on|off)                            # LED control
mii             <hex pa> <hex ra> (hex data)?                    # show/change eth PHY standard registers
mmd             <hex pa> <hex devad> <hex ra> (hex data)?        # show/change eth PHY extended registers
otp             <bank> <word>                                    # OTP fuses display
peek            <hex offset> <size>                              # memory display (use with caution)
poke            <hex offset> <hex value>                         # memory write   (use with caution)
rand                                                             # gather 32 random bytes
reboot                                                           # reset device
sha             <size> <sec> (soft)?                             # benchmark CAAM/DCP hardware hashing
stack                                                            # stack trace of current goroutine
stackall                                                         # stack trace of all goroutines
test                                                             # launch tests
usdhc           <n> <hex offset> <size>                          # SD/MMC card read

On emulated runs (e.g. make qemu) the console is exposed directly on the terminal.

Building the compiler

Build the TamaGo compiler (or use the latest binary release):

wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
unzip latest.zip
cd tamago-go-latest/src && ./all.bash
cd ../bin && export TAMAGO=`pwd`/go

Building and executing on ARM targets

Build the application executables as follows:

make imx TARGET=usbarmory

The following targets are available:

TARGET	Board	Executing and debugging
usbarmory	USB armory Mk II	usbarmory
mx6ullevk	MCIMX6ULL-EVK	mx6ullevk

The targets support native (see relevant documentation links in the table above) as well as emulated execution (e.g. make qemu).

Building and executing on RISC-V targets

Build the application executables as follows:

make TARGET=sifive_u

Available targets:

TARGET	Board	Executing and debugging
sifive_u	QEMU sifive_u	sifive_u

The target has only been tested with emulated execution (e.g. make qemu)

Emulated hardware with QEMU

All targets can be executed under emulation as follows:

make qemu

The emulation run will either provide an interactive console or emulated Ethernet connectivity, in the latter case tap0 should be configured as follows (Linux example):

ip addr add 10.0.0.2/24 dev tap0
ip link set tap0 up
ip tuntap add dev tap0 mode tap group <your user group>

An emulated target can be debugged with GDB using make qemu-gdb, this will make qemu waiting for a GDB connection that can be launched as follows:

# ARM targets
arm-none-eabi-gdb -ex "target remote 127.0.0.1:1234" example

# RISC-V targets
riscv64-elf-gdb -ex "target remote 127.0.0.1:1234" example

Breakpoints can be set in the usual way:

b ecdsa.Verify
continue

License

tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation

These source files are distributed under the BSD-style license found in the LICENSE file.

The TamaGo logo is adapted from the Go gopher designed by Renee French and licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector illustration by Hugo Arganda.

This is extended for t9. see p9/ for basic 9p access and fs/ for forth fs. t9 is the kernel.