204 lines
6.1 KiB
Text
204 lines
6.1 KiB
Text
TinyEMU System Emulator by Fabrice Bellard
|
|
==========================================
|
|
|
|
1) Features
|
|
-----------
|
|
|
|
- RISC-V system emulator supporting the RV128IMAFDQC base ISA (user
|
|
level ISA version 2.2, priviledged architecture version 1.10)
|
|
including:
|
|
|
|
- 32/64/128 bit integer registers
|
|
- 32/64/128 bit floating point instructions
|
|
- Compressed instructions
|
|
- dynamic XLEN change
|
|
|
|
- x86 system emulator based on KVM
|
|
|
|
- VirtIO console, network, block device, input and 9P filesystem
|
|
|
|
- Graphical display with SDL
|
|
|
|
- JSON configuration file
|
|
|
|
- Remote HTTP block device and filesystem
|
|
|
|
- small code, easy to modify, no external dependancies
|
|
|
|
- Javascript demo version
|
|
|
|
2) Installation
|
|
---------------
|
|
|
|
- The libraries libcurl, OpenSSL and SDL should be installed. On a Fedora
|
|
system you can do it with:
|
|
|
|
sudo dnf install openssl-devel libcurl-devel SDL-devel
|
|
|
|
It is possible to compile the programs without these libraries by
|
|
commenting CONFIG_FS_NET and/or CONFIG_SDL in the Makefile.
|
|
|
|
- Edit the Makefile to disable the 128 bit target if you compile on a
|
|
32 bit host (for the 128 bit RISCV target the compiler must support
|
|
the __int128 C extension).
|
|
|
|
- Use 'make' to compile the binaries.
|
|
|
|
- You can optionally install the program to '/usr/local/bin' with:
|
|
|
|
make install
|
|
|
|
3) Usage
|
|
--------
|
|
|
|
3.1 Quick examples
|
|
------------------
|
|
|
|
- Use the VM images available from https://bellard.org/jslinux (no
|
|
need to download them):
|
|
|
|
Terminal:
|
|
|
|
./temu https://bellard.org/jslinux/buildroot-riscv64.cfg
|
|
|
|
Graphical (with SDL):
|
|
|
|
./temu https://bellard.org/jslinux/buildroot-x86-xwin.cfg
|
|
|
|
./temu https://bellard.org/jslinux/win2k.cfg
|
|
|
|
- Download the example RISC-V Linux image
|
|
(diskimage-linux-riscv-yyyy-mm-dd.tar.gz) and use it:
|
|
|
|
./temu root-riscv64.cfg
|
|
|
|
./temu rv128test/rv128test.cfg
|
|
|
|
- Access to your local hard disk (/tmp directory) in the guest:
|
|
|
|
./temu root_9p-riscv64.cfg
|
|
|
|
then type:
|
|
mount -t 9p /dev/root /mnt
|
|
|
|
in the guest. The content of the host '/tmp' directory is visible in '/mnt'.
|
|
|
|
3.2 Invocation
|
|
--------------
|
|
|
|
usage: temu [options] config_file
|
|
options are:
|
|
-m ram_size set the RAM size in MB
|
|
-rw allow write access to the disk image (default=snapshot)
|
|
-ctrlc the C-c key stops the emulator instead of being sent to the
|
|
emulated software
|
|
-append cmdline append cmdline to the kernel command line
|
|
-no-accel disable VM acceleration (KVM, x86 machine only)
|
|
|
|
Console keys:
|
|
Press C-a x to exit the emulator, C-a h to get some help.
|
|
|
|
3.3 Network usage
|
|
-----------------
|
|
|
|
The easiest way is to use the "user" mode network driver. No specific
|
|
configuration is necessary.
|
|
|
|
TinyEMU also supports a "tap" network driver to redirect the network
|
|
traffic from a VirtIO network adapter.
|
|
|
|
You can look at the netinit.sh script to create the tap network
|
|
interface and to redirect the virtual traffic to Internet thru a
|
|
NAT. The exact configuration may depend on the Linux distribution and
|
|
local firewall configuration.
|
|
|
|
The VM configuration file must include:
|
|
|
|
eth0: { driver: "tap", ifname: "tap0" }
|
|
|
|
and configure the network in the guest system with:
|
|
|
|
ifconfig eth0 192.168.3.2
|
|
route add -net 0.0.0.0 gw 192.168.3.1 eth0
|
|
|
|
3.4 Network filesystem
|
|
----------------------
|
|
|
|
TinyEMU supports the VirtIO 9P filesystem to access local or remote
|
|
filesystems. For remote filesystems, it does HTTP requests to download
|
|
the files. The protocol is compatible with the vfsync utility. In the
|
|
"mount" command, "/dev/rootN" must be used as device name where N is
|
|
the index of the filesystem. When N=0 it is omitted.
|
|
|
|
The build_filelist tool builds the file list from a root directory. A
|
|
simple web server is enough to serve the files.
|
|
|
|
The '.preload' file gives a list of files to preload when opening a
|
|
given file.
|
|
|
|
3.5 Network block device
|
|
------------------------
|
|
|
|
TinyEMU supports an HTTP block device. The disk image is split into
|
|
small files. Use the 'splitimg' utility to generate images. The URL of
|
|
the JSON blk.txt file must be provided as disk image filename.
|
|
|
|
4) Technical notes
|
|
------------------
|
|
|
|
4.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 toolchain nor OS now
|
|
(volunteers for the Linux port ?), so rv128test.bin may be the first
|
|
128 bit code for RISC-V !
|
|
|
|
4.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.
|
|
|
|
4.3) HTIF console
|
|
|
|
The standard HTIF console uses registers at variable addresses which
|
|
are deduced by loading specific ELF symbols. TinyEMU 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. The HTIF console is only used to
|
|
display boot messages and to power off the virtual system. The OS
|
|
should use the VirtIO console.
|
|
|
|
4.4) Javascript version
|
|
|
|
The Javascript version (JSLinux) can be compiled with Makefile.js and
|
|
emscripten. A complete precompiled and preconfigured demo is available
|
|
in the jslinux-yyyy-mm-dd.tar.gz archive (read the readme.txt file
|
|
inside the archive).
|
|
|
|
4.5) x86 emulator
|
|
|
|
A small x86 emulator is included. It is not really an emulator because
|
|
it uses the Linux KVM API to run the x86 code at near native
|
|
performance. The x86 emulator uses the same set of VirtIO devices as
|
|
the RISCV emulator and is able to run many operating systems.
|
|
|
|
The x86 emulator accepts a Linux kernel image (bzImage). No BIOS image
|
|
is necessary.
|
|
|
|
The x86 emulator comes from my JS/Linux project (2011) which was one
|
|
of the first emulator running Linux fully implemented in
|
|
Javascript. It is provided to allow easy access to the x86 images
|
|
hosted at https://bellard.org/jslinux .
|
|
|
|
|
|
5) License / Credits
|
|
--------------------
|
|
|
|
TinyEMU is released under the MIT license. If there is no explicit
|
|
license in a file, the license from MIT-LICENSE.txt applies.
|
|
|
|
The SLIRP library has its own license (two clause BSD license).
|