usbarmory/tamagoFramework para compilar e executar aplicações Go em processadores bare metal, permitindo o desenvolvimento seguro de firmware com superfície de ataque reduzida através da remoção de dependências de SO e C.
TamaGo - Go bare metal
======================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Introdução
============
TamaGo é um framework que permite a compilação e execução de aplicações Go
sem dependências em processadores bare metal.
Os projetos surgem do desejo de reduzir a superfície de ataque do firmware de
sistemas embarcados, removendo qualquer dependência de runtime em código C e
Sistemas Operacionais.
O framework TamaGo é composto pelos seguintes componentes:
- Uma [distribuição Go](https://github.com/usbarmory/tamago-go) modificada
que estende o suporte a `GOOS` para o alvo `tamago`, permitindo execução
bare metal através de um overlay [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)
definido por `GOOSPKG`.
- Pacotes Go para suporte a processador/SoC.
- Pacotes Go para suporte a placas.
As modificações são mínimas em relação ao compilador Go original, runtime e a
aplicação alvo (um import necessário), com uma separação limpa de outras
arquiteturas.
É dada forte ênfase à reutilização de código de arquiteturas existentes já
incluídas no runtime padrão do Go, consulte
[Internals](https://github.com/usbarmory/tamago/wiki/Internals).
As modificações mantêm [suporte completo à biblioteca padrão](https://github.com/usbarmory/tamago/wiki/Compatibility).
Tais aspetos são motivados pelo desejo de fornecer um framework que permita
o desenvolvimento seguro de firmware Go em sistemas embarcados.
Versões atuais
================
Os links seguintes são as versões mais recentes para a
[distribuição Go modificada do TamaGo](https://github.com/usbarmory/tamago-go),
que adiciona suporte a `GOOS=tamago` à versão Go correspondente, e
[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)
Documentação
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
A documentação principal pode ser encontrada na
[wiki do projeto](https://github.com/usbarmory/tamago/wiki).
A documentação da API dos pacotes pode ser encontrada em
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
Alvos AMD64 suportados
=======================
A tabela seguinte resume os alvos x86-64 atualmente suportados
(`GOOS=tamago GOARCH=amd64`).
| CPU | Plataforma | Pacote CPU | Pacote 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) |
Alvos ARM suportados
=====================
A tabela seguinte resume os SoCs e placas ARM atualmente suportados
(`GOOS=tamago GOARCH=arm`).
| SoC | Placa | Pacote SoC | Pacote 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) |
Alvos ARM64 suportados
=======================
A tabela seguinte resume os SoCs e placas ARM64 atualmente suportados
(`GOOS=tamago GOARCH=arm64`).
| SoC | Placa | Pacote SoC | Pacote 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) |
Alvos RISC-V suportados
========================
A tabela seguinte resume os SoCs e placas RISC-V atualmente suportados
(`GOOS=tamago GOARCH=riscv64`).
| SoC | Placa | Pacote SoC | Pacote 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) |
Alvos LoongArch suportados
===========================
A tabela seguinte resume os SoCs e placas LoongArch atualmente suportados
(`GOOS=tamago GOARCH=loong64`).
| SoC | Placa | Pacote SoC | Pacote 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) |
Alvos em espaço de utilizador
=================
A execução de programas compilados com `GOOS=tamago` também pode ocorrer em
espaço de utilizador importando qualquer pacote que implemente o overlay
`runtime/goos` necessário com supervisão do SO em vez de drivers bare metal.
Compilar e executar programas Go em espaço de utilizador como `GOOS=tamago`
proporciona o benefício do isolamento de chamadas de sistema, uma vez que o
executável não pode tirar partido do runtime Go para aceder diretamente a
recursos do SO, o que resulta em:
* isolamento do sistema de ficheiros do SO, através de disco emulado em memória
* isolamento da rede do SO, consulte [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API para rede, rng e handlers de tempo personalizados
A tabela seguinte resume o suporte em espaço de utilizador atualmente disponível:
| Sistema Operativo | `GOARCH` | Pacotes 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 executar [testes da distribuição padrão](https://github.com/usbarmory/tamago/wiki/Compatibility) e `go test -tags user_linux`
Compilação
=========
Distribuição Go com suporte a `GOOS=tamago`
---------------------------------------
O comando [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
descarrega, compila e executa o comando `go` da
[distribuição TamaGo](https://github.com/usbarmory/tamago-go) correspondente à
versão do módulo tamago do `go.mod` da aplicação.
As aplicações podem adicionar `github.com/usbarmory/tamago` ao `go.mod` e, em
seguida, substituir o comando `go` por:
```sh
go run github.com/usbarmory/tamago/cmd/tamago
```
ou adicione a seguinte linha ao `go.mod` para usar `go tool tamago` como comando go:
```
tool github.com/usbarmory/tamago/cmd/tamago
```
Alternativamente, a
[última distribuição do TamaGo](https://github.com/usbarmory/tamago-go/tree/latest) pode ser
compilada manualmente ou a
[última versão binária](https://github.com/usbarmory/tamago-go/releases/latest) pode ser utilizada:
```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
```
Compilando aplicações
-----------------------
Durante a compilação, a variável de ambiente Go `GOOSPKG` deve ser definida para habilitar
esta biblioteca como overlay para suportar `GOOS=tamago`.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Aplicações Go precisam importar o pacote de placa relevante para garantir
que a inicialização de hardware e o suporte em tempo de execução ocorram:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Aplicações Go podem ser compiladas com o compilador criado no passo anterior,
com a adição de algumas flags/variáveis:
```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
```
Consulte o arquivo README do pacote de placa respectivo para obter informações de compilação para
cada alvo específico.
Tags de compilação
==================
As seguintes tags de compilação permitem que as aplicações substituam a definição
própria do pacote para a sobreposição `runtime/goos`:
* `linkramstart`: substitui `ramStart`
* `linkramsize`: substitui `ramSize`
* `linkprintk`: substitui `printk`
* `linkcpuinit`: substitui `cpuinit`
* `tiny`: reduz os requisitos de alocação de heap
Execução e depuração
====================
Consulte o arquivo README do pacote de placa respectivo para obter informações de execução e depuração
para cada alvo específico (real ou emulado).
A [aplicação de exemplo](https://github.com/usbarmory/tamago-example)
fornece exemplos de uso de drivers e instruções para execução nativa, bem como emulada.
Uma execução emulada da [aplicação de exemplo](https://github.com/usbarmory/tamago-example)
pode ser iniciada da seguinte forma:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Aplicações que usam TamaGo
=========================
* [go-boot](https://github.com/usbarmory/go-boot) - o gerenciador de inicialização UEFI Go bare metal
* [GoKey](https://github.com/usbarmory/GoKey) - o smartcard Go bare metal
* [GoTEE](https://github.com/usbarmory/GoTEE) - Go Trusted Execution Environment
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - rede de testemunhas entre ecossistemas
* [armory-drive](https://github.com/usbarmory/armory-drive) - unidade USB criptografada
* [armory-ums](https://github.com/usbarmory/armory-ums) - firmware de armazenamento em massa USB
* [armory-boot](https://github.com/usbarmory/armory-boot) - carregador de inicialização do USB armory
* [tamago-example](https://github.com/usbarmory/tamago-example) - aplicação de exemplo do TamaGo
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - exemplo de VM Confidencial (AMD SEV-SNP)
* [kotama](https://github.com/usbarmory/kotama) - demonstrador de alvo RISC-V minúsculo
* [kanzashi](https://github.com/abarisani/kanzashi) - Agente Bare Metal
Drivers externos que usam TamaGo
=============================
* [go-net](https://github.com/usbarmory/go-net) - driver de rede genérico
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - driver de Ethernet sobre USB i.MX
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - driver de rede VirtIO
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - driver de Serial sobre USB i.MX
Recursos adicionais
====================
* [API do pacote](https://pkg.go.dev/github.com/usbarmory/tamago)
* [API de runtime](https://github.com/usbarmory/tamago-go/blob/latest/src/runtime/goos/README.md)
* [Compatibilidade](https://github.com/usbarmory/tamago/wiki/Compatibility)
* [Internos](https://github.com/usbarmory/tamago/wiki/Internals)
* [FAQ](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ))
* Apresentações: [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]
Licença
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Este projeto é distribuído sob a licença no estilo BSD encontrada no arquivo
[LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE).
O logotipo do TamaGo é adaptado do gopher Go criado por Renee French e
licenciado sob a licença Creative Commons 3.0 Attributions. Ilustração vetorial
do Go Gopher por Hugo Arganda.