tamago | https://github.com/usbarmory/tamago
Andrea Barisani
[email protected]
Andrej Rosano
[email protected]
TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal processors (AMD64, ARM, ARM64, RISCV64).
This example Go application illustrates use of the tamago package execute bare metal Go code on the following platforms:
| Processor | Platform | SoC/CPU package | Support package |
|---|---|---|---|
| AMD/Intel 64-bit | Cloud Hypervisor | amd64 | cloud_hypervisor/vm |
| AMD/Intel 64-bit | QEMU microvm | amd64 | qemu/microvm |
| AMD/Intel 64-bit | Firecracker microvm | amd64 | firecracker/microvm |
| 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 |
| NXP i.MX8M Plus | 8MPLUSLPD4-EVK | imx8mp | imx8mpevk |
| 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, if available).
- 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 (on non-emulated runs, if available).
- 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
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
build # build information
cat <path> # show file contents
cpuidle (on|off)? # CPU idle time management control
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
hab <srk table hash> # HAB activation (use with extreme caution)
halt # halt the machine
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
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
TARGET |
Platform | Executing and debugging | Interface |
|---|---|---|---|
cloud_hypervisor |
Cloud Hypervisor | cloud_hypervisor/vm | VirtIO networking¹ |
firecracker |
Firecracker microvm | firecracker/microvm | VirtIO networking¹ |
microvm |
QEMU microvm | qemu/microvm | VirtIO networking¹ |
microvm |
Google Compute Engine | tools | WiP (serial only) |
¹ network configuration example in Emulated hardware with QEMU
These targets are meant for paravirtualized execution as described in the following sections.
make example TARGET=cloud_hypervisor
cloud-hypervisor --kernel example --cpus boot=4 --memory size=4096M --net "tap=tap0" --serial tty --console off --seccomp false
Example shown via firectl:
make example TARGET=firecracker
firectl --kernel example --root-drive /dev/null --tap-device tap0/06:00:AC:10:00:01 -c 4 -m 4096
make qemu TARGET=microvm SMP=4
The microvm target can be executed on Google Compute Engine, see
tools for more information.
TARGET |
Board | Executing and debugging | Interface |
|---|---|---|---|
usbarmory |
USB armory Mk II | usbarmory | Ethernet over USB |
usbarmory |
USB armory Mk II LAN | usbarmory | Ethernet over USB, LAN |
mx6ullevk |
MCIMX6ULL-EVK | mx6ullevk | LAN (2nd port) |
Build the application executables as follows:
make imx TARGET=usbarmory
The targets support native (see relevant documentation links in the table above)
as well as emulated execution (e.g. make qemu).
TARGET |
Board | Executing and debugging | Interface |
|---|---|---|---|
imx8mpevk |
8MPLUSLPD4-EVK | imx8mpevk | LAN (1st port) |
Warning
This package is in early development stages, only emulated runs (qemu) have been tested.
Build and run the application executables as follows:
make qemu TARGET=imx8mpevk
TARGET |
Board | Executing and debugging | Interface |
|---|---|---|---|
sifive_u |
QEMU sifive_u | sifive_u | Serial console |
Build and run the application executables as follows:
make qemu TARGET=sifive_u
QEMU supported 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 tuntap add dev tap0 mode tap group <your user group>
ip addr add 10.0.0.2/24 dev tap0
ip link set tap0 up
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:
# path should be adjusted on cross platforms (e.g. arm-none-eabi-gdb)
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) The TamaGo Authors. All Rights Reserved.
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.