usbarmory/tamagoФреймворк для компиляции и выполнения Go-приложений на голых металлических процессорах, обеспечивающий безопасную разработку прошивок с уменьшенной поверхностью атаки за счет удаления зависимостей от ОС и C.
TamaGo - Go на голом железе
======================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Введение
============
TamaGo — это фреймворк, позволяющий компилировать и запускать необременённые Go-приложения на процессорах без операционной системы.
Проект возник из желания уменьшить поверхность атаки прошивок встраиваемых систем путём устранения любых зависимостей времени выполнения от кода на C и операционных систем.
Фреймворк TamaGo состоит из следующих компонентов:
- Модифицированный [дистрибутив Go](https://github.com/usbarmory/tamago-go),
который расширяет поддержку `GOOS` до цели `tamago`, позволяя исполнение
на голом железе через оверлей [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos),
устанавливаемый `GOOSPKG`.
- Go-пакеты для поддержки процессоров/SoC.
- Go-пакеты для поддержки плат.
Модификации минимальны по отношению к оригинальному компилятору Go, среде выполнения и целевому приложению (требуется один импорт), с чётким отделением от других архитектур.
Большое внимание уделяется повторному использованию кода из существующих архитектур, уже включённых в стандартную среду выполнения Go, см.
[Internals](https://github.com/usbarmory/tamago/wiki/Internals).
Модификации сохраняют [полную поддержку стандартной библиотеки](https://github.com/usbarmory/tamago/wiki/Compatibility).
Такие аспекты мотивированы желанием предоставить фреймворк, позволяющий разрабатывать безопасные прошивки на Go для встраиваемых систем.
Текущие релизы
================
Следующие ссылки ведут на последние релизы
[модифицированного дистрибутива Go TamaGo](https://github.com/usbarmory/tamago-go),
который добавляет поддержку `GOOS=tamago` к соответствующей версии Go, и
[библиотеки 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)
Документация
=============
[](https://pkg.go.dev/github.com/usbarmory/tamago)
Основная документация находится на
[вики проекта](https://github.com/usbarmory/tamago/wiki).
Документация по API пакетов доступна на
[pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
Поддерживаемые цели AMD64
=======================
В следующей таблице перечислены текущие поддерживаемые цели x86-64
(`GOOS=tamago GOARCH=amd64`).
| CPU | Платформа | Пакет CPU | Пакет платформы |
|------------------|---------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 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) |
Поддерживаемые цели ARM
=====================
В следующей таблице перечислены текущие поддерживаемые SoC и платы ARM
(`GOOS=tamago GOARCH=arm`).
| SoC | Плата | Пакет SoC | Пакет платы |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| 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) |
Поддерживаемые цели ARM64
=======================
В следующей таблице перечислены текущие поддерживаемые SoC и платы ARM64
(`GOOS=tamago GOARCH=arm64`).
| SoC | Плата | Пакет SoC | Пакет платы |
|-------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Поддерживаемые цели RISC-V
========================
В следующей таблице перечислены текущие поддерживаемые SoC и платы RISC-V
(`GOOS=tamago GOARCH=riscv64`).
| SoC | Плата | Пакет SoC | Пакет платы |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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) |
Поддерживаемые цели LoongArch
===========================
В следующей таблице перечислены текущие поддерживаемые SoC и платы LoongArch
(`GOOS=tamago GOARCH=loong64`).
| SoC | Плата | Пакет SoC | Пакет платы |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 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) |
Цели пользовательского пространства
=================
Выполнение программ, скомпилированных с `GOOS=tamago`, также может происходить в
пользовательском пространстве путём импорта любого пакета, реализующего требуемый оверлей `runtime/goos`
с супервизией ОС вместо драйверов голого железа.
Компиляция и запуск Go-программ в пользовательском пространстве как `GOOS=tamago` даёт
преимущество изоляции системных вызовов, поскольку исполняемый файл не может использовать среду выполнения Go
для прямого доступа к ресурсам ОС, что приводит к:
* изоляции от файловой системы ОС через эмулированный в памяти диск
* изоляции от сетевого стека ОС, см. [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
* API для пользовательской обработки сетевых операций, rng, времени
В следующей таблице перечислена текущая доступная поддержка пользовательского пространства:
| Операционная система | `GOARCH` | Пакеты среды выполнения |
|----------------------------------------------|-------------------------|--------------------------------------------------------------------------------------|
| [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) |
¹ Используется для запуска [тестов стандартного дистрибутива](https://github.com/usbarmory/tamago/wiki/Compatibility) и `go test -tags user_linux`
Компиляция
=========
Дистрибутив Go с поддержкой `GOOS=tamago`
---------------------------------------
Команда [tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
скачивает, компилирует и запускает команду `go` из
[дистрибутива TamaGo](https://github.com/usbarmory/tamago-go), соответствующего
версии модуля tamago из `go.mod` приложения.
Приложения могут добавить `github.com/usbarmory/tamago` в `go.mod`, а затем
заменить команду `go` на:
```sh
go run github.com/usbarmory/tamago/cmd/tamago
```
или добавьте следующую строку в `go.mod`, чтобы использовать `go tool tamago` как команду go:
```
tool github.com/usbarmory/tamago/cmd/tamago
```
Кроме того, можно вручную собрать
[последнюю версию дистрибутива TamaGo](https://github.com/usbarmory/tamago-go/tree/latest) или
использовать
[последний бинарный релиз](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
```
Сборка приложений
---------------------
При компиляции необходимо установить переменную окружения Go `GOOSPKG`, чтобы
включить эту библиотеку в качестве overlay для поддержки `GOOS=tamago`.
```
export GOOSPKG=github.com/usbarmory/tamago
```
Приложения на Go должны импортировать соответствующий пакет платы, чтобы
обеспечить инициализацию оборудования и поддержку во время выполнения:
```golang
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)
```
Go-приложения можно скомпилировать с помощью компилятора, собранного на предыдущем шаге,
с добавлением нескольких флагов/переменных:
```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
```
См. соответствующий README-файл пакета платы для получения информации о компиляции
для каждой конкретной цели.
Теги сборки
==========
Следующие теги сборки позволяют приложениям переопределять собственное
определение пакета для оверлея `runtime/goos`:
* `linkramstart`: переопределить `ramStart`
* `linkramsize`: переопределить `ramSize`
* `linkprintk`: переопределить `printk`
* `linkcpuinit`: переопределить `cpuinit`
* `tiny`: уменьшить требования к выделению кучи
Выполнение и отладка
=======================
См. соответствующий README-файл пакета платы для получения информации о выполнении и отладке
для каждой конкретной цели (реальной или эмулируемой).
[Пример приложения](https://github.com/usbarmory/tamago-example)
предоставляет примеры использования драйверов и инструкции как для нативного, так и для эмулируемого
выполнения.
Эмулируемый запуск [примера приложения](https://github.com/usbarmory/tamago-example)
можно запустить следующим образом:
```sh
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
```
Приложения, использующие TamaGo
=========================
* [go-boot](https://github.com/usbarmory/go-boot) - менеджер загрузки UEFI на Go для bare metal
* [GoKey](https://github.com/usbarmory/GoKey) - смарт-карта на Go для bare metal
* [GoTEE](https://github.com/usbarmory/GoTEE) - доверенная среда исполнения на Go
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - кросс-экосистемная сеть свидетелей
* [armory-drive](https://github.com/usbarmory/armory-drive) - USB-накопитель с шифрованием
* [armory-ums](https://github.com/usbarmory/armory-ums) - прошивка USB Mass Storage
* [armory-boot](https://github.com/usbarmory/armory-boot) - загрузчик USB armory
* [tamago-example](https://github.com/usbarmory/tamago-example) - пример приложения TamaGo
* [tamago-sev-example](https://github.com/usbarmory/tamago-sev-example) - пример конфиденциальной ВМ (AMD SEV-SNP)
* [kotama](https://github.com/usbarmory/kotama) - демонстратор крошечной цели RISC-V
* [kanzashi](https://github.com/abarisani/kanzashi) - агент для bare metal
Внешние драйверы, использующие TamaGo
=============================
* [go-net](https://github.com/usbarmory/go-net) - универсальный сетевой драйвер
* [go-net/imx-usb](https://github.com/usbarmory/go-net/tree/main/imx-usb) - драйвер i.MX Ethernet over USB
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - сетевой драйвер VirtIO
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - драйвер i.MX Serial over USB
Дополнительные ресурсы
====================
* [API пакета](https://pkg.go.dev/github.com/usbarmory/tamago)
* [API среды исполнения](https://github.com/usbarmory/tamago-go/blob/latest/src/runtime/goos/README.md)
* [Совместимость](https://github.com/usbarmory/tamago/wiki/Compatibility)
* [Внутреннее устройство](https://github.com/usbarmory/tamago/wiki/Internals)
* [FAQ](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ))
* Презентации: [TamaGo](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago), [ArmoredWitness](https://github.com/abarisani/abarisani.github.io/tree/master/research/witness)
Сопровождающие
===========
Andrea Barisani
[email protected]
Andrej Rosano
[email protected]
Лицензия
=======
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
Этот проект распространяется под лицензией в стиле BSD, находящейся в файле
[LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE).
Логотип TamaGo адаптирован из Go gopher, созданного Renee French и
лицензированного по лицензии Creative Commons 3.0 Attributions. Векторная
иллюстрация Go Gopher выполнена Hugo Arganda.