github.com/usbarmory/tamago@v0.0.0-20240508072735-8612bbe1e454/board/qemu/sifive_u/README.md (about) 1 TamaGo - bare metal Go for RISC-V SoCs - QEMU sifive_u support 2 ============================================================== 3 4 tamago | https://github.com/usbarmory/tamago 5 6 Copyright (c) WithSecure Corporation 7 https://foundry.withsecure.com 8 9 ![TamaGo gopher](https://github.com/usbarmory/tamago/wiki/images/tamago.svg?sanitize=true) 10 11 Authors 12 ======= 13 14 Andrea Barisani 15 andrea.barisani@withsecure.com | andrea@inversepath.com 16 17 Andrej Rosano 18 andrej.rosano@withsecure.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/RISC-V System-on-Chip (SoC) components. 25 26 The [sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u) 27 package provides support for the [QEMU sifive_u](https://qemu.readthedocs.io/en/latest/system/riscv/sifive_u.html) 28 emulated machine configured with a single U54 core. 29 30 Documentation 31 ============= 32 33 For more information about TamaGo see its 34 [repository](https://github.com/usbarmory/tamago) and 35 [project wiki](https://github.com/usbarmory/tamago/wiki). 36 37 For the underlying driver support for this board see package 38 [fu540](https://github.com/usbarmory/tamago/tree/master/soc/sifive/fu540). 39 40 The package API documentation can be found on 41 [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago). 42 43 Supported hardware 44 ================== 45 46 | SoC | Board | SoC package | Board package | 47 |--------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------| 48 | 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) | 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/usbarmory/tamago/board/qemu/sifive_u" 59 ) 60 ``` 61 62 Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go) 63 (or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)): 64 65 ``` 66 wget https://github.com/usbarmory/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 GOARCH=riscv64 \ 78 ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_riscv64_tamago -R 0x1000" 79 ``` 80 81 An example application, targeting the QEMU sifive_u platform, 82 is [available](https://github.com/usbarmory/tamago-example). 83 84 Executing and debugging 85 ======================= 86 87 The [example application](https://github.com/usbarmory/tamago-example) provides 88 reference usage and a Makefile target for automatic creation of an ELF image as 89 well as emulated execution. 90 91 QEMU 92 ---- 93 94 The target can be executed under emulation as follows: 95 96 ``` 97 dtc -I dts -O dtb qemu-riscv64-sifive_u.dts -o qemu-riscv54-sifive_u.dtb 98 99 qemu-system-riscv64 \ 100 -machine sifive_u -m 512M \ 101 -nographic -monitor none -serial stdio -net none 102 -dtb qemu-riscv64-sifive_u.dtb \ 103 -bios bios.bin 104 ``` 105 106 At this time a bios is required to jump to the correct entry point of the ELF 107 image, the [example application](https://github.com/usbarmory/tamago-example) 108 includes a minimal bios which is configured and compiled for all riscv64 `qemu` 109 targets. 110 111 The emulated target can be debugged with GDB by adding the `-S -s` flags to the 112 previous execution command, this will make qemu waiting for a GDB connection 113 that can be launched as follows: 114 115 ``` 116 riscv64-elf-gdb -ex "target remote 127.0.0.1:1234" example 117 ``` 118 119 Breakpoints can be set in the usual way: 120 121 ``` 122 b ecdsa.Verify 123 continue 124 ``` 125 126 License 127 ======= 128 129 tamago | https://github.com/usbarmory/tamago 130 Copyright (c) WithSecure Corporation 131 132 These source files are distributed under the BSD-style license found in the 133 [LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE) file. 134 135 The TamaGo logo is adapted from the Go gopher designed by Renee French and 136 licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector 137 illustration by Hugo Arganda.