README

TamaGo - bare metal Go for ARM SoCs

tamago | https://github.com/f-secure-foundry/tamago

Copyright (c) F-Secure Corporation
https://foundry.f-secure.com

TamaGo gopher

Authors

Andrea Barisani
andrea.barisani@f-secure.com | andrea@inversepath.com

Andrej Rosano
andrej.rosano@f-secure.com | andrej@inversepath.com

Introduction

TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal ARM System-on-Chip (SoC) components.

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 meant to be minimal for both the Go distribution (< ~4000 LOC changed) 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.

Both aspects are motivated by the desire of providing a framework that allows secure Go firmware development on embedded systems.

Current release level

GitHub release Build Status

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

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 hardware

The following table summarizes currently supported SoCs and boards.

SoC Board SoC package Board package
NXP i.MX6ULZ USB armory Mk II imx6 usbarmory/mark-two
NXP i.MX6ULL MCIMX6ULL-EVK imx6 mx6ullevk
BCM2835 Raspberry Pi Zero bcm2835 pi/pizero
BCM2835 Raspberry Pi 1 Model A+ bcm2835 pi/pi1
BCM2835 Raspberry Pi 1 Model B+ bcm2835 pi/pi1
BCM2836 Raspberry Pi 2 Model B bcm2835 pi/pi2

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/f-secure-foundry/tamago/board/f-secure/usbarmory/mark-two"
)

Build the TamaGo compiler (or use the latest binary release):

wget https://github.com/f-secure-foundry/tamago-go/archive/refs/tags/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
GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \
  ${TAMAGO} build -ldflags "-T 0x80010000  -E _rt0_arm_tamago -R 0x1000"

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.

License

tamago | https://github.com/f-secure-foundry/tamago
Copyright (c) F-Secure Corporation

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.

Expand ▾ Collapse ▴

Directories

Path Synopsis
Package arm provides support for ARM architecture specific operations.
Package arm provides support for ARM architecture specific operations.
Package bits provides primitives for bitwise operations on uint32 values.
Package bits provides primitives for bitwise operations on uint32 values.
board
f-secure/usbarmory/mark-two
Package usbarmory provides hardware initialization, automatically on import, for the USB armory Mk II single board computer.
Package usbarmory provides hardware initialization, automatically on import, for the USB armory Mk II single board computer.
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.
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.
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.
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.
imx6
Package imx6 provides support to Go bare metal unikernels written using the TamaGo framework.
Package imx6 provides support to Go bare metal unikernels written using the TamaGo framework.
imx6/dcp
Package dcp implements a driver for the NXP Data Co-Processor (DCP), a cryptographic hardware accelerator included in i.MX6ULL/i.MX6ULZ SoCs.
Package dcp implements a driver for the NXP Data Co-Processor (DCP), a cryptographic hardware accelerator included in i.MX6ULL/i.MX6ULZ SoCs.
imx6/imx6q
Package imx6q provides hardware initialization, automatically on import, for the i.MX6Q family of System-on-Chip components.
Package imx6q provides hardware initialization, automatically on import, for the i.MX6Q family of System-on-Chip components.
imx6/imx6ul
Package imx6ul provides hardware initialization, automatically on import, for the i.MX6UL family of System-on-Chip components.
Package imx6ul provides hardware initialization, automatically on import, for the i.MX6UL family of System-on-Chip components.
imx6/ocotp
Package ocotp implements a driver for the NXP On-Chip OTP Controller (OCOTP_CTRL), included in i.MX6 series SoCs to interface with on-chip fuses, including write operation.
Package ocotp implements a driver for the NXP On-Chip OTP Controller (OCOTP_CTRL), included in i.MX6 series SoCs to interface with on-chip fuses, including write operation.
imx6/rngb
Package rngb implements a driver for the NXP True Random Number Generator (RNGB) included in i.MX6ULL/i.MX6ULZ SoCs.
Package rngb implements a driver for the NXP True Random Number Generator (RNGB) included in i.MX6ULL/i.MX6ULZ SoCs.
imx6/usb
Package usb implements a driver for the USB PHY designated as NXP USBOH3USBO2, included in i.MX6 SoCs.
Package usb implements a driver for the USB PHY designated as NXP USBOH3USBO2, included in i.MX6 SoCs.
imx6/usb/ethernet
Package ethernet implements a driver for Ethernet over USB emulation on i.MX6 SoCs.
Package ethernet implements a driver for Ethernet over USB emulation on i.MX6 SoCs.
imx6/usdhc
Package usdhc implements a driver for Freescale Enhanced Secure Digital Host Controller (eSDHC) interface, also known as NXP Ultra Secured Digital Host Controller (uSDHC).
Package usdhc implements a driver for Freescale Enhanced Secure Digital Host Controller (eSDHC) interface, also known as NXP Ultra Secured Digital Host Controller (uSDHC).
internal
reg
Package reg provides primitives for retrieving and modifying hardware registers.
Package reg provides primitives for retrieving and modifying hardware registers.