usbarmory/tamagoFramework per compilare ed eseguire applicazioni Go su processori bare metal, che consente lo sviluppo di firmware sicuro con una superficie di attacco ridotta grazie alla rimozione delle dipendenze da OS e C.
TamaGo - Go bare metal
======================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Introduzione
============
TamaGo è un framework che consente la compilazione e l'esecuzione di applicazioni Go non vincolate su processori bare metal.
I progetti nascono dal desiderio di ridurre la superficie di attacco del firmware dei sistemi embedded eliminando qualsiasi dipendenza a runtime da codice C e sistemi operativi.
Il framework TamaGo è composto dai seguenti componenti:
- Una [distribuzione Go](https://github.com/usbarmory/tamago-go) modificata
che estende il supporto `GOOS` al target `tamago`, consentendo l'esecuzione
bare metal attraverso un overlay [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)
impostato da `GOOSPKG`.
- Pacchetti Go per il supporto a processori/SoC.
- Pacchetti Go per il supporto alle board.
Le modifiche sono minime rispetto al compilatore Go originale, al runtime e
all'applicazione target (è richiesto un solo import), con una netta separazione
dalle altre architetture.
Una forte enfasi è posta sul riutilizzo del codice delle architetture esistenti
già incluse nel runtime standard di Go, vedi
[Internals](https://github.com/usbarmory/tamago/wiki/Internals).
Le modifiche mantengono il [supporto completo alla libreria standard](https://github.com/usbarmory/tamago/wiki/Compatibility).
Tali aspetti sono motivati dal desiderio di fornire un framework che consenta
lo sviluppo sicuro di firmware Go su sistemi embedded.
Release attuali
================
I seguenti link sono le ultime release per la
[distribuzione Go modificata TamaGo](https://github.com/usbarmory/tamago-go),
che aggiunge il supporto `GOOS=tamago` alla corrispondente versione di Go, e
la [libreria TamaGo](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)
Documentazione
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
La documentazione principale è disponibile sulla
[wiki del progetto](https://github.com/usbarmory/tamago/wiki).
La documentazione dell'API dei pacchetti è disponibile su
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
Target AMD64 supportati
=======================
La seguente tabella riassume i target x86-64 attualmente supportati
(`GOOS=tamago GOARCH=amd64`).
| CPU | Piattaforma | Pacchetto CPU | Pacchetto piattaforma |
|------------------|---------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 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) |
Target ARM supportati
=====================
La seguente tabella riassume i SoC e le board ARM attualmente supportati
(`GOOS=tamago GOARCH=arm`).
| SoC | Board | Pacchetto SoC | Pacchetto board |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| 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) |
Target ARM64 supportati
=======================
La seguente tabella riassume i SoC e le board ARM64 attualmente supportati
(`GOOS=tamago GOARCH=arm64`).
| SoC | Board | Pacchetto SoC | Pacchetto board |
|-------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Target RISC-V supportati
========================
La seguente tabella riassume i SoC e le board RISC-V attualmente supportati
(`GOOS=tamago GOARCH=riscv64`).
| SoC | Board | Pacchetto SoC | Pacchetto board |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Target LoongArch supportati
===========================
La seguente tabella riassume i SoC e le board LoongArch attualmente supportati
(`GOOS=tamago GOARCH=loong64`).
| SoC | Board | Pacchetto SoC | Pacchetto board |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 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) |
Target userspace
================
L'esecuzione di programmi compilati con `GOOS=tamago` può avvenire anche nello
spazio utente importando qualsiasi pacchetto che implementi l'overlay
`runtime/goos` richiesto con supervisione del sistema operativo invece che con
driver bare metal.
Compilare ed eseguire programmi Go nello spazio utente come `GOOS=tamago`
offre il vantaggio dell'isolamento delle chiamate di sistema, poiché
l'eseguibile non può sfruttare il runtime Go per accedere direttamente alle
risorse del sistema operativo; ciò comporta:
* isolamento dal file system del sistema operativo, tramite un disco emulato in memoria
* isolamento dal networking del sistema operativo, vedi [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API per networking, rng e gestori temporali personalizzati
La seguente tabella riassume il supporto userspace attualmente disponibile:
| Sistema operativo | `GOARCH` | Pacchetti runtime |
|----------------------------------------------|-------------------------|--------------------------------------------------------------------------------------|
| [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) |
¹ Utilizzato per eseguire i [test della distribuzione standard](https://github.com/usbarmory/tamago/wiki/Compatibility) e `go test -tags user_linux`
Compilazione
============
Distribuzione Go con supporto `GOOS=tamago`
-------------------------------------------
Il comando [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
scarica, compila ed esegue il comando `go` dalla
[distribuzione TamaGo](https://github.com/usbarmory/tamago-go) corrispondente
alla versione del modulo tamago presente nel `go.mod` dell'applicazione.
Le applicazioni possono aggiungere `github.com/usbarmory/tamago` al `go.mod`, e
poi sostituire il comando `go` con:
```sh
go run github.com/usbarmory/tamago/cmd/tamago
```
oppure aggiungi la seguente riga a `go.mod` per usare `go tool tamago` come comando go:
```
tool github.com/usbarmory/tamago/cmd/tamago
```
In alternativa, la
[distribuzione TamaGo più recente](https://github.com/usbarmory/tamago-go/tree/latest) può essere
compilata manualmente oppure si può utilizzare la
[release binaria più recente](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
```
Compilazione delle applicazioni
---------------------
Durante la compilazione, la variabile d'ambiente Go `GOOSPKG` deve essere impostata per abilitare questa libreria come overlay a supporto di `GOOS=tamago`.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Le applicazioni Go devono importare il pacchetto della scheda pertinente per garantire
che avvengano l'inizializzazione dell'hardware e il supporto a runtime:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Le applicazioni Go possono essere compilate con il compilatore creato nel passaggio precedente,
con l'aggiunta di alcuni flag/variabili:
```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
```
Consulta il file README del rispettivo pacchetto della scheda per informazioni sulla compilazione per
ciascun target specifico.
Build tags
==========
I seguenti build tag consentono alle applicazioni di sovrascrivere la definizione
propria del pacchetto per l'overlay `runtime/goos`:
* `linkramstart`: sovrascrive `ramStart`
* `linkramsize`: sovrascrive `ramSize`
* `linkprintk`: sovrascrive `printk`
* `linkcpuinit`: sovrascrive `cpuinit`
* `tiny`: riduce i requisiti di allocazione dell'heap
Esecuzione e debug
=======================
Consulta il file README del rispettivo pacchetto della scheda per informazioni sull'esecuzione e il debug
per ciascun target specifico (reale o emulato).
L'[applicazione di esempio](https://github.com/usbarmory/tamago-example)
fornisce esempi di utilizzo dei driver e istruzioni per l'esecuzione nativa
nonché emulata.
Un'esecuzione emulata dell'[applicazione di esempio](https://github.com/usbarmory/tamago-example)
può essere avviata come segue:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Applicazioni che utilizzano TamaGo
===================================
* [go-boot](https://github.com/usbarmory/go-boot) - il boot manager UEFI bare metal in Go
* [GoKey](https://github.com/usbarmory/GoKey) - la smartcard bare metal in Go
* [GoTEE](https://github.com/usbarmory/GoTEE) - Go Trusted Execution Environment
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - rete di witness cross-ecosystem
* [armory-drive](https://github.com/usbarmory/armory-drive) - drive USB cifrato
* [armory-ums](https://github.com/usbarmory/armory-ums) - firmware USB Mass Storage
* [armory-boot](https://github.com/usbarmory/armory-boot) - boot loader USB armory
* [tamago-example](https://github.com/usbarmory/tamago-example) - applicazione di esempio TamaGo
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - esempio di Confidential VM (AMD SEV-SNP)
* [kotama](https://github.com/usbarmory/kotama) - dimostratore di target RISC-V minimale
* [kanzashi](https://github.com/abarisani/kanzashi) - Bare Metal Agent
Driver esterni che utilizzano TamaGo
====================================
* [go-net](https://github.com/usbarmory/go-net) - driver di rete generico
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - driver i.MX Ethernet over USB
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - driver di rete VirtIO
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - driver i.MX Serial over USB
Risorse aggiuntive
==================
* [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)
* [Compatibilità](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))
* Presentazioni: [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]
Licenza
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Questo progetto è distribuito sotto la licenza in stile BSD presente nel file
[LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE).
Il logo TamaGo è adattato dal gopher Go disegnato da Renee French e
rilasciato sotto licenza Creative Commons 3.0 Attributions. Illustrazione
vettoriale del Go Gopher di Hugo Arganda.