tamago

module

v0.0.0-...-1cacaac Latest Latest Go to latest Published: Dec 6, 2024 License: BSD-3-Clause

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/usbarmory/tamago

README ¶

TamaGo - bare metal Go for AMD64/ARM/RISC-V processors

tamago | https://github.com/usbarmory/tamago

Copyright (c) WithSecure Corporation
https://foundry.withsecure.com

TamaGo gopher

Introduction

TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal AMD64/ARM/RISC-V 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 which extends GOOS support to the tamago target, allowing bare metal execution.
Go packages for SoC driver 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 release level

The current release for the TamaGo modified Go distribution is tamago1.23.4, which adds GOOS=tamago support to go1.23.4.

Binary releases for amd64 and armv7l Linux hosts are available.

Documentation

The main documentation can be found on the project wiki.

The package API documentation can be found on pkg.go.dev.

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 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

Supported AMD64 targets

The support for an actual target is work-in-progress, the testing environment is supported and all Go standard library packages are supported and tested using original distribution tests.

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 changes 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,riscv64	linux
Linux	amd64,arm,riscv64	testing¹
GoTEE	arm,riscv64	applet

¹ Used to run standard distribution tests

Compiling

Go applications are simply required to import, the relevant board package to ensure that hardware initialization and runtime support takes place:

import (
	// Example for USB armory Mk II
	_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)

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

Go applications can be compiled with the compiler built in the previous step, with the addition of a few flags/variables:

# Example for USB armory Mk II
GOOS=tamago GOARM=7 GOARCH=arm ${TAMAGO} build -ldflags "-T 0x80010000 -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.

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 provides sample driver usage and instructions for native as well as emulated execution.

An emulated run of the example application can be launched as follows:

git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu

Applications using TamaGo

GoKey - the bare metal Go smartcard
GoTEE - Go Trusted Execution Environment
ArmoredWitness - cross-ecosystem witness network
armory-drive - USB encrypted drive
armory-ums - USB Mass Storage firmware
armory-boot - primary bootloader
tamago-example - TamaGo example application

External drivers using TamaGo

imx-usbserial - i.MX Serial over USB driver
imx-usbnet - i.MX Ethernet over USB driver
imx-enet - i.MX Ethernet driver

Additional resources

Maintainers

Andrea Barisani
andrea.barisani@withsecure.com | andrea@inversepath.com

Andrej Rosano
andrej.rosano@withsecure.com | andrej@inversepath.com

License

tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation

