[mirror_qemu.git] / tcg / tci / README

TCG Interpreter (TCI) - Copyright (c) 2011 Stefan Weil.

This file is released under the BSD license.

1) Introduction

TCG (Tiny Code Generator) is a code generator which translates
code fragments ("basic blocks") from target code (any of the
targets supported by QEMU) to a code representation which
can be run on a host.

QEMU can create native code for some hosts (arm, i386, ia64, ppc, ppc64,
s390, sparc, x86_64). For others, unofficial host support was written.

By adding a code generator for a virtual machine and using an
interpreter for the generated bytecode, it is possible to
support (almost) any host.

This is what TCI (Tiny Code Interpreter) does.

2) Implementation

Like each TCG host frontend, TCI implements the code generator in
tcg-target.c.inc, tcg-target.h. Both files are in directory tcg/tci.

The additional file tcg/tci.c adds the interpreter and disassembler.

The bytecode consists of opcodes (with only a few exceptions, with
the same same numeric values and semantics as used by TCG), and up
to six arguments packed into a 32-bit integer.  See comments in tci.c
for details on the encoding.

3) Usage

For hosts without native TCG, the interpreter TCI must be enabled by

        configure --enable-tcg-interpreter

If configure is called without --enable-tcg-interpreter, it will
suggest using this option. Setting it automatically would need
additional code in configure which must be fixed when new native TCG
implementations are added.

For hosts with native TCG, the interpreter TCI can be enabled by

        configure --enable-tcg-interpreter

The only difference from running QEMU with TCI to running without TCI
should be speed. Especially during development of TCI, it was very
useful to compare runs with and without TCI. Create /tmp/qemu.log by

        qemu-system-i386 -d in_asm,op_opt,cpu -D /tmp/qemu.log -accel tcg,one-insn-per-tb=on

once with interpreter and once without interpreter and compare the resulting
qemu.log files. This is also useful to see the effects of additional
registers or additional opcodes (it is easy to modify the virtual machine).
It can also be used to verify native TCGs.

Hosts with native TCG can also enable TCI by claiming to be unsupported:

        configure --cpu=unknown --enable-tcg-interpreter

configure then no longer uses the native linker script (*.ld) for
user mode emulation.


4) Status

TCI needs special implementation for 32 and 64 bit host, 32 and 64 bit target,
host and target with same or different endianness.

            | host (le)                     host (be)
            | 32             64             32             64
------------+------------------------------------------------------------
target (le) | s0, u0         s1, u1         s?, u?         s?, u?
32 bit      |
            |
target (le) | sc, uc         s1, u1         s?, u?         s?, u?
64 bit      |
            |
target (be) | sc, u0         sc, uc         s?, u?         s?, u?
32 bit      |
            |
target (be) | sc, uc         sc, uc         s?, u?         s?, u?
64 bit      |
            |

System emulation
s? = untested
sc = compiles
s0 = bios works
s1 = grub works
s2 = Linux boots

Linux user mode emulation
u? = untested
uc = compiles
u0 = static hello works
u1 = linux-user-test works

5) Todo list

* TCI is not widely tested. It was written and tested on a x86_64 host
  running i386 and x86_64 system emulation and Linux user mode.
  A cross compiled QEMU for i386 host also works with the same basic tests.
  A cross compiled QEMU for mipsel host works, too. It is terribly slow
  because I run it in a mips malta emulation, so it is an interpreted
  emulation in an emulation.
  A cross compiled QEMU for arm host works (tested with pc bios).
  A cross compiled QEMU for ppc host works at least partially:
  i386-linux-user/qemu-i386 can run a simple hello-world program
  (tested in a ppc emulation).

* Some TCG opcodes are either missing in the code generator and/or
  in the interpreter. These opcodes raise a runtime exception, so it is
  possible to see where code must be added.

* It might be useful to have a runtime option which selects the native TCG
  or TCI, so QEMU would have to include two TCGs. Today, selecting TCI
  is a configure option, so you need two compilations of QEMU.
Commit	Line	Data
7316329a SW	1	TCG Interpreter (TCI) - Copyright (c) 2011 Stefan Weil.
	2
	3	This file is released under the BSD license.
	4
	5	1) Introduction
	6
	7	TCG (Tiny Code Generator) is a code generator which translates
	8	code fragments ("basic blocks") from target code (any of the
	9	targets supported by QEMU) to a code representation which
	10	can be run on a host.
	11
