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.