[pcsx_rearmed.git] / deps / lightrec / README.md


# Lightrec

Lightrec is a MIPS-to-everything dynamic recompiler for
PlayStation emulators, using
[GNU Lightning](https://www.gnu.org/software/lightning/)
as the code emitter.

As such, in theory it should be able to run on every CPU that Lightning
can generate code for; including, but not limited to, __x86__, __x86_64__,
__ARM__, __Aarch64__, __MIPS__, __PowerPC__ and __Risc-V__.

## Features

* __High-level optimizations__.  The MIPS code is first pre-compiled into
a form of Intermediate Representation (IR).
Basically, just a single-linked list of structures representing the
instructions. On that list, several optimization steps are performed:
instructions are modified, reordered, tagged; new meta-instructions
can be added, for instance to tell the code generator that a certain
register won't be used anymore.

* __Lazy compilation__.
If Lightrec detects a block of code that would be very hard to
compile properly (e.g. a branch with a branch in its delay slot),
the block is marked as not compilable, and will always be emulated
with the built-in interpreter. This allows to keep the code emitter
simple and easy to understand.

* __Run-time profiling__.
The generated code will gather run-time information about the I/O access
(whether they hit RAM, or hardware registers).
The code generator will then use this information to generate direct
read/writes to the emulated memories, instead of jumping to C for
every call.

* __Threaded compilation__.
When entering a loading zone, where a lot of code has to be compiled,
we don't want the compilation process to slow down the pace of emulation.
To avoid that, the code compiler optionally runs on a thread, and the
main loop will emulate the blocks that have not been compiled yet with
the interpreter. This helps to drastically reduce the stutter that
typically happens when a lot of new code is run.

## Emulators

Lightrec has been ported to the following emulators:

* [__PCSX-ReArmed__ (my own fork)](https://github.com/pcercuei/pcsx_rearmed)

* [__pcsx4all__ (my own fork)](https://github.com/pcercuei/pcsx4all)

* [__Beetle__ (libretro)](https://github.com/libretro/beetle-psx-libretro/)
Commit	Line	Data
a59e5536	1
	2	# Lightrec
	3
	4	Lightrec is a MIPS-to-everything dynamic recompiler for
	5	PlayStation emulators, using
	6	[GNU Lightning](https://www.gnu.org/software/lightning/)
	7	as the code emitter.
	8
	9	As such, in theory it should be able to run on every CPU that Lightning
	10	can generate code for; including, but not limited to, __x86__, __x86_64__,
	11	__ARM__, __Aarch64__, __MIPS__, __PowerPC__ and __Risc-V__.
	12
	13	## Features
	14
	15	* __High-level optimizations__. The MIPS code is first pre-compiled into
	16	a form of Intermediate Representation (IR).
	17	Basically, just a single-linked list of structures representing the
	18	instructions. On that list, several optimization steps are performed:
	19	instructions are modified, reordered, tagged; new meta-instructions
	20	can be added, for instance to tell the code generator that a certain
	21	register won't be used anymore.
	22
	23	* __Lazy compilation__.
	24	If Lightrec detects a block of code that would be very hard to
	25	compile properly (e.g. a branch with a branch in its delay slot),
	26	the block is marked as not compilable, and will always be emulated
	27	with the built-in interpreter. This allows to keep the code emitter
	28	simple and easy to understand.
	29
	30	* __Run-time profiling__.
	31	The generated code will gather run-time information about the I/O access
	32	(whether they hit RAM, or hardware registers).
	33	The code generator will then use this information to generate direct
	34	read/writes to the emulated memories, instead of jumping to C for
	35	every call.
	36
	37	* __Threaded compilation__.
	38	When entering a loading zone, where a lot of code has to be compiled,
	39	we don't want the compilation process to slow down the pace of emulation.
	40	To avoid that, the code compiler optionally runs on a thread, and the
	41	main loop will emulate the blocks that have not been compiled yet with
	42	the interpreter. This helps to drastically reduce the stutter that
	43	typically happens when a lot of new code is run.
	44
	45	## Emulators
	46
	47	Lightrec has been ported to the following emulators:
	48
	49	* [__PCSX-ReArmed__ (my own fork)](https://github.com/pcercuei/pcsx_rearmed)
	50
	51	* [__pcsx4all__ (my own fork)](https://github.com/pcercuei/pcsx4all)
	52
	53	* [__Beetle__ (libretro)](https://github.com/libretro/beetle-psx-libretro/)