This project is 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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
arm Package arm provides support for ARM architecture specific operations.	Package arm provides support for ARM architecture specific operations.
gic Package gic implements a driver for the ARM Generic Interrupt Controller.	Package gic implements a driver for the ARM Generic Interrupt Controller.
tzc380 Package tzc380 implements a driver for the ARM TrustZone Address Space Controller TZC-380.	Package tzc380 implements a driver for the ARM TrustZone Address Space Controller TZC-380.
bits Package bits provides primitives for bitwise operations on 32/64 bit registers.	Package bits provides primitives for bitwise operations on 32/64 bit registers.
board
nxp/mx6ullevk Package mx6ullevk provides hardware initialization, automatically on import, for the NXP MCIMX6ULL-EVK evaluation board.	Package mx6ullevk provides hardware initialization, automatically on import, for the NXP MCIMX6ULL-EVK evaluation board.
qemu/sifive_u Package sifive_u provides hardware initialization, automatically on import, for the QEMU sifive_u machine configured (see the `dts` file in this directory) with a single U54 core.	Package sifive_u provides hardware initialization, automatically on import, for the QEMU sifive_u machine configured (see the `dts` file in this directory) with a single U54 core.
raspberrypi Package pi provides basic abstraction for support of different models of Raspberry Pi single board computers.	Package pi provides basic abstraction for support of different models of Raspberry Pi single board computers.
raspberrypi/pi1 Package pi1 provides hardware initialization, automatically on import, for the Raspberry Pi 1 single board computer.	Package pi1 provides hardware initialization, automatically on import, for the Raspberry Pi 1 single board computer.
raspberrypi/pi2 Package pi2 provides hardware initialization, automatically on import, for the Raspberry Pi 2 single board computer.	Package pi2 provides hardware initialization, automatically on import, for the Raspberry Pi 2 single board computer.
raspberrypi/pizero Package pizero provides hardware initialization, automatically on import, for the Raspberry Pi Zero single board computer.	Package pizero provides hardware initialization, automatically on import, for the Raspberry Pi Zero single board computer.
usbarmory/mk2 Package mk2 provides hardware initialization, automatically on import, for the USB armory Mk II single board computer.	Package mk2 provides hardware initialization, automatically on import, for the USB armory Mk II single board computer.
dma Package dma provides primitives for direct memory allocation and alignment, it is primarily used in bare metal device driver operation to avoid passing Go pointers for DMA purposes.	Package dma provides primitives for direct memory allocation and alignment, it is primarily used in bare metal device driver operation to avoid passing Go pointers for DMA purposes.
internal
reg Package reg provides primitives for retrieving and modifying hardware registers.	Package reg provides primitives for retrieving and modifying hardware registers.
rng
riscv Package riscv provides support for RISC-V architecture specific operations.	Package riscv provides support for RISC-V architecture specific operations.
soc
bcm2835 Package bcm2835 provides support to Go bare metal unikernels written using the TamaGo framework on BCM2835/BCM2836 SoCs.	Package bcm2835 provides support to Go bare metal unikernels written using the TamaGo framework on BCM2835/BCM2836 SoCs.
bcm2835/framebuffer
nxp/bee Package bee implements a driver for the NXP Bus Encryption Engine (BEE) adopting the following reference specifications:	Package bee implements a driver for the NXP Bus Encryption Engine (BEE) adopting the following reference specifications:
nxp/caam Package caam implements a driver for the NXP Cryptographic Acceleration and Assurance Module (CAAM) adopting the following reference specifications:	Package caam implements a driver for the NXP Cryptographic Acceleration and Assurance Module (CAAM) adopting the following reference specifications:
nxp/csu Package csu implements a driver for the NXP Central Security Unit (CSU) adopting the following reference specifications:	Package csu implements a driver for the NXP Central Security Unit (CSU) adopting the following reference specifications:
nxp/dcp Package dcp implements a driver for the NXP Data Co-Processor (DCP) cryptographic accelerator adopting the following reference specifications:	Package dcp implements a driver for the NXP Data Co-Processor (DCP) cryptographic accelerator adopting the following reference specifications:
nxp/enet Package enet implements a driver for NXP Ethernet controllers adopting the following reference specifications:	Package enet implements a driver for NXP Ethernet controllers adopting the following reference specifications:
nxp/gpio Package gpio implements helpers for GPIO configuration on NXP SoCs.	Package gpio implements helpers for GPIO configuration on NXP SoCs.
nxp/i2c Package i2c implements a driver for NXP I2C controllers adopting the following reference specifications:	Package i2c implements a driver for NXP I2C controllers adopting the following reference specifications:
nxp/imx6ul Package imx6ul provides support to Go bare metal unikernels, written using the TamaGo framework, on the NXP i.MX6UL family of System-on-Chip (SoC) application processors.	Package imx6ul provides support to Go bare metal unikernels, written using the TamaGo framework, on the NXP i.MX6UL family of System-on-Chip (SoC) application processors.
nxp/iomuxc Package iomuxc implements helpers for IOMUX configuration on NXP SoCs.	Package iomuxc implements helpers for IOMUX configuration on NXP SoCs.
nxp/ocotp Package ocotp implements a driver for the NXP On-Chip OTP Controller (OCOTP_CTRL), which provides an interface to on-chip fuses for read/write operation, adopting the following reference specifications:	Package ocotp implements a driver for the NXP On-Chip OTP Controller (OCOTP_CTRL), which provides an interface to on-chip fuses for read/write operation, adopting the following reference specifications:
nxp/rngb Package rngb implements a driver for the NXP True Random Number Generator (RNGB) adopting the following specifications:	Package rngb implements a driver for the NXP True Random Number Generator (RNGB) adopting the following specifications:
nxp/snvs Package snvs implements a driver for NXP Secure Non-Volatile Storage (SNVS) following reference specifications:	Package snvs implements a driver for NXP Secure Non-Volatile Storage (SNVS) following reference specifications:
nxp/tempmon Package bee implements a driver for the NXP Temperature Monitor (TEMPMON) adopting the following reference specifications:	Package bee implements a driver for the NXP Temperature Monitor (TEMPMON) adopting the following reference specifications:
nxp/uart Package uart implements a driver for NXP UART controllers adopting the following reference specifications:	Package uart implements a driver for NXP UART controllers adopting the following reference specifications:
nxp/usb Package usb implements a driver for the USB PHY designated as NXP USBOH3USBO2, included in several i.MX SoCs, adopting the following specifications:	Package usb implements a driver for the USB PHY designated as NXP USBOH3USBO2, included in several i.MX SoCs, adopting the following specifications:
nxp/usdhc Package usdhc implements a driver for the Freescale Enhanced Secure Digital Host Controller (eSDHC) interface, also known as NXP Ultra Secured Digital Host Controller (uSDHC).	Package usdhc implements a driver for the Freescale Enhanced Secure Digital Host Controller (eSDHC) interface, also known as NXP Ultra Secured Digital Host Controller (uSDHC).
nxp/wdog Package bee implements a driver for the NXP Watchdog Timer (WDOG) adopting the following reference specifications:	Package bee implements a driver for the NXP Watchdog Timer (WDOG) adopting the following reference specifications:
sifive/clint Package clint implements a driver for SiFive Core-Local Interruptor (CLINT) block adopting the following reference specifications:	Package clint implements a driver for SiFive Core-Local Interruptor (CLINT) block adopting the following reference specifications:
sifive/fu540 Package fu530 provides support to Go bare metal unikernels written using the TamaGo framework.	Package fu530 provides support to Go bare metal unikernels written using the TamaGo framework.
sifive/physicalfilter Package physicalfilter implements a driver for SiFive physical-filter IP adopting the following reference specifications:	Package physicalfilter implements a driver for SiFive physical-filter IP adopting the following reference specifications:
sifive/uart Package uart implements a driver for SiFive UART controllers adopting the following reference specifications:	Package uart implements a driver for SiFive UART controllers adopting the following reference specifications:
user
linux Package linux_user provides support for using `GOOS=tamago` in Linux user space.	Package linux_user provides support for using `GOOS=tamago` in Linux user space.