usbarmory/tamagoFramework for compiling and executing Go applications on bare metal processors, enabling secure firmware development with reduced attack surface through OS and C dependency removal. Goアプリケーションをベアメタルプロセッサ上でコンパイルおよび実行するためのフレームワーク。OSとCの依存関係を取り除くことで攻撃対象領域を減らし、セキュアなファームウェア開発を可能にします。
TamaGo - ベアメタル Go
======================
tamago | https://github.com/usbarmory/tamago
Copyright (c) The TamaGo Authors. All Rights Reserved.
はじめに
============
TamaGo は、ベアメタルプロセッサ上で無改造の Go アプリケーションのコンパイルと実行を可能にするフレームワークです。
このプロジェクトは、C コードやオペレーティングシステムへの実行時依存を排除することで、組み込みシステムファームウェアの攻撃対象領域を削減したいという願いから生まれました。
TamaGo フレームワークは以下のコンポーネントで構成されています：
- `GOOS` サポートを `tamago` ターゲットに拡張した[修正版 Go ディストリビューション](https://github.com/usbarmory/tamago-go)。これにより `GOOSPKG` によって設定される [runtime/goos](https://github.com/usbarmory/tamago-go/tree/latest/src/runtime/goos) オーバーレイを通じたベアメタル実行が可能になります。
- プロセッサ/SoC サポート用の Go パッケージ。
- ボードサポート用の Go パッケージ。
変更は元の Go コンパイラ、ランタイム、およびターゲットアプリケーション（1 つのインポートが必要）に対して最小限であり、他のアーキテクチャから明確に分離されています。
標準 Go ランタイムに既に含まれている既存アーキテクチャからのコード再利用に重点が置かれています。詳細は[内部構造](https://github.com/usbarmory/tamago/wiki/Internals)を参照してください。
変更は[完全な標準ライブラリサポート](https://github.com/usbarmory/tamago/wiki/Compatibility)を維持しています。
このような側面は、組み込みシステム上で安全な Go ファームウェア開発を可能にするフレームワークを提供したいという願いから来ています。
現在のリリース
================
以下のリンクは、対応する Go バージョンに `GOOS=tamago` サポートを追加する [TamaGo 修正版 Go ディストリビューション](https://github.com/usbarmory/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)
主要なドキュメントは[プロジェクト 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` でコンパイルされたプログラムの実行は、ベアメタルドライバの代わりに OS の監督下で必要な `runtime/goos` オーバーレイを実装するパッケージをインポートすることにより、ユーザースペースでも行うことができます。
`GOOS=tamago` としてユーザースペースで Go プログラムをコンパイルおよび実行することは、実行ファイルが Go ランタイムを利用して OS リソースに直接アクセスできないため、システムコール分離の利点を提供します。これにより以下が実現されます：
* インメモリエミュレートディスクによる OS ファイルシステムからの分離
* OS ネットワーキングからの分離、[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) コマンドは、アプリケーションの `go.mod` の tamago モジュールバージョンに一致する [TamaGo ディストリビューション](https://github.com/usbarmory/tamago-go)から `go` コマンドをダウンロード、コンパイル、実行します。
アプリケーションは `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
```
アプリケーションのビルド
---------------------
コンパイル時には、`GOOS=tamago` をサポートするためのオーバーレイとしてこのライブラリを有効にするために、Go 環境変数 `GOOSPKG` を設定する必要があります。
```
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 ファイルを参照してください。
[example application](https://github.com/usbarmory/tamago-example) は、ネイティブおよびエミュレート実行のためのサンプルドライバの使用法と手順を提供しています。
[example application](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) - コンフィデンシャルVM (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 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.
このプロジェクトは、[LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE)ファイルに記載されたBSDスタイルライセンスの下で配布されています。
TamaGoのロゴは、Renee Frenchによってデザインされ、Creative Commons 3.0 Attributionsライセンスの下でライセンスされたGo gopherを基に改変されています。Go GopherのベクターイラストはHugo Argandaによるものです。