readme.txt

RISCV Emulator by Fabrice Bellard
=================================

1) Features
-----------

- RISC-V system emulator supporting the RV128IMAFDQC base ISA (user
  level ISA version 2.1, priviledged architecture version 1.9.1)
  including:

  - 32/64/128 bit integer registers
  - 32/64/128 bit floating point instructions
  - Compressed instructions
  - Private extension to change the integer register width (XLEN) dynamically
  
- HTIF console

- IDE block device

- small code, easy to modify, no external dependancies

- Javascript demo version running 64 bit Linux

2) Installation
---------------

- Edit the Makefile to disable the 128 bit target if you compile on a
  32 bit host (for the 128 bit target the compiler must support the
  __int128 C extension).

- Use 'make' to compile the binaries.

- Test the compiled binaries with:

  ./riscvemu -b 32 rv128test.bin
  
  ./riscvemu -b 64 rv128test.bin
  
  ./riscvemu -b 128 rv128test.bin

  [rv128test.bin is a small program working with the 32/64/128 bit ISA]

- Download the example Linux image and use it:

  ./riscvemu bbl.bin root.bin

3) Technical notes
------------------

3.1) 128 bit support

The RISC-V specification does not define all the instruction encodings
for the 128 bit integer and floating point operations. The missing
ones were interpolated from the 32 and 64 ones.

Unfortunately there is no RISC-V 128 bit tool chain nor OS now
(volunteers for the Linux port ?), so rv128test.bin may be the first
128 bit code for RISC-V !

3.2) Floating point emulation

The floating point emulation is bit exact and supports all the
specified instructions for 32, 64 and 128 bit floating point
numbers. It uses the new SoftFP library.

3.3) Dynamic XLEN change

The emulator contains a private extension to dynamically change the
integer register width. It is needed so that for example a 64 bit
Linux can run 32 bit executables. Unfortunately no such feature is
implemented yet in RISC-V Linux, but with this emulator it is possible
to support it.

The 'misa' BASE bits are writable and can be used to make the switch
(see the rv128test.bin demo).

The MSTATUS bits includes the new 'XB' and 'XPB' bits (X=U, S, H or M)
to change the XLEN value when entering and exiting an exception.

3.4) HTIF console

The standard HTIF console uses registers at variable addresses which
are deduced by loading specific ELF symbols. RISCVEMU does not rely on
an ELF loader, so it is much simpler to use registers at fixed
addresses (0x40008000). A small modification was made in the
"riscv-pk" boot loader to support it.

3.5) IDE block device

A memory mapped IDE block device (originated from QEMU then JSLinux)
was added with the minimum PLIC (interrupt controller) support in Linux
(the official RISC-V Linux master does not support the PLIC).

By default, data written to the block device is stored in RAM and not
written to the disk image. The '-rw' command line option allows read
and write access to the disk image.

3.6) Javascript version

A RISC-V 64 bit Javascript demo is provided using emscripten. A 32 bit
version would be much faster, but it is less fun because there are
already plenty of other Javascript 32 bit emulators such as JSLinux or
JOR1K. The tool 'splitimg' is used to create the splitted file disk
image from the provided disk image.

3.7) Optimization

The code is not fully optimized yet, so I expect the speed could be
improved, mainly by optimizing the code fetch. Of course the code base
should be kept small and simple, otherwise it is better to invest time
in QEMU !

4) License
----------

RISCVEMU is released under the MIT license.