github.com/usbarmory/tamago @v1.26.4 sqlite
README
TamaGo - bare metal Go
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Introduction
TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal processors (AMD64, ARM, ARM64, RISCV64).
The projects spawns from the desire of reducing the attack surface of embedded systems firmware by removing any runtime dependency on C code and Operating Systems.
The TamaGo framework consists of the following components:
-
A modified Go distribution which extends
GOOSsupport to thetamagotarget, allowing bare metal execution through a runtime/goos overlay set byGOOSPKG. -
Go packages for processor/SoC support.
-
Go packages for board support.
The modifications are minimal against the original Go compiler, runtime and the target application (one import required), with a clean separation from other architectures.
Strong emphasis is placed on code re-use from existing architectures already included within the standard Go runtime, see Internals.
The modifications maintain complete standard library support.
Such aspects are motivated by the desire of providing a framework that allows secure Go firmware development on embedded systems.
Current releases
The following links are the latest releases for the
TamaGo modified Go distribution,
which adds GOOS=tamago support to the corresponding Go version, and
TamaGo library:
Documentation
The main documentation can be found on the project wiki.
The package API documentation can be found on pkg.go.dev.
Supported AMD64 targets
The following table summarizes currently supported x86-64 targets
(GOOS=tamago GOARCH=amd64).
| CPU | Platform | CPU package | Platform package |
|---|---|---|---|
| AMD/Intel 64-bit | Cloud Hypervisor | amd64 | cloud_hypervisor/vm |
| AMD/Intel 64-bit | Firecracker microvm | amd64 | firecracker/microvm |
| AMD/Intel 64-bit | QEMU microvm | amd64 | qemu/microvm |
| AMD/Intel 64-bit | UEFI | amd64 | uefi/x64 |
| AMD/Intel 64-bit | Google Compute Engine | amd64 | google/gcp, uefi/x64 |
Supported ARM targets
The following table summarizes currently supported ARM SoCs and boards
(GOOS=tamago GOARCH=arm).
| 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 | mx6ullevk |
| Broadcom BCM2835 | Raspberry Pi Zero | bcm2835 | pi/pizero |
| Broadcom BCM2835 | Raspberry Pi 1 Model A+ | bcm2835 | pi/pi1 |
| Broadcom BCM2835 | Raspberry Pi 1 Model B+ | bcm2835 | pi/pi1 |
| Broadcom BCM2836 | Raspberry Pi 2 Model B | bcm2835 | pi/pi2 |
Supported ARM64 targets
The following table summarizes currently supported ARM64 SoCs and boards
(GOOS=tamago GOARCH=arm64).
| SoC | Board | SoC package | Board package |
|---|---|---|---|
| NXP i.MX8M Plus | 8MPLUSLPD4-EVK | imx8mp | imx8mpevk |
| Microchip LAN969x | EVB-LAN9696-24port | lan969x | lan9696evb |
Supported RISC-V targets
The following table summarizes currently supported RISC-V SoCs and boards
(GOOS=tamago GOARCH=riscv64).
| SoC | Board | SoC package | Board package |
|---|---|---|---|
| SiFive FU540 | QEMU sifive_u | fu540 | qemu/sifive_u |
| AI Foundry Erbium | erbium_emu | erbium | erbium_emu |
| AI Foundry ET-SoC-1 | sys_emu | etsoc1 | sys_emu |
Userspace targets
The execution of programs compiled with GOOS=tamago can also take place in
user space by importing any package that implements the required runtime/goos
overlay with OS supervision instead of bare metal drivers.
Compiling and running Go programs in user space as GOOS=tamago provides the
benefit of system call isolation as the executable cannot leverage on the Go
runtime to directly access OS resources, this results in:
- isolation from OS file system, through in-memory emulated disk
- isolation from OS networking, see net.SocketFunc
- API for custom networking, rng, time handlers
The following table summarizes currently available userspace support:
| Operating System | GOARCH |
Runtime packages |
|---|---|---|
| Linux | amd64,arm,arm64,riscv64 | runtime/goos¹ |
| Linux | amd64,arm,arm64,riscv64 | linux |
| GoTEE | arm,riscv64 | applet |
¹ Used to run standard distribution tests and go test -tags user_linux
Compiling
Go distribution supporting GOOS=tamago
The tamago
command downloads, compiles, and runs the go command from the
TamaGo distribution matching the
tamago module version from the application go.mod.
Applications can add github.com/usbarmory/tamago to go.mod, and then
replace the go command with:
go run github.com/usbarmory/tamago/cmd/tamago
or add the following line to go.mod to use go tool tamago as go command:
tool github.com/usbarmory/tamago/cmd/tamago
Alternatively the latest TamaGo distribution can be manually built or the latest binary release can be used:
```sh w
Extension points exported contracts — how you extend this code
Board (Interface)Core symbols most depended-on inside this repo
WriteShape
Languages
Modules by API surface
For agents
$ claude mcp add tamago \
-- python -m otcore.mcp_server <graph>