usbarmory/tamagoFramework para compilar y ejecutar aplicaciones Go en procesadores bare metal, que permite el desarrollo seguro de firmware con una superficie de ataque reducida al eliminar las dependencias del sistema operativo y de C.
TamaGo - Go sobre metal desnudo
=================================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Introducción
============
TamaGo es un framework que permite la compilación y ejecución de aplicaciones Go sin restricciones sobre procesadores de metal desnudo.
Los proyectos surgen del deseo de reducir la superficie de ataque del firmware de sistemas embebidos eliminando cualquier dependencia en tiempo de ejecución de código C y Sistemas Operativos.
El framework TamaGo consta de los siguientes componentes:
- Una [distribución de Go](https://github.com/usbarmory/tamago-go) modificada
que extiende el soporte de `GOOS` al objetivo `tamago`, permitiendo la
ejecución en metal desnudo a través de una superposición de
[runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)
establecida por `GOOSPKG`.
- Paquetes Go para soporte de procesador/SoC.
- Paquetes Go para soporte de placas.
Las modificaciones son mínimas respecto al compilador Go original, el runtime y la
aplicación objetivo (se requiere un import), con una separación limpia de otras
arquitecturas.
Se pone un fuerte énfasis en la reutilización de código de arquitecturas existentes ya
incluidas dentro del runtime estándar de Go, véase
[Internals](https://github.com/usbarmory/tamago/wiki/Internals).
Las modificaciones mantienen [soporte completo de la biblioteca estándar](https://github.com/usbarmory/tamago/wiki/Compatibility).
Tales aspectos están motivados por el deseo de proporcionar un framework que permita
el desarrollo seguro de firmware Go en sistemas embebidos.
Versiones actuales
==================
Los siguientes enlaces son las últimas versiones para la
[distribución de Go modificada de TamaGo](https://github.com/usbarmory/tamago-go),
que añade soporte `GOOS=tamago` a la versión de Go correspondiente, y la
[biblioteca 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)
Documentación
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
La documentación principal se encuentra en la
[wiki del proyecto](https://github.com/usbarmory/tamago/wiki).
La documentación de la API de los paquetes se encuentra en
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
Objetivos AMD64 soportados
==========================
La siguiente tabla resume los objetivos x86-64 soportados actualmente
(`GOOS=tamago GOARCH=amd64`).
| CPU | Plataforma | Paquete de CPU | Paquete de plataforma |
|------------------|---------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 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) |
Objetivos ARM soportados
========================
La siguiente tabla resume los SoCs y placas ARM soportados actualmente
(`GOOS=tamago GOARCH=arm`).
| SoC | Placa | Paquete de SoC | Paquete de placa |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| 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) |
Objetivos ARM64 soportados
==========================
La siguiente tabla resume los SoCs y placas ARM64 soportados actualmente
(`GOOS=tamago GOARCH=arm64`).
| SoC | Placa | Paquete de SoC | Paquete de placa |
|-------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Objetivos RISC-V soportados
===========================
La siguiente tabla resume los SoCs y placas RISC-V soportados actualmente
(`GOOS=tamago GOARCH=riscv64`).
| SoC | Placa | Paquete de SoC | Paquete de placa |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Objetivos LoongArch soportados
==============================
La siguiente tabla resume los SoCs y placas LoongArch soportados actualmente
(`GOOS=tamago GOARCH=loong64`).
| SoC | Placa | Paquete de SoC | Paquete de placa |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 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) |
Objetivos de espacio de usuario
===============================
La ejecución de programas compilados con `GOOS=tamago` también puede tener lugar en
espacio de usuario importando cualquier paquete que implemente la superposición
`runtime/goos` requerida con supervisión del SO en lugar de controladores de metal desnudo.
Compilar y ejecutar programas Go en espacio de usuario como `GOOS=tamago` proporciona el
beneficio del aislamiento de llamadas al sistema, ya que el ejecutable no puede aprovechar el
runtime de Go para acceder directamente a los recursos del SO, lo que resulta en:
* aislamiento del sistema de archivos del SO, mediante disco emulado en memoria
* aislamiento de la red del SO, véase [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API para red personalizada, rng, manejadores de tiempo
La siguiente tabla resume el soporte de espacio de usuario disponible actualmente:
| Sistema Operativo | `GOARCH` | Paquetes de 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) |
¹ Utilizado para ejecutar [pruebas de la distribución estándar](https://github.com/usbarmory/tamago/wiki/Compatibility) y `go test -tags user_linux`
Compilación
===========
Distribución de Go con soporte para `GOOS=tamago`
-------------------------------------------------
El comando [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
descarga, compila y ejecuta el comando `go` de la
[distribución TamaGo](https://github.com/usbarmory/tamago-go) que coincide con la
versión del módulo tamago del `go.mod` de la aplicación.
Las aplicaciones pueden añadir `github.com/usbarmory/tamago` a `go.mod`, y luego
reemplazar el comando `go` con:
```sh
go run github.com/usbarmory/tamago/cmd/tamago
```
o añade la siguiente línea a `go.mod` para usar `go tool tamago` como comando go:
```
tool github.com/usbarmory/tamago/cmd/tamago
```
Alternativamente, la
[última distribución de TamaGo](https://github.com/usbarmory/tamago-go/tree/latest) puede compilarse
manualmente o puede usarse la
[última versión binaria](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
```
Compilación de aplicaciones
---------------------
Al compilar, la variable de entorno Go `GOOSPKG` debe estar configurada para habilitar
esta biblioteca como overlay para soportar `GOOS=tamago`.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Las aplicaciones Go deben importar el paquete de placa correspondiente para garantizar
que se realicen la inicialización del hardware y el soporte en tiempo de ejecución:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Las aplicaciones Go se pueden compilar con el compilador creado en el paso anterior,
con la adición de algunos flags/variables:
```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 el archivo README del paquete de placa correspondiente para obtener información de compilación para
cada objetivo específico.
Etiquetas de compilación
========================
Las siguientes etiquetas de compilación permiten a las aplicaciones sobrescribir la definición propia del paquete
para la superposición `runtime/goos`:
* `linkramstart`: sobrescribe `ramStart`
* `linkramsize`: sobrescribe `ramSize`
* `linkprintk`: sobrescribe `printk`
* `linkcpuinit`: sobrescribe `cpuinit`
* `tiny`: reduce los requisitos de asignación de heap
Ejecución y depuración
=======================
Consulta el archivo README del paquete de placa correspondiente para obtener información de ejecución y depuración
para cada objetivo específico (real o emulado).
La [aplicación de ejemplo](https://github.com/usbarmory/tamago-example)
proporciona ejemplos de uso de controladores e instrucciones para la ejecución tanto nativa como emulada.
Una ejecución emulada de la [aplicación de ejemplo](https://github.com/usbarmory/tamago-example)
se puede lanzar de la siguiente manera:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Aplicaciones que utilizan TamaGo
=========================
* [go-boot](https://github.com/usbarmory/go-boot) - el gestor de arranque UEFI de Go para bare metal
* [GoKey](https://github.com/usbarmory/GoKey) - la smartcard de Go para bare metal
* [GoTEE](https://github.com/usbarmory/GoTEE) - Entorno de Ejecución de Confianza en Go
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - red de testigos entre ecosistemas
* [armory-drive](https://github.com/usbarmory/armory-drive) - unidad USB cifrada
* [armory-ums](https://github.com/usbarmory/armory-ums) - firmware de almacenamiento masivo USB
* [armory-boot](https://github.com/usbarmory/armory-boot) - gestor de arranque de USB armory
* [tamago-example](https://github.com/usbarmory/tamago-example) - aplicación de ejemplo de TamaGo
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - ejemplo de VM confidencial (AMD SEV-SNP)
* [kotama](https://github.com/usbarmory/kotama) - demostrador de objetivo RISC-V minimalista
* [kanzashi](https://github.com/abarisani/kanzashi) - Agente Bare Metal
Controladores externos que utilizan TamaGo
=============================
* [go-net](https://github.com/usbarmory/go-net) - Controlador de red genérico
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - Controlador de Ethernet sobre USB para i.MX
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - Controlador de red VirtIO
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - Controlador de Serial sobre USB para i.MX
Recursos adicionales
====================
* [API del paquete](https://pkg.go.dev/github.com/usbarmory/tamago)
* [API del runtime](https://github.com/usbarmory/tamago-go/blob/latest/src/runtime/goos/README.md)
* [Compatibilidad](https://github.com/usbarmory/tamago/wiki/Compatibility)
* [Funcionamiento interno](https://github.com/usbarmory/tamago/wiki/Internals)
* [Preguntas frecuentes](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ))
* Presentaciones: [TamaGo](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago), [ArmoredWitness](https://github.com/abarisani/abarisani.github.io/tree/master/research/witness)
Mantenedores
===========
Andrea Barisani
[email protected]
Andrej Rosano
[email protected]
Licencia
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Este proyecto se distribuye bajo la licencia de estilo BSD que se encuentra en el archivo
[LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE).
El logotipo de TamaGo es una adaptación de la gopher de Go diseñada por Renee French y
con licencia Creative Commons 3.0 Attributions. Ilustración vectorial de la Gopher de Go por Hugo Arganda.