HAN JIE

🚀 XenonRecomp Compiler Documentation

XenonRecomp is a tool designed to convert PowerPC (PPC) assembly code into C++, primarily used in the development of game simulators. This documentation provides detailed guidance on how to use and configure XenonRecomp, covering its features, input/output handling, configuration options, and testing methods.

🚀 Quick Start

Input and Output Formats

Input Format

XenonRecomp accepts the following inputs:

• PPC Assembly Code Files: Contain the PPC assembly instructions to be converted.
• Context Header Files: Define the registers and other context information used in the assembly code.

Output Format

The converted C++ files, which contain the results of converting the assembly instructions into C++ code. The location of the output files is specified by the user.

Configuration Options

XenonRecomp provides the following configuration options:

• Input Directory: Specifies the directory path containing the PPC assembly code and context header files.
• Output Directory: Specifies the target location for the generated converted C++ files.
• Debug Mode: Enables debug information for easier debugging and error handling.

Features

1. Interrupt Handling

In the config.toml configuration file, users can define code segments to be skipped:

# Disable the conversion of assembly code for interrupt handling to C++
skip_assembler = ["Altivec"]

2. Debug Hooks

Through the config.toml configuration file, users can insert custom debug hooks:

[[debug_hook]]
name = "Example Debug Hook"
address = 0x12345678
registers = ["r0", "r1"]

3. Custom Conversion Rules

In the rules.toml file, users can customize the conversion rules from assembly instructions to C++:

# Example: Convert the PPC instruction 'add' to the C++ expression 'r0 = r1 + r2'
[add]
cpp = "r0 = r1 + r2;"

Testing

XenonRecomp can handle the PPC tests of the Xenia project and generate the corresponding C++ files. Use the following command for conversion:

XenonRecomp [Path to Input Test Directory] [Path to Input PPC Context Header File] [Path to Output Directory]

The generated files can be found in the src/xenia/cpu/ppc/testing/bin directory.

Compilation

The project requires CMake 3.20 or higher and Clang 18 or higher. Since the repository contains sub - modules, ensure to use git clone --recursive for cloning.

It is only recommended to use the Clang compiler for development because the project relies on specific features of Clang. On Windows, you can use the clang - cl toolchain and develop through Visual Studio's CMake integration.

📄 License

This project could not have been realized without referring to the PPC code converter of the Xenia simulator. The project also uses patches from Xenia Canary to handle XEX binary files.