usbarmory/tamagoFramework for compiling and executing Go applications on bare metal processors, enabling secure firmware development with reduced attack surface through OS and C dependency removal.
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.
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](https://github.com/usbarmory/tamago-go)
which extends `GOOS` support to the `tamago` target, allowing bare metal
execution through a [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)
overlay set by `GOOSPKG`.
- 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](https://github.com/usbarmory/tamago/wiki/Internals).
The modifications maintain [complete standard library support](https://github.com/usbarmory/tamago/wiki/Compatibility).
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](https://github.com/usbarmory/tamago-go),
which adds `GOOS=tamago` support to the corresponding Go version, and
[TamaGo library](https://github.com/usbarmory/tamago):
[](https://github.com/usbarmory/tamago-go/releases/latest) [](https://github.com/usbarmory/tamago-go/actions)
[](https://github.com/usbarmory/tamago/releases/latest)
Documentation
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
The main documentation can be found on the
[project wiki](https://github.com/usbarmory/tamago/wiki).
The package API documentation can be found on
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
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](https://www.cloudhypervisor.org ) | [amd64](https://github.com/usbarmory/tamago/tree/master/amd64) | [cloud_hypervisor/vm](https://github.com/usbarmory/tamago/tree/master/board/cloud_hypervisor/vm) |
| AMD/Intel 64-bit | [Firecracker microvm](https://firecracker-microvm.github.io) | [amd64](https://github.com/usbarmory/tamago/tree/master/amd64) | [firecracker/microvm](https://github.com/usbarmory/tamago/tree/master/board/firecracker/microvm) |
| AMD/Intel 64-bit | [QEMU microvm](https://www.qemu.org/docs/master/system/i386/microvm.html) | [amd64](https://github.com/usbarmory/tamago/tree/master/amd64) | [qemu/microvm](https://github.com/usbarmory/tamago/tree/master/board/qemu/microvm) |
| AMD/Intel 64-bit | [UEFI](https://uefi.org/) | [amd64](https://github.com/usbarmory/tamago/tree/master/amd64) | [uefi/x64](https://github.com/usbarmory/go-boot/tree/main/uefi/x64) |
| AMD/Intel 64-bit | [Google Compute Engine](https://cloud.google.com/products/compute) | [amd64](https://github.com/usbarmory/tamago/tree/master/amd64) | [google/gcp](https://github.com/usbarmory/tamago/tree/master/board/google/gcp), [uefi/x64](https://github.com/usbarmory/go-boot/tree/main/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](https://github.com/usbarmory/usbarmory/wiki/Mk-II-Introduction) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory) |
| NXP i.MX6ULL/i.MX6UL | [USB armory Mk II LAN](https://github.com/usbarmory/usbarmory/wiki/Mk-II-LAN) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory) |
| NXP i.MX6ULL/i.MX6ULZ | [MCIMX6ULL-EVK](https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/evaluation-kit-for-the-i-mx-6ull-and-6ulz-applications-processor:MCIMX6ULL-EVK) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [mx6ullevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/mx6ullevk) |
| Broadcom BCM2835 | [Raspberry Pi Zero](https://www.raspberrypi.org/products/raspberry-pi-zero) | [bcm2835](https://github.com/usbarmory/tamago/tree/master/soc/bcm2835) | [pi/pizero](https://github.com/usbarmory/tamago/tree/master/board/raspberrypi) |
| Broadcom BCM2835 | [Raspberry Pi 1 Model A+](https://www.raspberrypi.org/products/raspberry-pi-1-model-a-plus/) | [bcm2835](https://github.com/usbarmory/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/usbarmory/tamago/tree/master/board/raspberrypi) |
| Broadcom BCM2835 | [Raspberry Pi 1 Model B+](https://www.raspberrypi.org/products/raspberry-pi-1-model-b-plus/) | [bcm2835](https://github.com/usbarmory/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/usbarmory/tamago/tree/master/board/raspberrypi) |
| Broadcom BCM2836 | [Raspberry Pi 2 Model B](https://www.raspberrypi.org/products/raspberry-pi-2-model-b) | [bcm2835](https://github.com/usbarmory/tamago/tree/master/soc/bcm2835) | [pi/pi2](https://github.com/usbarmory/tamago/tree/master/board/raspberrypi) |
| Nuvoton NUC980 | [NuMaker-IIoT-NUC980G2](https://www.nuvoton.com/products/iot-solution/iot-platform/numaker-iiot-nuc980g2) | [nuc980](https://github.com/usbarmory/tamago/tree/master/soc/nuvoton/nuc980) | [nuc980iiot](https://github.com/usbarmory/tamago/tree/master/board/nuvoton/nuc980iiot) |
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](https://www.nxp.com/design/design-center/development-boards-and-designs/8MPLUSLPD4-EVK) | [imx8mp](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx8mp) | [imx8mpevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/imx8mpevk) |
| Microchip LAN969x | [EVB-LAN9696-24port](https://www.microchip.com/en-us/development-tool/ev23x71a) | [lan969x](https://github.com/usbarmory/tamago/tree/master/soc/microchip/lan969x) | [lan9696evb](https://github.com/usbarmory/tamago/tree/master/board/microchip/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 |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| AI Foundry Erbium | [erbium_emu](https://github.com/aifoundry-org/et-platform) | [erbium](https://github.com/usbarmory/tamago/tree/master/soc/aifoundry/erbium) | [erbium_emu](https://github.com/usbarmory/tamago/tree/master/board/aifoundry/erbium_emu) |
| AI Foundry ET-SoC-1 | [sys_emu](https://github.com/aifoundry-org/et-platform/tree/master/sw-sysemu) | [etsoc1](https://github.com/usbarmory/tamago/tree/master/soc/aifoundry/etsoc1) | [sys_emu](https://github.com/usbarmory/tamago/tree/master/board/aifoundry/sys_emu) |
| Fisilink FSL91030 | [MilkV Vega](https://milkv.io/vega) | [fsl91030](https://github.com/usbarmory/tamago/tree/master/soc/fisilink/fsl91030) | [vega](https://github.com/usbarmory/tamago/tree/master/board/milkv/vega) |
| Fisilink FSL91030 | [Nuclei QEMU](https://doc.nucleisys.com/nuclei_tools/qemu/index.html) | [fsl91030](https://github.com/usbarmory/tamago/tree/master/soc/fisilink/fsl91030) | [eval_soc](https://github.com/usbarmory/tamago/tree/master/board/nuclei/eval_soc) |
| SiFive FU540 | [QEMU sifive_u](https://www.qemu.org/docs/master/system/riscv/sifive_u.html) | [fu540](https://github.com/usbarmory/tamago/tree/master/soc/sifive/fu540) | [qemu/sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u) |
Supported LoongArch targets
===========================
The following table summarizes currently supported LoongArch SoCs and boards
(`GOOS=tamago GOARCH=loong64`).
| SoC | Board | SoC package | Board package |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| Loongson 3A5000 | [QEMU virt](https://www.qemu.org/docs/master/system/loongarch/virt.html) | [ls3a5000](https://github.com/usbarmory/tamago/tree/master/soc/loongson/ls3a5000) | [qemu/virt](https://github.com/usbarmory/tamago/tree/master/board/qemu/virt) |
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](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API for custom networking, rng, time handlers
The following table summarizes currently available userspace support:
| Operating System | `GOARCH` | Runtime packages |
|----------------------------------------------|-------------------------|--------------------------------------------------------------------------------------|
| [Linux](https://www.kernel.org/) | amd64,arm,arm64,riscv64 | [runtime/goos](https://github.com/usbarmory/tamago-go/blob/latest/src/runtime/goos)¹ |
| [Linux](https://www.kernel.org/) | amd64,arm,arm64,riscv64 | [linux](https://github.com/usbarmory/tamago/tree/master/user/linux) |
| [GoTEE](https://github.com/usbarmory/GoTEE/) | arm,riscv64 | [applet](https://pkg.go.dev/github.com/usbarmory/GoTEE/applet) |
¹ Used to run [standard distribution tests](https://github.com/usbarmory/tamago/wiki/Compatibility) and `go test -tags user_linux`
Compiling
=========
Go distribution supporting `GOOS=tamago`
---------------------------------------
The [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
command downloads, compiles, and runs the `go` command from the
[TamaGo distribution](https://github.com/usbarmory/tamago-go) 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:
```sh
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](https://github.com/usbarmory/tamago-go/tree/latest) can be
manually built or the
[latest binary release](https://github.com/usbarmory/tamago-go/releases/latest) can be used:
```sh
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 applications
---------------------
While compiling, the `GOOSPKG` Go environment variable must be set to enable
this library as overlay to support `GOOS=tamago`.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Go applications are required to import the relevant board package to ensure
that hardware initialization and runtime support take place:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Go applications can be compiled with the compiler built in the previous step,
with the addition of a few flags/variables:
```sh
# set this library as `runtime/goos` overlay
export GOOSPKG=github.com/usbarmory/tamago
# Example for Cloud Hypervisory, QEMU and Firecracker KVMs
GOOS=tamago GOARCH=amd64 ${TAMAGO} build -ldflags "-T 0x10010000 -R 0x1000" main.go
# Example for NXP i.MX6UL
GOOS=tamago GOARM=7 GOARCH=arm ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go
# Example for NXP 8MPLUSLPD4-EVK
GOOS=tamago GOARCH=arm64 ${TAMAGO} build -ldflags "-T 0x40010000 -R 0x1000" main.go
# Example for SiFive FU540
GOOS=tamago GOARCH=riscv64 ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go
# Example for AI Foundry Erbium
GOOS=tamago GOARCH=riscv64 GOEXPERIMENT=softfloat ${TAMAGO} build -ldflags "-T 0x40010000 -R 0x1000" main.go
# Example for QEMU LoongArch virt
GOOS=tamago GOARCH=loong64 ${TAMAGO} build -ldflags "-T 0x1000000 -R 0x1000" main.go
# Example for Linux userspace
GOOS=tamago ${TAMAGO} build main.go
```
See the respective board package README file for compilation information for
each specific target.
Build tags
==========
The following build tags allow applications to override the package own
definition for the `runtime/goos` overlay:
* `linkramstart`: override `ramStart`
* `linkramsize`: override `ramSize`
* `linkprintk`: override `printk`
* `linkcpuinit`: override `cpuinit`
* `tiny`: reduce heap allocation requirements
Executing and debugging
=======================
See the respective board package README file for execution and debugging
information for each specific target (real or emulated).
The [example application](https://github.com/usbarmory/tamago-example)
provides sample driver usage and instructions for native as well as emulated
execution.
An emulated run of the [example application](https://github.com/usbarmory/tamago-example)
can be launched as follows:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Applications using TamaGo
=========================
* [go-boot](https://github.com/usbarmory/go-boot) - the bare metal Go UEFI boot manager
* [GoKey](https://github.com/usbarmory/GoKey) - the bare metal Go smartcard
* [GoTEE](https://github.com/usbarmory/GoTEE) - Go Trusted Execution Environment
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - cross-ecosystem witness network
* [armory-drive](https://github.com/usbarmory/armory-drive) - USB encrypted drive
* [armory-ums](https://github.com/usbarmory/armory-ums) - USB Mass Storage firmware
* [armory-boot](https://github.com/usbarmory/armory-boot) - USB armory boot loader
* [tamago-example](https://github.com/usbarmory/tamago-example) - TamaGo example application
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - Confidential VM (AMD SEV-SNP) example
* [kotama](https://github.com/usbarmory/kotama) - Tiny RISC-V target demonstrator
* [kanzashi](https://github.com/abarisani/kanzashi) - Bare Metal Agent
External drivers using TamaGo
=============================
* [go-net](https://github.com/usbarmory/go-net) - Generic Network driver
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - i.MX Ethernet over USB driver
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - VirtIO Network driver
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - i.MX Serial over USB driver
Additional resources
====================
* [Package API](https://pkg.go.dev/github.com/usbarmory/tamago)
* [Runtime API](https://github.com/usbarmory/tamago-go/blob/latest/src/runtime/goos/README.md)
* [Compatibility](https://github.com/usbarmory/tamago/wiki/Compatibility)
* [Internals](https://github.com/usbarmory/tamago/wiki/Internals)
* [FAQ](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ))
* Presentations: [TamaGo](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago), [ArmoredWitness](https://github.com/abarisani/abarisani.github.io/tree/master/research/witness)
Maintainers
===========
Andrea Barisani
[email protected]
Andrej Rosano
[email protected]
License
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
This project is distributed under the BSD-style license found in the
[LICENSE](https://github.com/usbarmory/tamago/blob/master/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.