TamaGo - 裸机 Go

tamago | https://github.com/usbarmory/tamago

版权所有 (c) The TamaGo Authors。保留所有权利。

介绍

TamaGo 是一个框架，能够在裸机处理器（AMD64、ARM、ARM64、RISCV64）上编译和执行不受限制的 Go 应用程序。

该项目源于减少嵌入式系统固件攻击面的愿望，通过移除对 C 代码和操作系统的运行时依赖。

TamaGo 框架由以下组件组成：

• 一个修改过的 Go 发行版， 将 GOOS 支持扩展到 tamago 目标，通过 GOOSPKG 设置的 runtime/goos 覆盖层实现裸机执行。

• 用于处理器/SoC 支持的 Go 包。

• 用于板级支持的 Go 包。

这些修改相对于原始 Go 编译器、运行时和目标应用程序（需要一个导入）来说是最小的，并且与其他架构保持清晰分离。

重点强调复用标准 Go 运行时中已包含的现有架构，参见 内部机制。

这些修改保持了完整的标准库支持。

这些方面的动机是提供一个能够在嵌入式系统上开发安全 Go 固件的框架。

当前发布版本

以下链接是 TamaGo 修改版 Go 发行版 和 TamaGo 库 的最新版本：

文档

主要文档可在项目维基找到。

包 API 文档可在 pkg.go.dev 找到。

支持的 AMD64 目标

下表总结了当前支持的 x86-64 目标（GOOS=tamago GOARCH=amd64）。

支持的 ARM 目标

下表总结了当前支持的 ARM SoC 和开发板（GOOS=tamago GOARCH=arm）。

支持的 ARM64 目标

下表总结了当前支持的 ARM64 SoC 和开发板（GOOS=tamago GOARCH=arm64）。

支持的 RISC-V 目标

下表总结了当前支持的 RISC-V SoC 和开发板（GOOS=tamago GOARCH=riscv64）。

用户空间目标

使用 GOOS=tamago 编译的程序也可以在用户空间中执行，只需导入实现了所需 runtime/goos 覆盖层的包，而不是裸机驱动，由操作系统监管。

在用户空间中以 GOOS=tamago 编译和运行 Go 程序的好处在于系统调用隔离，因为可执行文件无法利用 Go 运行时直接访问操作系统资源，这带来了：

• 与操作系统文件系统的隔离，通过内存模拟磁盘
• 与操作系统网络的隔离，参见 net.SocketFunc
• 用于自定义网络、随机数生成、时间处理器的 API

下表总结了当前可用的用户空间支持：

¹ 用于运行标准发行版测试和 go test -tags user_linux

编译

支持 GOOS=tamago 的 Go 发行版

tamago 命令下载、编译并运行来自 TamaGo 发行版中与应用程序 go.mod 中 tamago 模块版本匹配的 go 命令。

应用程序可以将 github.com/usbarmory/tamago 添加到 go.mod，然后将 go 命令替换为：

go run github.com/usbarmory/tamago/cmd/tamago

或者将以下行添加到 go.mod 以使用 go tool tamago 作为 go 命令：

tool github.com/usbarmory/tamago/cmd/tamago

或者也可以手动构建最新的 TamaGo 发行版或使用最新的二进制发布：

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

构建应用程序

编译时，必须设置 GOOSPKG Go 环境变量以启用此库作为支持 GOOS=tamago 的覆盖层。

export GOOSPKG=github.com/usbarmory/tamago

Go 应用程序需要导入相关的开发板包，以确保硬件初始化和运行时支持：

import (
	// USB armory Mk II 示例
	_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)

Go 应用程序可以使用上一步构建的编译器进行编译，并添加一些标志/变量：

# 将此库设置为 `runtime/goos` 覆盖层
export GOOSPKG=github.com/usbarmory/tamago

# Cloud Hypervisor、QEMU 和 Firecracker KVM 示例
GOOS=tamago GOARCH=amd64 ${TAMAGO} build -ldflags "-T 0x10010000 -R 0x1000" main.go

# NXP i.MX6UL 示例
GOOS=tamago GOARM=7 GOARCH=arm ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go

# NXP 8MPLUSLPD4-EVK 示例
GOOS=tamago GOARCH=arm64 ${TAMAGO} build -ldflags "-T 0x40010000 -R 0x1000" main.go

# SiFive FU540 示例
GOOS=tamago GOARCH=riscv64 ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go

# AI Foundry Erbium 示例
GOOS=tamago GOARCH=riscv64 GOSOFT=1 ${TAMAGO} build -ldflags "-T 0x40010000 -R 0x1000" main.go

# Linux 用户空间示例
GOOS=tamago ${TAMAGO} build main.go

请参阅各自开发板包的 README 文件以获取每个特定目标的编译信息。

构建标签

以下构建标签允许应用程序覆盖包自身的 runtime/goos 覆盖层定义：

• linkramstart: 覆盖 ramStart
• linkramsize: 覆盖 ramSize
• linkprintk: 覆盖 printk
• linkcpuinit: 覆盖 cpuinit
• tiny: 减少堆分配需求

执行和调试

请参阅各自开发板包的 README 文件以获取每个特定目标（真实或仿真）的执行和调试信息。

示例应用程序提供了示例驱动使用以及原生和仿真执行的说明。

可以按以下方式启动示例应用程序的仿真运行：

git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu

使用 TamaGo 的应用程序

• go-boot - 裸机 Go UEFI 启动管理器
• GoKey - 裸机 Go 智能卡
• GoTEE - Go 可信执行环境
• ArmoredWitness - 跨生态系统见证网络
• armory-drive - USB 加密驱动器
• armory-ums - USB 大容量存储固件
• armory-boot - USB armory 引导加载程序
• tamago-example - TamaGo 示例应用程序
• tamago-sev-example - 机密虚拟机（AMD SEV-SNP）示例
• kotama - 微型 RISC-V 目标演示器
• kanzashi - 裸机代理

使用 TamaGo 的外部驱动

• go-net - 通用网络驱动
• go-net/imx-usb - i.MX 以太网 over USB 驱动
• go-net/virtio - VirtIO 网络驱动
• imx-usbserial - i.MX 串行 over USB 驱动

其他资源

• 包 API
• 运行时 API
• 兼容性
• 内部机制
• 常见问题
• 演讲：TamaGo, ArmoredWitness

维护者

Andrea Barisani
[email protected]

Andrej Rosano
[email protected]

许可证

tamago | https://github.com/usbarmory/tamago
版权所有 (c) The TamaGo Authors。保留所有权利。

本项目基于 LICENSE 文件中的 BSD 风格许可证分发。

TamaGo 标志改编自 Renee French 设计的 Go gopher，根据 Creative Commons 3.0 Attributions 许可授权。Go Gopher 矢量插画由 Hugo Arganda 制作。