Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/usbarmory/tamago
TamaGo - ARM/RISC-V bare metal Go
https://github.com/usbarmory/tamago
Last synced: 3 months ago
JSON representation
TamaGo - ARM/RISC-V bare metal Go
- Host: GitHub
- URL: https://github.com/usbarmory/tamago
- Owner: usbarmory
- License: bsd-3-clause
- Created: 2019-10-24T09:51:55.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-09-09T21:36:10.000Z (4 months ago)
- Last Synced: 2024-09-10T02:19:41.197Z (4 months ago)
- Language: Go
- Homepage:
- Size: 1.09 MB
- Stars: 1,295
- Watchers: 36
- Forks: 50
- 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 for ARM/RISC-V SoCs
==========================================
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
https://foundry.withsecure.com
Introduction
============
TamaGo is a framework that enables compilation and execution of unencumbered Go
applications on bare metal ARM/RISC-V 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](https://github.com/usbarmory/tamago-go)
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](https://github.com/usbarmory/tamago/wiki/Internals).
Both aspects are motivated by the desire of providing a framework that allows
secure Go firmware development on embedded systems.
Current release level
=====================
[](https://github.com/usbarmory/tamago-go/tree/latest) [](https://github.com/usbarmory/tamago-go/actions)
The current release for the [TamaGo modified Go distribution](https://github.com/usbarmory/tamago-go) is
[tamago1.23.2](https://github.com/usbarmory/tamago-go/tree/tamago1.23.2),
which [adds](https://github.com/golang/go/compare/go1.23.2...usbarmory:tamago1.23.2)
`GOOS=tamago` support to go1.23.2.
Binary releases for amd64 and armv7l Linux hosts [are available](https://github.com/usbarmory/tamago-go/releases/latest).
Documentation
=============
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 ARM hardware
=======================
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 RISC-V hardware
==========================
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) |
Compiling
=========
Go applications are simply required to import, the relevant board package to
ensure that hardware initialization and runtime support takes 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)):
```
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
GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \
${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_arm_tamago -R 0x1000"
# Example for QEMU RISC-V sifive_u
GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARCH=riscv64 \
${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_riscv64_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](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:
```
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Applications using TamaGo
=========================
* [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) - primary bootloader
* [tamago-example](https://github.com/usbarmory/tamago-example) - TamaGo example application
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
Additional resources
====================
* [Package API](https://pkg.go.dev/github.com/usbarmory/tamago)
* [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)
Maintainers
===========
Andrea Barisani
[email protected] | [email protected]
Andrej Rosano
[email protected] | [email protected]
License
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
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.