tamago

TamaGo - 裸机 Go
======================

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

Copyright (c) The TamaGo Authors. All Rights Reserved.  

![TamaGo gopher](https://github.com/usbarmory/tamago/wiki/images/tamago.svg?sanitize=true)

简介
============

TamaGo 是一个框架，支持在裸机处理器上编译和执行无额外依赖的 Go 应用程序。

这些项目源于通过消除对 C 代码和操作系统的任何运行时依赖来减少嵌入式系统固件攻击面的愿望。

TamaGo 框架由以下组件组成：

 - 一个修改过的 [Go 发行版](https://github.com/usbarmory/tamago-go)，
   它将 `GOOS` 支持扩展到 `tamago` 目标，允许通过由 `GOOSPKG` 设置的
   [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos)
   覆盖层进行裸机执行。

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

 - 用于开发板支持的 Go 包。

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

重点强调从标准 Go 运行时中已包含的现有架构中复用代码，参见
[内部机制](https://github.com/usbarmory/tamago/wiki/Internals)。

这些修改保持了[完整的标准库支持](https://github.com/usbarmory/tamago/wiki/Compatibility)。

这些方面的动机是希望提供一个框架，允许在嵌入式系统上进行安全的 Go 固件开发。

当前版本
================

以下链接是
[TamaGo 修改版 Go 发行版](https://github.com/usbarmory/tamago-go)
（为相应 Go 版本添加 `GOOS=tamago` 支持）和
[TamaGo 库](https://github.com/usbarmory/tamago)的最新版本：

[![GitHub release](https://img.shields.io/github/v/release/usbarmory/tamago-go)](https://github.com/usbarmory/tamago-go/releases/latest) [![Build Status](https://github.com/usbarmory/tamago-go/workflows/Build%20Go%20compiler/badge.svg)](https://github.com/usbarmory/tamago-go/actions)  
[![GitHub release](https://img.shields.io/github/v/release/usbarmory/tamago)](https://github.com/usbarmory/tamago/releases/latest)

文档
=============

[![Go Reference](https://pkg.go.dev/badge/github.com/usbarmory/tamago.svg)](https://pkg.go.dev/github.com/usbarmory/tamago)

主要文档可在
[项目 wiki](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              | Platform                                                                  | CPU package                                                    | Platform package                                                                                                                                    |
|------------------|---------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 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 目标
=====================

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

| SoC                   | Board                                                                                                                                                                                | SoC package                                                                  | Board package                                                                          |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| 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 目标
=======================

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

| SoC               | Board                                                                                                    | SoC package                                                                      | Board package                                                                            |
|-------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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 目标
========================

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

| SoC                 | Board                                                                         | SoC package                                                                       | Board package                                                                            |
|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| 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 目标
===========================

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

| SoC             | Board                                                                    | SoC package                                                                       | Board package                                                                |
|-----------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 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` 覆盖层的包，在用户空间中执行，并使用操作系统监督而不是裸机驱动程序。

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

  * 通过内存模拟磁盘与操作系统文件系统隔离
  * 与操作系统网络隔离，参见 [net.SocketFunc](https://github.com/usbarmory/tamago-go/blob/latest/src/net/net_tamago.go)
  * 用于自定义网络、rng、时间处理程序的 API

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

| Operating System                             | `GOARCH`                | Runtime packages                                                                     |
|----------------------------------------------|-------------------------|--------------------------------------------------------------------------------------|
| [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`

编译
=========

支持 `GOOS=tamago` 的 Go 发行版
---------------------------------------

[tamago](https://github.com/usbarmory/tamago/tree/latest/cmd/tamago)
命令会下载、编译并运行来自
[TamaGo 发行版](https://github.com/usbarmory/tamago-go)的 `go` 命令，该发行版与应用程序 `go.mod` 中的 tamago 模块版本匹配。

应用程序可以将 `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
```

构建应用程序
---------------------

编译时，必须设置 `GOOSPKG` Go 环境变量，以启用此库作为 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) - 裸机 Go UEFI 启动管理器
* [GoKey](https://github.com/usbarmory/GoKey) - 裸机 Go 智能卡
* [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 大容量存储固件
* [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) - 裸机代理

使用 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 基于 USB 的以太网驱动程序
* [go-net/virtio](https://github.com/usbarmory/go-net/tree/main/virtio) - VirtIO 网络驱动程序
* [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - i.MX 基于 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)
* [常见问题解答](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 徽标改编自 Renee French 设计的 Go gopher，
并根据 Creative Commons 3.0 署名许可授权。Go Gopher 矢量
插图由 Hugo Arganda 创作。