Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@kotcrab
kotcrab committed Oct 24, 2021
1 parent c44c027 commit ef5f395
Showing 1 changed file with 41 additions and 30 deletions.
71 changes: 41 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,80 +4,91 @@ ghidra-allegrex
Ghidra processor module adding support for the Allegrex CPU used in the PlayStation Portable.

Features:

- PSP calling convention
- Processor type auto-detection for ELF files
- Support for PSP specific ELF relocation sections (type A and B)
- Image rebase after loading is also supported
- Disassembly and decompilation of VFPU instructions (see limitations bellow)
- Scripts for importing and exporting PPSSPP `.sym` files (function labels)

In progress:
- Integration with PPSSPP debugger
- Ghidra Debugger can be used to debug games running in PPSSPP (beta, available in pre-release)

### Installation

Download prebuilt package from the [Releases](https://github.com/kotcrab/ghidra-allegrex/releases) section.
After extracting copy the `Allegrex` directory into `GHIDRA_INSTALL_DIR/Ghidra/Processors`
Download prebuilt package from the [Releases](https://github.com/kotcrab/ghidra-allegrex/releases) section. After extracting
copy the `Allegrex` directory into `GHIDRA_INSTALL_DIR/Ghidra/Processors`

### Usage

#### Games

Drag decrypted EBOOT in ELF/PRX format into Ghidra. It should get automatically detected
as `PSP Executable (ELF)` / `Allegrex`. Now is your chance to set initial base address by
clicking `Options...` and changing `Image Base`. I highly recommend you set it to `08804000`.
If you leave it at `0` Ghidra may create many useless labels and references it confuses
Drag decrypted EBOOT in ELF/PRX format into Ghidra. It should get automatically detected as `PSP Executable (ELF)`
/ `Allegrex`. Now is your chance to set initial base address by clicking `Options...` and changing `Image Base`. I highly
recommend you set it to `08804000`. If you leave it at `0` Ghidra may create many useless labels and references it confuses
as memory access. Rebasing the image later is possible but will not remove those labels.

After importing and opening the file you should do the auto analysis. Default options are fine.

#### Using PPSSPP .sym scripts

PPSSPP identifies many functions automatically, it's useful to get those into Ghidra
after doing the initial analysis. Export the `.sym` file from PPSSPP and in Ghidra run script
`PpssppImportSymFile`. Select the `.sym` file. Enter `0` when asked for offset if your image base is already
at `08804000`.
It's usually fine to run this script after you've started renaming functions in the binary. The script by
default skips unknown names from PPSSPP so your work can only get overwritten if you've renamed
one of the autodetected function.
PPSSPP identifies many functions automatically, it's useful to get those into Ghidra after doing the initial analysis. Export
the `.sym` file from PPSSPP and in Ghidra run script
`PpssppImportSymFile`. Select the `.sym` file. Enter `0` when asked for offset if your image base is already at `08804000`.
It's usually fine to run this script after you've started renaming functions in the binary. The script by default skips
unknown names from PPSSPP so your work can only get overwritten if you've renamed one of the autodetected function.

Likewise, you can use `PpssppExportSymFile` to export your work as a `.sym` file which can be imported
into PPSSPP. Enter `0` when asked for offset if your image base is already at `08804000`.
You need to do `Reset symbol table` before importing the file in PPSSPP.
Likewise, you can use `PpssppExportSymFile` to export your work as a `.sym` file which can be imported into PPSSPP. Enter `0`
when asked for offset if your image base is already at `08804000`. You need to do `Reset symbol table` before importing the
file in PPSSPP.

#### Kernel modules

Since version 1.7 relocations found in kernel modules are supported. Usage is very similar as when
importing games though kernel modules are usually loaded starting from address `88000000`. Note that
for some files (e.g. `sysmem`, `loadcore`) you will need to click `Options...` during import and
select option to use `reboot.bin` type B relocation mapping.
Since version 1.7 relocations found in kernel modules are supported. Usage is very similar as when importing games though
kernel modules are usually loaded starting from address `88000000`. Note that for some files (e.g. `sysmem`, `loadcore`) you
will need to click `Options...` during import and select option to use `reboot.bin` type B relocation mapping.

#### Raw binaries

Raw binaries are also supported. In that case you will need to manually select Allegrex as the processor
and set image base.
Raw binaries are also supported. In that case you will need to manually select Allegrex as the processor and set image base.

#### PPSSPP debugger integration

Since version 1.9 Ghidra Debugger can be used to debug games running in PPSSPP over the WebSocket API. To get started open
PPSSPP and make sure "Allow remote debugger" is enabled in PPSSPP settings. Then open your binary using the Debugger tool and
in the `Debugger Targets` panel press the `Connect` button. Select `PPSSPP WebSocket debugger (beta)` and press `Connect`.
See Ghidra's built-in help to learn more about the debugger features.

Tips:

- To enable automatic mapping between static and dynamic listing you must make sure the binary file name in Ghidra contains
the module name from PPSSPP. Module name is visible in the `Modules` panel and the binary can be renamed in the Ghidra
project window.

### VFPU Limitations

- Decompilation support is rather basic, almost every operation is converted to a function call such as `vadd_q(...)`
- Decompilation support is rather basic, almost every operation is converted to a function call such as `vadd_q(...)`
- Semantics of `vpfxs`, `vpfxt` and `vpfxd` are not currently modeled
- Second operand of `vfim.s` will be shown as an integer, should be shown as a half float. Sleigh does not support float tokens.
- Second operand of `vfim.s` will be shown as an integer, should be shown as a half float. Sleigh does not support float
tokens.

### Building

`GHIDRA_INSTALL_DIR` environment variable must be set to Ghidra root installation directory.

- `./gradlew ghidraInstall` - build and install into Ghidra (warning: contents of `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex` will be deleted before installing)
- `./gradlew ghidraInstall` - build and install into Ghidra (warning: contents
of `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex` will be deleted before installing)
- `./gradlew ghidraInstallThenRun` - run `ghidraInstall` task then start Ghidra, useful for development
- `./gradlew ghidraInstallThenDebug` - run `ghidraInstall` task then start Ghidra in debug mode, useful for development
- `./gradlew ghidraInstallThenPackage` - run `ghidraInstall` task then create release zip
- `./gradlew shadowJar` - create single library jar file with all external dependencies included

After running `./gradlew shadowJar` you can manually install extension by copying:
- `build/libs/ghidra-allegrex-all.jar` file to `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex/lib/Allegrex.jar`
- `data` and `ghidra_scripts` directories to `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex/`

- `build/libs/ghidra-allegrex-all.jar` file to `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex/lib/Allegrex.jar`
- `data` and `ghidra_scripts` directories to `GHIDRA_INSTALL_DIR/Ghidra/Processors/Allegrex/`

Ghidra should automatically recompile Sleigh files when importing an executable, if not run:

```bash
/ghidra_10.x.x/support$ ./sleigh -a ../Ghidra/Processors/Allegrex/data/languages/
```
Expand Down

0 comments on commit ef5f395

Please sign in to comment.