d41f3c3c	12	QEMU can create native code for some hosts (arm, i386, ia64, ppc, ppc64,
7316329a SW	13	s390, sparc, x86_64). For others, unofficial host support was written.
	14
	15	By adding a code generator for a virtual machine and using an
	16	interpreter for the generated bytecode, it is possible to
	17	support (almost) any host.
	18
	19	This is what TCI (Tiny Code Interpreter) does.
	20
	21	2) Implementation
	22
	23	Like each TCG host frontend, TCI implements the code generator in
139c1837	24	tcg-target.c.inc, tcg-target.h. Both files are in directory tcg/tci.
7316329a	25
65089889	26	The additional file tcg/tci.c adds the interpreter and disassembler.
7316329a	27
65089889 RH	28	The bytecode consists of opcodes (with only a few exceptions, with
	29	the same same numeric values and semantics as used by TCG), and up
	30	to six arguments packed into a 32-bit integer. See comments in tci.c
	31	for details on the encoding.
7316329a SW	32
	33	3) Usage
	34
	35	For hosts without native TCG, the interpreter TCI must be enabled by
	36
	37	configure --enable-tcg-interpreter
	38
	39	If configure is called without --enable-tcg-interpreter, it will
	40	suggest using this option. Setting it automatically would need
	41	additional code in configure which must be fixed when new native TCG
	42	implementations are added.
	43
7316329a SW	44	For hosts with native TCG, the interpreter TCI can be enabled by
	45
	46	configure --enable-tcg-interpreter
	47
	48	The only difference from running QEMU with TCI to running without TCI
	49	should be speed. Especially during development of TCI, it was very
	50	useful to compare runs with and without TCI. Create /tmp/qemu.log by
	51
12fd0f41	52	qemu-system-i386 -d in_asm,op_opt,cpu -D /tmp/qemu.log -accel tcg,one-insn-per-tb=on
7316329a SW	53
	54	once with interpreter and once without interpreter and compare the resulting
	55	qemu.log files. This is also useful to see the effects of additional
	56	registers or additional opcodes (it is easy to modify the virtual machine).
	57	It can also be used to verify native TCGs.
	58
	59	Hosts with native TCG can also enable TCI by claiming to be unsupported:
	60
	61	configure --cpu=unknown --enable-tcg-interpreter
	62
	63	configure then no longer uses the native linker script (*.ld) for
	64	user mode emulation.
	65
	66
	67	4) Status
	68
	69	TCI needs special implementation for 32 and 64 bit host, 32 and 64 bit target,
	70	host and target with same or different endianness.
	71
	72	\| host (le) host (be)
	73	\| 32 64 32 64
	74	------------+------------------------------------------------------------
	75	target (le) \| s0, u0 s1, u1 s?, u? s?, u?
	76	32 bit \|
	77	\|
	78	target (le) \| sc, uc s1, u1 s?, u? s?, u?
	79	64 bit \|
	80	\|
	81	target (be) \| sc, u0 sc, uc s?, u? s?, u?
	82	32 bit \|
	83	\|
	84	target (be) \| sc, uc sc, uc s?, u? s?, u?
	85	64 bit \|
	86	\|
	87
	88	System emulation
	89	s? = untested
	90	sc = compiles
	91	s0 = bios works
	92	s1 = grub works
	93	s2 = Linux boots
	94
	95	Linux user mode emulation
	96	u? = untested
	97	uc = compiles
	98	u0 = static hello works
	99	u1 = linux-user-test works
	100
	101	5) Todo list
	102
	103	* TCI is not widely tested. It was written and tested on a x86_64 host
	104	running i386 and x86_64 system emulation and Linux user mode.
	105	A cross compiled QEMU for i386 host also works with the same basic tests.
	106	A cross compiled QEMU for mipsel host works, too. It is terribly slow
	107	because I run it in a mips malta emulation, so it is an interpreted
	108	emulation in an emulation.
	109	A cross compiled QEMU for arm host works (tested with pc bios).
	110	A cross compiled QEMU for ppc host works at least partially:
	111	i386-linux-user/qemu-i386 can run a simple hello-world program
	112	(tested in a ppc emulation).
	113
	114	* Some TCG opcodes are either missing in the code generator and/or
	115	in the interpreter. These opcodes raise a runtime exception, so it is
	116	possible to see where code must be added.
117
7316329a SW	118	* It might be useful to have a runtime option which selects the native TCG
	119	or TCI, so QEMU would have to include two TCGs. Today, selecting TCI
	120	is a configure option, so you need two compilations of QEMU.