PPSSPP PSP Emulator Development Guide - git, tasks, portability

Building

Android

You can build for Android from Windows, MacOSX or Linux. NOTE: You will need a real Android device to test on, the SDK emulator is not good enough. Although BlueStacks seems to work on Windows.

To build for Android, make sure that you have installed the Android SDK and NDK correctly, and that the $NDK environment variable is set to the path of the NDK.

Go to ppsspp/android and run either ab.cmd or ab.sh, depending on your operating system.
Open the project in Eclipse (Impor it into your workspace, also import the "native" project and set up an Android library dependency from PPSSPP to native)
Build and run on your phone. If you rebuild the NDK part, you may have to add a space to PPSSPPActivity.java or refresh the project to force Eclipse to push out a new APK to your device.

It is also possible to build the Android version using Ant. If you know how to do that, well, it'll be easy for you anyway.

iOS

Build instructions coming soon.

Debugging and logging

You'll find yourself to be relying on the logs a LOT to figure out what's really going on. PPSSPP logs an equivalent of strace on Linux with the addition of some system libraries that on other systems would not be in the kernel, and this function call log is very useful to see what is going on.

There's a headless (no display/audio) build, which is very useful when running the pspautotests through test.py - highly recommended way to find issues.

PPSSPP is in the process of switching to Qt for many of the ports. The Android port will stay non-Qt for the time being but most of the others will migrate. Qt code is not allowed in Core, only in the UI layers.

The Windows port and the Qt build have interactive debuggers. Currently this is not available for mobile platforms and "SDL" builds.

Test Suite

Since this emulator needs to implement the whole PSP OS, testing it against the real thing is critical. Some other PSP emulator authors have collaborated around creating a test suite called pspautotest, and we have picked that up and turned it into a proper test suite. There are two scripts: test.py and gentest.py. gentest.py uses psplink to run a test program on your real PSP and captures the text output and saves it as [test].expected. Then you can run the same test in PPSSPP by using test.py, which will automatically compare the output to the expected output.

The structure of the source code

Simplicity

PPSSPP has a strong emphasis on keeping the code as simple as possible, but no simpler. That is, no excessive class hierarchies, not lots of whitespace fluff but reasonably tight and flexible (where appropriate only!).

Dependencies

PPSSPP has few dependencies: basically zlib and OpenGL, and soon FFMPEG. It uses the OpenGL ES 2.0 subset of OpenGL, so that the same graphics code can be shared between all platforms. It does also include a few minor libraries like CityHash and libzip directly in the distribution, for ease of building on Windows.

HLE

PPSSPP is a HLE ("high level emulation") emulator, it simulates the PSP OS as seen by the game rather than the full hardware. A program running on the PSP OS can send raw display lists to the graphics chips, but can't access the flash controller or the Media Engine directly, instead it has to go through libraries and the PSP OS kernel. We simply simulate these. This is a lot of work though, the PSP OS is large and has plenty of functionality so achieving 100% compatibility is difficult bordering on the impossible. We can get close though.

Folder Structure

The core goes in Core, graphics emulation goes in GPU, ports go in their own folders like "Android", "Windows", some common functionality is in Common, and that's pretty much it.

Contributing

Pick from the list of tasks below, go look at the open issues on GitHub, or just implement whatever missing feature you feel like. If you send a couple of good pull requests, you'll be added as a contributor and get your own commit access.

Submit pull requests by e-mailing them to the project mailing list or posting them in the development section of the forum.

Do not simply copy code from JPCSP or build frameworks to make that easy. Instead, write code for PPSSPP, in the PPSSPP style. Using JPCSP as documentation of the PSP hardware/OS is fine though.

The PPSSPP coding style is approximately the same as Dolphin's coding style.. The one exception is that private member variables are distinguished by a '_' suffix instead of a 'm_' prefix, also, we prefer opening braces on the same line as the statement. The style is not strictly enforced but you are encouraged to write code in the same style to make it easier for other contributors to read and edit your code.

Task lists - things that need doing

If you don't know where to start, pick a task below and have at it!

Beginner / Janitor tasks

In Core/HLE, use the Wrap* methods from FunctionWrappers.h to avoid manual PARAM(x) parameter parsing. You'll understand when you see it. For example, see sceGe.cpp. Don't make the functions static though as GCC doesn't like that. New HLE functions should always use the Wrap functions, and add new ones if the correct one isn’t there.

Intermediate complexity tasks

Run games, look at the logs to see what functions are missing or buggy, and implement them and see if the games go further.
Work through the automated test suite (see test.py), make sure that all of them work correctly.
Port PPSSPP to new platforms, see below.
Get the Qt UI running on Windows.

Advanced tasks

Bring in FFMPEG, hook up sceMpeg and ATRAC3 (and MP3). ATRAC3plus is still a problem as there's no open source decoder...
Write an OpenGL ES 3.0 backend (separate from the OpenGL ES 2.0 backend) making use of the new features, like uniform buffers and VAOs, for speed and compatibility.
Write a D3D9 backend for old slow XP PCs.
Write a D3D11 backend so that we can eventually make a Windows 8 Modern UI version (it will be slow due to lack of JIT though).
Write a software rasterizer backend, for accuracy and so that we can run on platforms without a programmable GPU.
Optimize things like texture decoding and swizzling for ARM NEON and SSE2. Note that on ARM you have to add checks - not all ARM devices support NEON (though nearly all new ones do).

Insane Tasks

Reverse engineer the ATRAC3plus audio codec and implement support for it.

Porting PPSSPP

You are encouraged to port PPSSPP to new platforms. Here's an incomplete list of platforms that PPSSPP could or could not plausibly be ported to:

Platform	Done	Comments
Windows	Done	JIT for x86 and x64
Android	Done	JIT for ARM
Ouya (Android)	Soon	Gamepad and JIT
Linux	Done	JIT for x86 and x64
MacOSX	Done	JIT for x86 and x64. Port still pretty bad.
Blackberry 10	Done	JIT for ARM
Symbian	Done	JIT for ARM
Pandora	Done (unofficial)
iOS	Nearly done (jailbreak required)	JIT WIP
Raspberry Pi	Done?
MeeGo	Soon?
Windows Phone 7.x	NOT POSSIBLE	No native code support
Windows Phone 8	POSSIBLE	JIT not allowed, will be slow
Windows RT	POSSIBLE	JIT not allowed, will be slow
Xbox 360	POSSIBLE	Hacked consoles only.
Playstation 3	POSSIBLE	Hacked consoles only.
Wii	POSSIBLE	Hacked consoles only.
Xbox Original	POSSIBLE	Hacked consoles only.
Playstation 2	NOT POSSIBLE	Lack of RAM, weak CPU.
Gamecube	NOT POSSIBLE	Lack of RAM
Dreamcast	NOT POSSIBLE	Lack of RAM, weak CPU.
P166MMX	NOT POSSIBLE	Weak CPU
Nintendo DS	Are you kidding?	Way below requirements
C64	Go away.	Yeah...

PPSSPP Development

Table of contents

Code and commit access

Convenient Links