usbarmory/tamagoFramework zur Kompilierung und Ausführung von Go-Anwendungen auf Bare-Metal-Prozessoren, das eine sichere Firmware-Entwicklung mit reduzierter Angriffsfläche durch Entfernung von Betriebssystem- und C-Abhängigkeiten ermöglicht.
TamaGo - Bare-Metal-Go
======================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. Alle Rechte vorbehalten.
Einführung
==========
TamaGo ist ein Framework, das die Kompilierung und Ausführung uneingeschränkter Go-Anwendungen auf Bare-Metal-Prozessoren ermöglicht.
Die Projekte entstehen aus dem Wunsch, die Angriffsfläche von Firmware eingebetteter Systeme zu reduzieren, indem jegliche Laufzeitabhängigkeit von C-Code und Betriebssystemen entfernt wird.
Das TamaGo-Framework besteht aus den folgenden Komponenten:
- Eine modifizierte [Go-Distribution](https://github.com/usbarmory/tamago-go),
die die `GOOS`-Unterstützung auf das `tamago`-Ziel erweitert und so die
Bare-Metal-Ausführung durch ein [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)-Overlay
ermöglicht, das durch `GOOSPKG` festgelegt wird.
- Go-Pakete für Prozessor-/SoC-Unterstützung.
- Go-Pakete für Board-Unterstützung.
Die Modifikationen sind minimal gegenüber dem ursprünglichen Go-Compiler, der Laufzeitumgebung und der Zielanwendung (ein Import erforderlich), mit einer sauberen Trennung von anderen Architekturen.
Großer Wert wird auf die Wiederverwendung von Code aus bestehenden Architekturen gelegt, die bereits in der Standard-Go-Laufzeitumgebung enthalten sind, siehe
[Interna](https://github.com/usbarmory/tamago/wiki/Internals).
Die Modifikationen erhalten die [vollständige Unterstützung der Standardbibliothek](https://github.com/usbarmory/tamago/wiki/Compatibility).
Solche Aspekte sind motiviert durch den Wunsch, ein Framework bereitzustellen, das eine sichere Go-Firmware-Entwicklung auf eingebetteten Systemen ermöglicht.
Aktuelle Releases
=================
Die folgenden Links sind die neuesten Releases für die
[TamaGo-modifizierte Go-Distribution](https://github.com/usbarmory/tamago-go),
die `GOOS=tamago`-Unterstützung für die entsprechende Go-Version hinzufügt, und
die [TamaGo-Bibliothek](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)
Dokumentation
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
Die Hauptdokumentation befindet sich im
[Projekt-Wiki](https://github.com/usbarmory/tamago/wiki).
Die Paket-API-Dokumentation befindet sich auf
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
Unterstützte AMD64-Ziele
=======================
Die folgende Tabelle fasst die derzeit unterstützten x86-64-Ziele zusammen
(`GOOS=tamago GOARCH=amd64`).
| CPU | Plattform | CPU-Paket | Plattform-Paket |
|------------------|---------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 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) |
Unterstützte ARM-Ziele
=====================
Die folgende Tabelle fasst die derzeit unterstützten ARM-SoCs und -Boards zusammen
(`GOOS=tamago GOARCH=arm`).
| SoC | Board | SoC-Paket | Board-Paket |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| 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) |
Unterstützte ARM64-Ziele
=======================
Die folgende Tabelle fasst die derzeit unterstützten ARM64-SoCs und -Boards zusammen
(`GOOS=tamago GOARCH=arm64`).
| SoC | Board | SoC-Paket | Board-Paket |
|-------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Unterstützte RISC-V-Ziele
========================
Die folgende Tabelle fasst die derzeit unterstützten RISC-V-SoCs und -Boards zusammen
(`GOOS=tamago GOARCH=riscv64`).
| SoC | Board | SoC-Paket | Board-Paket |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Unterstützte LoongArch-Ziele
===========================
Die folgende Tabelle fasst die derzeit unterstützten LoongArch-SoCs und -Boards zusammen
(`GOOS=tamago GOARCH=loong64`).
| SoC | Board | SoC-Paket | Board-Paket |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 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-Ziele
=================
Die Ausführung von Programmen, die mit `GOOS=tamago` kompiliert wurden, kann auch im
Userspace erfolgen, indem ein Paket importiert wird, das das erforderliche `runtime/goos`-Overlay
mit OS-Überwachung anstelle von Bare-Metal-Treibern implementiert.
Das Kompilieren und Ausführen von Go-Programmen im Userspace als `GOOS=tamago` bietet den
Vorteil der Systemaufruf-Isolation, da die ausführbare Datei nicht auf die Go-Laufzeitumgebung
zurückgreifen kann, um direkt auf OS-Ressourcen zuzugreifen. Dies führt zu:
* Isolation vom OS-Dateisystem durch eine im Speicher emulierte Festplatte
* Isolation vom OS-Netzwerk, siehe [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API für benutzerdefiniertes Netzwerk, RNG, Zeit-Handler
Die folgende Tabelle fasst die derzeit verfügbare Userspace-Unterstützung zusammen:
| Betriebssystem | `GOARCH` | Laufzeit-Pakete |
|----------------------------------------------|-------------------------|--------------------------------------------------------------------------------------|
| [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) |
¹ Wird verwendet, um [Standard-Distributionstests](https://github.com/usbarmory/tamago/wiki/Compatibility) und `go test -tags user_linux` auszuführen
Kompilieren
=========
Go-Distribution mit `GOOS=tamago`-Unterstützung
---------------------------------------
Der Befehl [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
lädt den `go`-Befehl aus der
[TamaGo-Distribution](https://github.com/usbarmory/tamago-go) herunter, kompiliert ihn und führt ihn aus,
passend zur tamago-Modulversion aus der `go.mod` der Anwendung.
Anwendungen können `github.com/usbarmory/tamago` zu `go.mod` hinzufügen und dann
den `go`-Befehl ersetzen durch:
```sh
go run github.com/usbarmory/tamago/cmd/tamago
```
oder fügen Sie die folgende Zeile zu `go.mod` hinzu, um `go tool tamago` als go-Befehl zu verwenden:
```
tool github.com/usbarmory/tamago/cmd/tamago
```
Alternativ kann die
[neueste TamaGo-Distribution](https://github.com/usbarmory/tamago-go/tree/latest) manuell
gebaut oder die
[neueste Binärversion](https://github.com/usbarmory/tamago-go/releases/latest) verwendet werden:
```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
```
Anwendungen erstellen
---------------------
Beim Kompilieren muss die Go-Umgebungsvariable `GOOSPKG` gesetzt werden, um
diese Bibliothek als Overlay zur Unterstützung von `GOOS=tamago` zu aktivieren.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Go-Anwendungen müssen das entsprechende Board-Paket importieren, um
sicherzustellen, dass die Hardware-Initialisierung und die Laufzeitunterstützung stattfinden:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Go-Anwendungen können mit dem im vorherigen Schritt erstellten Compiler kompiliert werden,
unter Hinzufügung einiger Flags/Variablen:
```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
```
Informationen zur Kompilierung für jedes spezifische Ziel finden Sie in
der jeweiligen README-Datei des Board-Pakets.
Build-Tags
==========
Die folgenden Build-Tags ermöglichen es Anwendungen, die paketeigene
Definition für das `runtime/goos`-Overlay zu überschreiben:
* `linkramstart`: überschreibt `ramStart`
* `linkramsize`: überschreibt `ramSize`
* `linkprintk`: überschreibt `printk`
* `linkcpuinit`: überschreibt `cpuinit`
* `tiny`: reduziert den Heap-Allokationsbedarf
Ausführen und Debuggen
=======================
Informationen zur Ausführung und zum Debuggen für jedes spezifische Ziel
(real oder emuliert) finden Sie in der jeweiligen README-Datei des
Board-Pakets.
Die [Beispielanwendung](https://github.com/usbarmory/tamago-example)
bietet Beispiel-Treibernutzung sowie Anweisungen für die native und die
emulierte Ausführung.
Ein emulierter Lauf der [Beispielanwendung](https://github.com/usbarmory/tamago-example)
kann wie folgt gestartet werden:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Anwendungen, die TamaGo verwenden
=========================
* [go-boot](https://github.com/usbarmory/go-boot) - der Bare-Metal-Go-UEFI-Bootmanager
* [GoKey](https://github.com/usbarmory/GoKey) - die 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-Netzwerk
* [armory-drive](https://github.com/usbarmory/armory-drive) - verschlüsseltes USB-Laufwerk
* [armory-ums](https://github.com/usbarmory/armory-ums) - USB-Massenspeicher-Firmware
* [armory-boot](https://github.com/usbarmory/armory-boot) - USB-armory-Bootloader
* [tamago-example](https://github.com/usbarmory/tamago-example) - TamaGo-Beispielanwendung
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - Beispiel für Confidential VM (AMD SEV-SNP)
* [kotama](https://github.com/usbarmory/kotama) - Tiny-RISC-V-Target-Demonstrator
* [kanzashi](https://github.com/abarisani/kanzashi) - Bare-Metal-Agent
Externe Treiber, die TamaGo verwenden
=============================
* [go-net](https://github.com/usbarmory/go-net) - generischer Netzwerktreiber
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - i.MX-Ethernet-over-USB-Treiber
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - VirtIO-Netzwerktreiber
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - i.MX-Serial-over-USB-Treiber
Zusätzliche Ressourcen
====================
* [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)
* [Kompatibilität](https://github.com/usbarmory/tamago/wiki/Compatibility)
* [Interna](https://github.com/usbarmory/tamago/wiki/Internals)
* [FAQ](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ))
* Präsentationen: [TamaGo](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago), [ArmoredWitness](https://github.com/abarisani/abarisani.github.io/tree/master/research/witness)
Maintainer
===========
Andrea Barisani
[email protected]
Andrej Rosano
[email protected]
Lizenz
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Dieses Projekt wird unter der BSD-artigen Lizenz vertrieben, die in der
Datei [LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE) zu finden ist.
Das TamaGo-Logo ist eine Adaption des von Renee French entworfenen Go-Gophers und
steht unter der Creative Commons 3.0 Attributions-Lizenz. Go-Gopher-Vektor-
Illustration von Hugo Arganda.