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 documents
   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 Standard](https://github.com/riscv/riscv-debug-spec/blob/master/riscv-debug-spec.pdf)
  10 * [RISC-V Assembly Programmer's Manual](https://github.com/riscv/riscv-asm-manual/blob/master/riscv-asm.md)
  11 * [RISC-V ELF psABI Specification](https://github.com/riscv/riscv-elf-psabi-doc/blob/master/riscv-elf.md)
  12
  13 ## Useful RISC-V repositories
  14
  15 * [RISC-V Organization](https://github.com/riscv)
  16   * [RISC-V Linux](https://github.com/riscv/riscv-linux)
  17   * [RISC-V LLD](https://github.com/riscv/riscv-lld)
  18   * [RISC-V Tools](https://github.com/riscv/riscv-tools)
  19     * [RISC-V GNU Toolchain](https://github.com/riscv/riscv-gnu-toolchain)
  20       * [RISC-V Binutils](https://github.com/riscv/riscv-binutils-gdb)
  21       * [RISC-V GCC](https://github.com/riscv/riscv-gcc)
  22       * [RISC-V Glibc](https://github.com/riscv/riscv-glibc)
  23       * [RISC-V Newlib](https://github.com/riscv/riscv-newlib)
  24       * [RISC-V QEMU](https://github.com/riscv/riscv-qemu)
  25     * [RISC-V Opcodes](https://github.com/riscv/riscv-opcodes)
  26     * [RISC-V Tests](https://github.com/riscv/riscv-tests)
  27 * [lowRISC Organization](https://github.com/lowrisc)
  28   * [RISC-V LLVM](https://github.com/lowrisc/riscv-llvm)
  29
  30 ## Setting up a cross environment
  31
  32 Setting up a cross environment with a Linux toolchain and QEMU is quite easy.
  33
  34 First, add these to your `.bashrc` (or some other script that you run):
  35
  36 ```bash
  37 export RISCV=$HOME/riscv
  38 export PATH=$RISCV/bin:$PATH
  39 export QEMU_LD_PREFIX=$RISCV/sysroot
  40 ```
  41
  42 Install some dependencies needed to build the toolchain:
  43
  44 ```console
  45 # apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev libusb-1.0-0-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev device-tree-compiler pkg-config libexpat-dev libglib2.0-dev libpixman-1-dev
  46 ```
  47
  48 Now you can build the toolchain:
  49
  50 ```console
  51 $ git clone --recursive git@github.com:riscv/riscv-tools.git
  52 $ cd riscv-tools
  53 $ ./build.sh
  54 $ cd riscv-gnu-toolchain
  55 $ ./configure --prefix=$RISCV --enable-multilib
  56 $ make linux
  57 $ cd ../..
  58 $ git clone --recursive git@github.com:riscv/riscv-qemu.git
  59 $ cd riscv-qemu
  60 $ mkdir build
  61 $ cd build
  62 $ ../configure --prefix=$RISCV --disable-werror
  63 $ make
  64 $ make install
  65 ```
  66
  67 ## Building Mono with a cross toolchain
  68
  69 Building Mono is quite straightforward:
  70
  71 ```console
  72 $ ./autogen.sh --prefix=$RISCV/sysroot --host=riscv64-unknown-linux-gnu
  73 $ make
  74 $ make install
  75 ```
  76
  77 You can set `CFLAGS` as appropriate to change the RISC-V options, such as which
  78 standard extensions and ABI to use. For example, to use the 64-bit soft float
  79 ABI:
  80
  81 ```console
  82 $ CFLAGS="-mabi=lp64" ./autogen.sh --prefix=$RISCV/sysroot --host=riscv64-unknown-linux-gnu
  83 ```
  84
  85 Note that, since this is a cross build, the `mcs` directory won't be built. You
  86 will have to build the managed libraries and tools through a native build of
  87 Mono and copy them into `$RISCV/sysroot`.
  88
  89 You can run Mono with QEMU like this:
  90
  91 ```console
  92 $ qemu-riscv64 $RISCV/sysroot/bin/mono hello.exe
  93 ```
  94
  95 ## Debugging
  96
  97 ```console
  98 $ qemu-riscv64 -g 12345 ./mono/mini/mono-sgen --interp basic.exe &
  99 $ riscv64-unknown-elf-gdb -ex 'target remote localhost:12345' -ex 'b main' -ex 'c' ./mono/mini/mono-sgen
 100 ```
 101
 102 ## Things to be done
 103
 104 In no particular order:
 105
 106 * Complete the soft float port.
 107 * Complete the 32-bit port.
 108 * Add unwind info to trampolines.
 109 * Implement AOT support.
 110 * Implement interpreter support.
 111 * Implement LLVM support.
 112 * Implement SDB support.
 113 * Implement `dyn_call` support.
 114 * Ensure all runtime tests pass.
 115 * Ensure all corlib tests pass.
 116 * Set up CI on Jenkins.