github.com/usbarmory/tamago@v0.0.0-20240508072735-8612bbe1e454/README.md (about) 1 TamaGo - bare metal Go for ARM/RISC-V SoCs 2 ========================================== 3 4 tamago | https://github.com/usbarmory/tamago 5 6 Copyright (c) WithSecure Corporation 7 https://foundry.withsecure.com 8 9  10 11 Introduction 12 ============ 13 14 TamaGo is a framework that enables compilation and execution of unencumbered Go 15 applications on bare metal ARM/RISC-V System-on-Chip (SoC) components. 16 17 The projects spawns from the desire of reducing the attack surface of embedded 18 systems firmware by removing any runtime dependency on C code and Operating 19 Systems. 20 21 The TamaGo framework consists of the following components: 22 23 - A modified [Go distribution](https://github.com/usbarmory/tamago-go) 24 which extends `GOOS` support to the `tamago` target, allowing bare metal 25 execution. 26 27 - Go packages for SoC driver support. 28 29 - Go packages for board support. 30 31 The modifications are meant to be minimal for both the Go distribution (< ~4000 32 LOC changed) and the target application (one import required), with a clean 33 separation from other architectures. 34 35 Strong emphasis is placed on code re-use from existing architectures already 36 included within the standard Go runtime, see 37 [Internals](https://github.com/usbarmory/tamago/wiki/Internals). 38 39 Both aspects are motivated by the desire of providing a framework that allows 40 secure Go firmware development on embedded systems. 41 42 Current release level 43 ===================== 44 [](https://github.com/usbarmory/tamago-go/tree/latest) [](https://github.com/usbarmory/tamago-go/actions) 45 46 The current release for the [TamaGo modified Go distribution](https://github.com/usbarmory/tamago-go) is 47 [tamago1.22.3](https://github.com/usbarmory/tamago-go/tree/tamago1.22.3), 48 which [adds](https://github.com/golang/go/compare/go1.22.3...usbarmory:tamago1.22.3) 49 `GOOS=tamago` support to go1.22.3. 50 51 Binary releases for amd64 and armv7l Linux hosts [are available](https://github.com/usbarmory/tamago-go/releases/latest). 52 53 Documentation 54 ============= 55 56 The main documentation can be found on the 57 [project wiki](https://github.com/usbarmory/tamago/wiki). 58 59 The package API documentation can be found on 60 [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago). 61 62 63 Supported ARM hardware 64 ======================= 65 66 The following table summarizes currently supported ARM SoCs and boards 67 (`GOOS=tamago GOARCH=arm`). 68 69 | SoC | Board | SoC package | Board package | 70 |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------| 71 | 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) | 72 | 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) | 73 | 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) | 74 | 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) | 75 | 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) | 76 | 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) | 77 | 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) | 78 79 Supported RISC-V hardware 80 ========================== 81 82 The following table summarizes currently supported RISC-V SoCs and boards 83 (`GOOS=tamago GOARCH=riscv64`). 84 85 | SoC | Board | SoC package | Board package | 86 |--------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------| 87 | 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) | 88 89 Compiling 90 ========= 91 92 Go applications are simply required to import, the relevant board package to 93 ensure that hardware initialization and runtime support takes place: 94 95 ```golang 96 import ( 97 // Example for USB armory Mk II 98 _ "github.com/usbarmory/tamago/board/usbarmory/mk2" 99 ) 100 ``` 101 102 Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go) 103 (or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)): 104 105 ``` 106 wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip 107 unzip latest.zip 108 cd tamago-go-latest/src && ./all.bash 109 cd ../bin && export TAMAGO=`pwd`/go 110 ``` 111 112 Go applications can be compiled with the compiler built in the previous step, 113 with the addition of a few flags/variables: 114 115 ``` 116 # Example for USB armory Mk II 117 GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \ 118 ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_arm_tamago -R 0x1000" 119 120 # Example for QEMU RISC-V sifive_u 121 GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARCH=riscv64 \ 122 ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_riscv64_tamago -R 0x1000" 123 ``` 124 125 See the respective board package README file for compilation information for 126 each specific target. 127 128 Executing and debugging 129 ======================= 130 131 See the respective board package README file for execution and debugging 132 information for each specific target (real or emulated). 133 134 The [example application](https://github.com/usbarmory/tamago-example) 135 provides sample driver usage and instructions for native as well as emulated 136 execution. 137 138 An emulated run of the [example application](https://github.com/usbarmory/tamago-example) 139 can be launched as follows: 140 141 ``` 142 git clone https://github.com/usbarmory/tamago-example 143 cd tamago-example && make qemu 144 ``` 145 146 Applications using TamaGo 147 ========================= 148 149 * [GoKey](https://github.com/usbarmory/GoKey) - the bare metal Go smartcard 150 * [GoTEE](https://github.com/usbarmory/GoTEE) - Go Trusted Execution Environment 151 * [armory-drive](https://github.com/usbarmory/armory-drive) - USB encrypted drive 152 * [armory-ums](https://github.com/usbarmory/armory-ums) - USB Mass Storage firmware 153 * [armory-boot](https://github.com/usbarmory/armory-boot) - primary bootloader 154 * [tamago-example](https://github.com/usbarmory/tamago-example) - TamaGo example application 155 156 External drivers using TamaGo 157 ============================= 158 159 * [imx-usbserial](https://github.com/usbarmory/imx-usbserial) - i.MX Serial over USB driver 160 * [imx-usbnet](https://github.com/usbarmory/imx-usbnet) - i.MX Ethernet over USB driver 161 * [imx-enet](https://github.com/usbarmory/imx-enet) - i.MX Ethernet driver 162 163 Additional resources 164 ==================== 165 166 * [Package API](https://pkg.go.dev/github.com/usbarmory/tamago) 167 * [Internals](https://github.com/usbarmory/tamago/wiki/Internals) 168 * [Go stdlib support](https://github.com/usbarmory/tamago/wiki/Import-report) 169 * [FAQ](https://github.com/usbarmory/tamago/wiki/Frequently-Asked-Questions-(FAQ)) 170 * [TamaGo presentation](https://github.com/abarisani/abarisani.github.io/tree/master/research/tamago) 171 172 Maintainers 173 =========== 174 175 Andrea Barisani 176 andrea.barisani@withsecure.com | andrea@inversepath.com 177 178 Andrej Rosano 179 andrej.rosano@withsecure.com | andrej@inversepath.com 180 181 License 182 ======= 183 184 tamago | https://github.com/usbarmory/tamago 185 Copyright (c) WithSecure Corporation 186 187 This project is distributed under the BSD-style license found in the 188 [LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE) file. 189 190 The TamaGo logo is adapted from the Go gopher designed by Renee French and 191 licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector 192 illustration by Hugo Arganda.