tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
https://foundry.withsecure.com
Andrea Barisani
[email protected] | [email protected]
Andrej Rosano
[email protected] | [email protected]
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/i.MX6UL | USB armory Mk II | imx6ul | usbarmory/mk2 |
| NXP i.MX6ULL/i.MX6UL | USB armory Mk II LAN | imx6ul | usbarmory/mk2 |
| NXP i.MX6ULL/i.MX6ULZ | MCIMX6ULL-EVK | imx6ul | nxp/mx6ullevk |
| SiFive FU540 | QEMU sifive_u | fu540 | qemu/sifive_u |
For more information about TamaGo see its repository and project wiki.
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).
- 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
On the USB armory Mk II the network interface is exposed over Ethernet over USB (ECM protocol, supported on Linux and macOS hosts).
On the USB armory Mk II LAN the network interface is exposed on both USB and physical Ethernet interfaces.
On 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 aftertestis 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):
9p # start 9p remote file server
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
dma (free|used)? # show allocation of default DMA region
dns <host> # resolve domain
ecdsa <sec> (soft)? # benchmark CAAM/DCP hardware signing
exit, quit # close session
freq (198|396|528|792|900) # change ARM core frequency
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
ls (path)? # list directory contents
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
ntp <host> # change runtime date and time via NTP
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
rtic (<hex start> <hex end>)? # start RTIC on .text and optional region
sha <size> <sec> (soft)? # benchmark CAAM/DCP hardware hashing
stack # goroutine stack trace (current)
stackall # goroutine stack trace (all)
tailscale <auth key> (verbose)? # start network servers on Tailscale tailnet
test # launch tests
usdhc <n> <hex offset> <size> # SD/MMC card read
wormhole (send <path>|recv <code>) # transfer file through magic wormhole
On emulated runs (e.g. make qemu) the console is exposed directly on the
terminal.
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
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).
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)
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
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.