Getting started

felix86 is an emulator, and emulators have endless amounts of work to be done.

If you’ve never used felix86 before, I recommend starting by testing it out. Use the installation script or check out the building instructions and try to run a simple program such as glxgears.

There’s multiple ways to contribute.

Communication

Join our discord server to ask development questions.

Good first issues

There’s a good-first-issues label on our issue tracker which contains easy bugs or feature requests for first time contributors.

Instruction optimizations

We use an IR-less JIT and we go through a lot of work to try to minimize the amount of RISC-V instructions needed to emulate an x86 instruction.

A good starting point is building with REPL support (set BUILD_REPL=1 during CMake configuration) and testing what the emitted code for each instruction is.

The REPL environment accepts x86 instructions and prints the generated RISC-V assembly. It can accept multiple instructions separated by semicolons.

Example:

felix86 --repl
> mov rdi, rsi
MV a0, a1

Try to find a non-optimal instruction sequence and optimize it!

Debugging tips

There’s some tips to make your life easier.

Some guest-side debuggers like winedbg can be useful.

Many times the host strace is useful when chasing bugs in the emulator itself, or want a more complete trace. Make sure to filter out some syscalls that are frequently use and spammy, such as riscv_flush_icache and rt_sigprocmask. Make sure to capture all processes, using the -f argument in strace.

Profiling games

You can make felix86 emit metadata for perf using FELIX86_PERF_BLOCKS=1.