github.com/f-secure-foundry/tamago@v0.0.0-20220307101044-d73fcdd7f11b/board/f-secure/usbarmory/README.md (about) 1 TamaGo - bare metal Go for ARM SoCs - USB armory support 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  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 [usbarmory](https://github.com/f-secure-foundry/tamago/tree/master/board/f-secure/usbarmory) 27 package provides support for the [USB armory](https://github.com/f-secure-foundry/usbarmory/wiki) 28 Single Board Computer. 29 30 Documentation 31 ============= 32 33 For more information about TamaGo see its 34 [repository](https://github.com/f-secure-foundry/tamago) and 35 [project wiki](https://github.com/f-secure-foundry/tamago/wiki). 36 37 For the underlying driver support for this board see package 38 [imx6](https://github.com/f-secure-foundry/tamago/tree/master/soc/imx6). 39 40 The package API documentation can be found on 41 [pkg.go.dev](https://pkg.go.dev/github.com/f-secure-foundry/tamago). 42 43 Supported hardware 44 ================== 45 46 | SoC | Board | SoC package | Board package | 47 |---------------|------------------------------------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| 48 | 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/mark-two) | 49 50 Compiling 51 ========= 52 53 Go applications are simply required to import, the relevant board package to 54 ensure that hardware initialization and runtime support takes place: 55 56 ```golang 57 import ( 58 _ "github.com/f-secure-foundry/tamago/board/f-secure/usbarmory/mark-two" 59 ) 60 ``` 61 62 Build the [TamaGo compiler](https://github.com/f-secure-foundry/tamago-go) 63 (or use the [latest binary release](https://github.com/f-secure-foundry/tamago-go/releases/latest)): 64 65 ``` 66 wget https://github.com/f-secure-foundry/tamago-go/archive/refs/tags/latest.zip 67 unzip latest.zip 68 cd tamago-go-latest/src && ./all.bash 69 cd ../bin && export TAMAGO=`pwd`/go 70 ``` 71 72 Go applications can be compiled as usual, using the compiler built in the 73 previous step, but with the addition of the following flags/variables and 74 ensuring that the required SoC and board packages are available in `GOPATH`: 75 76 ``` 77 GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \ 78 ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_arm_tamago -R 0x1000" 79 ``` 80 81 An example application, targeting the USB armory Mk II platform, 82 is [available](https://github.com/f-secure-foundry/tamago-example). 83 84 Executing and debugging 85 ======================= 86 87 The [example application](https://github.com/f-secure-foundry/tamago-example) 88 provides reference usage and a Makefile target for automatic creation of an ELF 89 as well as `imx` image for flashing. 90 91 Native hardware: imx image 92 -------------------------- 93 94 Follow [these instructions](https://github.com/f-secure-foundry/usbarmory/wiki/Boot-Modes-(Mk-II)#flashing-bootable-images-on-externalinternal-media) 95 using built `imx` images. 96 97 Native hardware: existing bootloader 98 ------------------------------------ 99 100 Copy the built ELF binary on an external microSD card (replace `$dev` with `0`) 101 or the internal eMMC (replace `$dev` with `1`), then launch it from the U-Boot 102 console as follows: 103 104 ``` 105 ext2load mmc $dev:1 0x90000000 example 106 bootelf -p 0x90000000 107 ``` 108 109 For non-interactive execution modify the U-Boot configuration accordingly. 110 111 Standard output 112 --------------- 113 114 The standard output can be accessed through the 115 [debug accessory](https://github.com/f-secure-foundry/usbarmory/tree/master/hardware/mark-two-debug-accessory) 116 and the following `picocom` configuration: 117 118 ``` 119 picocom -b 115200 -eb /dev/ttyUSB2 --imap lfcrlf 120 ``` 121 122 Debugging 123 --------- 124 125 The application can be debugged with GDB over JTAG using `openocd` (version > 126 0.11.0) and the `gdbinit` debugging helper published 127 [here](https://github.com/f-secure-foundry/tamago/tree/master/_dev). 128 129 ``` 130 # start openocd daemon 131 openocd -f interface/ftdi/jtagkey.cfg -f target/imx6ul.cfg -c "adapter speed 1000" 132 133 # connect to the OpenOCD command line 134 telnet localhost 4444 135 136 # debug with GDB 137 arm-none-eabi-gdb -x gdbinit example 138 ``` 139 140 Hardware breakpoints can be set in the usual way: 141 142 ``` 143 hb ecdsa.Verify 144 continue 145 ``` 146 147 QEMU 148 ---- 149 150 The target can be executed under emulation as follows: 151 152 ``` 153 qemu-system-arm \ 154 -machine mcimx6ul-evk -cpu cortex-a7 -m 512M 155 \ -nographic -monitor none -serial null -serial stdio -net none 156 \ -kernel example -semihosting -d unimp 157 ``` 158 159 The emulated target can be debugged with GDB by adding the `-S -s` flags to the 160 previous execution command, this will make qemu waiting for a GDB connection 161 that can be launched as follows: 162 163 ``` 164 arm-none-eabi-gdb -ex "target remote 127.0.0.1:1234" example 165 ``` 166 167 Breakpoints can be set in the usual way: 168 169 ``` 170 b ecdsa.Verify 171 continue 172 ``` 173 174 License 175 ======= 176 177 tamago | https://github.com/f-secure-foundry/tamago 178 Copyright (c) F-Secure Corporation 179 180 These source files are distributed under the BSD-style license found in the 181 [LICENSE](https://github.com/f-secure-foundry/tamago/blob/master/LICENSE) file. 182 183 The TamaGo logo is adapted from the Go gopher designed by Renee French and 184 licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector 185 illustration by Hugo Arganda.