https://github.com/usbarmory/tamago
TamaGo - bare metal Go
https://github.com/usbarmory/tamago
Last synced: 28 days ago
JSON representation
TamaGo - bare metal Go
- Host: GitHub
- URL: https://github.com/usbarmory/tamago
- Owner: usbarmory
- License: bsd-3-clause
- Created: 2019-10-24T09:51:55.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-18T14:16:58.000Z (12 months ago)
- Last Synced: 2025-03-18T15:30:36.764Z (12 months ago)
- Language: Go
- Homepage:
- Size: 1.28 MB
- Stars: 1,394
- Watchers: 35
- Forks: 55
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-SGX-Open-Source - https://github.com/usbarmory/tamago
- awesome-repositories - usbarmory/tamago - TamaGo - bare metal Go (Go)
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](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/tamagoo/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) |
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) |
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](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) |
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
=========
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
```
Additionally 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"
)
```
Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go)
(or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)):
```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
```
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 USB armory Mk II
GOOS=tamago GOARM=7 GOARCH=arm ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go
# Example for 8MPLUSLPD4-EVK
GOOS=tamago GOARCH=arm64 ${TAMAGO} build -ldflags "-T 0x40010000 -R 0x1000" main.go
# Example for QEMU RISC-V sifive_u
GOOS=tamago GOARCH=riscv64 ${TAMAGO} build -ldflags "-T 0x80010000 -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`
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
External drivers using TamaGo
=============================
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - i.MX Serial over USB driver
* [imx-usbnet](https://github.com/usbarmory/imx-usbnet) - i.MX Ethernet over USB driver
* [imx-enet](https://github.com/usbarmory/imx-enet) - i.MX Ethernet driver
* [virtio-net](https://github.com/usbarmory/virtio-net) - VirtIO Network driver
* [go-net](https://github.com/usbarmory/go-net) - Generic Network 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))
* [TamaGo presentation](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago)
* [ArmoredWitness presentation](https://github.com/abarisani/abarisani.github.io/tree/master/research/witness)
Maintainers
===========
Andrea Barisani
andrea@inversepath.com
Andrej Rosano
andrej@inversepath.com
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.