github.com/f-secure-foundry/tamago@v0.0.0-20220307101044-d73fcdd7f11b/README.md (about) 1 TamaGo - bare metal Go for ARM SoCs 2 =================================== 3 4 tamago | https://github.com/f-secure-foundry/tamago 5 6 Copyright (c) F-Secure Corporation 7 https://foundry.f-secure.com 8 9 ![TamaGo gopher](https://github.com/f-secure-foundry/tamago/wiki/images/tamago.svg?sanitize=true) 10 11 Authors 12 ======= 13 14 Andrea Barisani 15 andrea.barisani@f-secure.com | andrea@inversepath.com 16 17 Andrej Rosano 18 andrej.rosano@f-secure.com | andrej@inversepath.com 19 20 Introduction 21 ============ 22 23 TamaGo is a framework that enables compilation and execution of unencumbered Go 24 applications on bare metal ARM System-on-Chip (SoC) components. 25 26 The projects spawns from the desire of reducing the attack surface of embedded 27 systems firmware by removing any runtime dependency on C code and Operating 28 Systems. 29 30 The TamaGo framework consists of the following components: 31 32 - A modified [Go distribution](https://github.com/f-secure-foundry/tamago-go) 33 which extends `GOOS` support to the `tamago` target, allowing bare metal 34 execution. 35 36 - Go packages for SoC driver support. 37 38 - Go packages for board support. 39 40 The modifications are meant to be minimal for both the Go distribution (< ~4000 41 LOC changed) and the target application (one import required), with a clean 42 separation from other architectures. 43 44 Strong emphasis is placed on code re-use from existing architectures already 45 included within the standard Go runtime, see 46 [Internals](https://github.com/f-secure-foundry/tamago/wiki/Internals). 47 48 Both aspects are motivated by the desire of providing a framework that allows 49 secure Go firmware development on embedded systems. 50 51 Current release level 52 ===================== 53 [![GitHub release](https://img.shields.io/github/v/release/f-secure-foundry/tamago-go)](https://github.com/f-secure-foundry/tamago-go/tree/latest) [![Build Status](https://github.com/f-secure-foundry/tamago-go/workflows/Build%20Go%20compiler/badge.svg)](https://github.com/f-secure-foundry/tamago-go/actions) 54 55 The current release for the [TamaGo modified Go distribution](https://github.com/f-secure-foundry/tamago-go) is 56 [tamago1.17.8](https://github.com/f-secure-foundry/tamago-go/tree/tamago1.17.8), 57 which [adds](https://github.com/golang/go/compare/go1.17.8...f-secure-foundry:tamago1.17.8) 58 `GOOS=tamago` support to go1.17.8. 59 60 Binary releases for amd64 and armv7l Linux hosts [are available](https://github.com/f-secure-foundry/tamago-go/releases/latest). 61 62 Documentation 63 ============= 64 65 The main documentation can be found on the 66 [project wiki](https://github.com/f-secure-foundry/tamago/wiki). 67 68 The package API documentation can be found on 69 [pkg.go.dev](https://pkg.go.dev/github.com/f-secure-foundry/tamago). 70 71 Supported hardware 72 ================== 73 74 The following table summarizes currently supported SoCs and boards. 75 76 | SoC | Board | SoC package | Board package | 77 |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------| 78 | NXP i.MX6ULZ | [USB armory Mk II](https://github.com/f-secure-foundry/usbarmory/wiki) | [imx6](https://github.com/f-secure-foundry/tamago/tree/master/soc/imx6) | [usbarmory/mark-two](https://github.com/f-secure-foundry/tamago/tree/master/board/f-secure/usbarmory) | 79 | NXP i.MX6ULL | [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) | [imx6](https://github.com/f-secure-foundry/tamago/tree/master/soc/imx6) | [mx6ullevk](https://github.com/f-secure-foundry/tamago/tree/master/board/nxp/mx6ullevk) | 80 | BCM2835 | [Raspberry Pi Zero](https://www.raspberrypi.org/products/raspberry-pi-zero) | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pizero](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi) | 81 | BCM2835 | [Raspberry Pi 1 Model A+](https://www.raspberrypi.org/products/raspberry-pi-1-model-a-plus/) | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi) | 82 | BCM2835 | [Raspberry Pi 1 Model B+](https://www.raspberrypi.org/products/raspberry-pi-1-model-b-plus/) | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi) | 83 | BCM2836 | [Raspberry Pi 2 Model B](https://www.raspberrypi.org/products/raspberry-pi-2-model-b) | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi2](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi) | 84 85 Compiling 86 ========= 87 88 Go applications are simply required to import, the relevant board package to 89 ensure that hardware initialization and runtime support takes place: 90 91 ```golang 92 import ( 93 // Example for USB armory Mk II 94 _ "github.com/f-secure-foundry/tamago/board/f-secure/usbarmory/mark-two" 95 ) 96 ``` 97 98 Build the [TamaGo compiler](https://github.com/f-secure-foundry/tamago-go) 99 (or use the [latest binary release](https://github.com/f-secure-foundry/tamago-go/releases/latest)): 100 101 ``` 102 wget https://github.com/f-secure-foundry/tamago-go/archive/refs/tags/latest.zip 103 unzip latest.zip 104 cd tamago-go-latest/src && ./all.bash 105 cd ../bin && export TAMAGO=`pwd`/go 106 ``` 107 108 Go applications can be compiled with the compiler built in the previous step, 109 with the addition of a few flags/variables: 110 111 ``` 112 # Example for USB armory Mk II 113 GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \ 114 ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_arm_tamago -R 0x1000" 115 ``` 116 117 See the respective board package README file for compilation information for 118 each specific target. 119 120 Executing and debugging 121 ======================= 122 123 See the respective board package README file for execution and debugging 124 information for each specific target (real or emulated). 125 126 The [example application](https://github.com/f-secure-foundry/tamago-example) 127 provides sample driver usage and instructions for native as well as emulated 128 execution. 129 130 License 131 ======= 132 133 tamago | https://github.com/f-secure-foundry/tamago 134 Copyright (c) F-Secure Corporation 135 136 These source files are distributed under the BSD-style license found in the 137 [LICENSE](https://github.com/f-secure-foundry/tamago/blob/master/LICENSE) file. 138 139 The TamaGo logo is adapted from the Go gopher designed by Renee French and 140 licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector 141 illustration by Hugo Arganda.