docs/riscv.md

   1 # Mono RISC-V Port
   2
   3 These are some useful links and notes pertaining to the RISC-V port of Mono.
   4
   5 ## Useful RISC-V documentation
   6
   7 * [RISC-V User-Level ISA Specification](https://riscv.org/specifications)
   8 * [RISC-V Privileged ISA Specification](https://riscv.org/specifications/privileged-isa)
   9 * [RISC-V Debug Specification](https://riscv.org/specifications/debug-specification)
  10 * [RISC-V ELF psABI Specification](https://github.com/riscv/riscv-elf-psabi-doc)
  11 * [RISC-V C API Specification](https://github.com/riscv/riscv-c-api-doc)
  12 * [RISC-V Toolchain Conventions](https://github.com/riscv/riscv-toolchain-conventions)
  13 * [RISC-V Assembly Programmer's Manual](https://github.com/riscv/riscv-asm-manual)
  14
  15 ## Useful RISC-V repositories
  16
  17 * [RISC-V Organization](https://github.com/riscv)
  18   * [RISC-V GNU Toolchain](https://github.com/riscv/riscv-gnu-toolchain)
  19     * [RISC-V Binutils](https://github.com/riscv/riscv-binutils-gdb)
  20     * [RISC-V GCC](https://github.com/riscv/riscv-gcc)
  21     * [RISC-V Glibc](https://github.com/riscv/riscv-glibc)
  22     * [RISC-V Newlib](https://github.com/riscv/riscv-newlib)
  23   * [RISC-V Tools](https://github.com/riscv/riscv-tools)
  24     * [RISC-V Opcodes](https://github.com/riscv/riscv-opcodes)
  25     * [RISC-V Tests](https://github.com/riscv/riscv-tests)
  26
  27 ## Setting up a cross environment
  28
  29 ### Debian/Ubuntu packages
  30
  31 This is the most painless way of getting a functional toolchain installed. Note
  32 that these packages may not be available on older distributions; this is tested
  33 on Ubuntu 19.04.
  34
  35 First, add this to your `$HOME/.bashrc` (or some other script that you run):
  36
  37 ```bash
  38 export RISCV=$HOME/riscv
  39 export PATH=$RISCV/bin:$PATH
  40 export QEMU_LD_PREFIX=/usr/riscv64-linux-gnu
  41 ```
  42
  43 Next, install the toolchain packages like so:
  44
  45 ```bash
  46 # apt install autoconf automake binutils-riscv64-linux-gnu build-essential gcc-riscv64-linux-gnu gdb-multiarch g++-riscv64-linux-gnu libtool qemu qemu-system-misc qemu-user qemu-user-static
  47 ```
  48
  49 You will now have all the toolchain binaries in `/usr/bin`.
  50
  51 ### Building manually
  52
  53 This approach may be somewhat unstable since you will be using the latest
  54 versions of the various parts of the toolchain.
  55
  56 First, add this to your `$HOME/.bashrc` (or some other script that you run):
  57
  58 ```bash
  59 export RISCV=$HOME/riscv
  60 export PATH=$RISCV/bin:$PATH
  61 export QEMU_LD_PREFIX=$RISCV/sysroot
  62 ```
  63
  64 Next, install some dependencies needed to build the toolchain:
  65
  66 ```console
  67 # apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
  68 ```
  69
  70 Finally, build the toolchain:
  71
  72 ```console
  73 $ git clone --recursive git@github.com:riscv/riscv-gnu-toolchain.git
  74 $ cd riscv-gnu-toolchain
  75 $ ./configure --prefix=$RISCV --enable-linux --enable-multilib --with-arch=rv64imafdc --with-abi=lp64d
  76 $ make linux
  77 ```
  78
  79 This will install the built toolchain binaries in `$RISCV/bin`.
  80
  81 ## Building Mono with a cross toolchain
  82
  83 Building Mono is quite straightforward:
  84
  85 ```console
  86 $ ./autogen.sh --prefix=$RISCV/sysroot --host=riscv64-linux-gnu
  87 $ make
  88 $ make install
  89 ```
  90
  91 (Note: You may need to use `--host=riscv64-unknown-linux-gnu` instead if you
  92 built the toolchain manually.)
  93
  94 You can set `CFLAGS` as appropriate to change the RISC-V options, such as which
  95 standard extensions and ABI to use. For example, to use the 64-bit soft float
  96 ABI:
  97
  98 ```console
  99 $ CFLAGS="-mabi=lp64" ./autogen.sh --prefix=$RISCV/sysroot --host=riscv64-linux-gnu
 100 ```
 101
 102 Note that, since this is a cross build, the `mcs` directory won't be built. You
 103 will have to build the managed libraries and tools through a native build of
 104 Mono and copy them into `$RISCV/sysroot`.
 105
 106 You can run Mono with QEMU like this:
 107
 108 ```console
 109 $ qemu-riscv64 ./mono/mini/mono hello.exe
 110 ```
 111
 112 ## Debugging
 113
 114 Debugging with GDB currently requires a manually built toolchain.
 115
 116 It can be done like so:
 117
 118 ```console
 119 $ qemu-riscv64 -g 12345 ./mono/mini/mono --interp basic.exe &
 120 $ riscv64-unknown-elf-gdb -ex 'target remote localhost:12345' -ex 'b main' -ex 'c' ./mono/mini/mono
 121 ```
 122
 123 ## Things to be done
 124
 125 Things that need to be done beyond the basic 64-bit port, in no particular
 126 order:
 127
 128 * Complete the soft float port.
 129 * Complete the 32-bit port.
 130 * Add unwind info to trampolines.
 131 * Implement AOT support.
 132 * Implement interpreter support.
 133 * Implement LLVM support.
 134 * Implement SDB support.
 135 * Implement `dyn_call` support.
 136 * Ensure all runtime tests pass.
 137 * Ensure all corlib tests pass.
 138 * Set up CI on Jenkins.