readme.txt - emulators/tinyemu - Rivoreo Source Code Repositories

 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).
	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).