PSP Development with Eclipse

Paulo Lopes
[email protected]

XXX XX, 2010

 Contents

Contents i

1 Getting Started 1
1.1 Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Install & Setup the Environment 3

2.1 MinPSPW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Blender3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Setup the Environment . . . . . . . . . . . . . . . . . . . . . . . . 6

3 C programming 13
3.1 Not an Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2 Debug your Game . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

i
 1
Getting Started

During this small book you will learn to setup the development environment
for your PlayStation Portable using Microsoft Windows as your host operat-
ing System. Although the book will only focus on Microsoft Windows you
can easily re use the same knowledge to your favorite operating system as
long as you manage to cross compile the PSPSDK. At the moment of writing
of this book the SDK can be cross compiled to Microsoft Windows (native and
emulated Cygwin), Linux, BSD and MacOS.
You will learn how to setup a working IDE with full debugging support
and then create a minimalist game engine with a blender exporter for your 3D
assets. This book will not teach the reader to program and assumes that the
reader is already familiar with the C programming language. This does not
mean that C is the only supported language in the SDK, you can use C, C++,
Objective-C or Objective-C++ for your native development or even Lua as a
scripting language (again not covered in this book).
Are you ready? Let’s get started!

1.1 Required Software

Getting started is easy and only requires one package, however this book
will help you to be productive, therefore besides MinPSPW (the minimal re-
quired software to compile your game to the PSP) You will install a C/C++
IDE (Eclipse) and a open source 3D modeling tool (Blender3D) to create a full
pipeline of game development.
You will get more information on what are these components and are free
to replace them with others you like more after you understand their role in
the full pipeline.

MinPSPW
Before starting developing for your PSP you need machine code tools. The
minimal toolset you will need is a compiler and linker for the PSP CPU. The
PSP CPU is known as the MIPS Allegrex. Basically is a modified MIPS 3000 +
FPU (Floating Point Unit) + VFPU (Vector FPU) all in one. Although originally
prepared to run at reduced CPU clock speed (200MHz) the usage of all these
CPUs make the PSP a powerful machine and still up to date (4 years after it’s
initial release).
The compiler and linker for this CPU is not publically available, actu-
ally Sony has never released it, however a huge base of fans understood the

1
2 CHAPTER 1. GETTING STARTED

full power of the machine and started to dig into the hardware and binaries
that you can run on the device. The findings allowed us to create a simple
toolchain based on the popular GNU GCC compiler.
This modified compiler is available to all under a GPL/BSD license mak-
ing it free for everyone. Under Microsoft Windows there were two options,
either use a posix emulator (Cygwin) or a native build (devKitPro) which is
not updated very often.
In the beginning of 2008 a new project started to port the SDK and keep
it up to date without any kind of emulation for windows (MinPSPW). Users
could just download a simple installer and once the installation was finished,
games could be compiled from the standard dos console window, the same
way the linux/bsd variant can compile from the shell.

Eclipse
PSP development forums are full of posts regarding people trying to get an
unified development environment. There are reports about using Visual Stu-
dio, CodeBlocks, Vi, Eclipse, etc... but it was always tricky to get it work-
ing.Eclipse is a Java-based, extensible open source development platform. By
itself, it is simply a framework and a set of services for building applications
from plug-in components. Fortunately, Eclipse comes with a standard set of
plug-ins, including the well-known Java Development Tools (JDT).
Eclipse is an open source community whose projects are focused on build-
ing an open development platform comprised of extensible frameworks, tools,
and runtimes for building, deploying, and managing software across the life
cycle. The Eclipse Foundation is a not for-profit member-supported corpora-
tion that hosts the Eclipse projects and helps cultivate an open source commu-
nity and an ecosystem of complementary products and services.

Blender3D
Blender was first conceived in December 1993 and born as a usable product in
August 1994 as an integrated application that enables the creation of a broad
range of 2D and 3D content. Blender provides a broad spectrum of model-
ing, texturing, lighting, animation and video post-processing functionality in
one package. Through it’s open architecture, Blender provides cross-platform
interoperability, extensibility, an incredibly small footprint, and a tightly inte-
grated workflow. Blender is one of the most popular Open Source 3D graphics
application in the world.
Aimed world-wide at media professionals and artists, Blender can be used
to create 3D visualizations, stills as well as broadcast and cinema quality videos,
while the incorporation of a real-time 3D engine allows for the creation of 3D
interactive content for stand-alone playback.
 2
Install & Setup the Environment

During this step You will learn how to install your environment and set it up
in order to be productive. This step involves download of open source soft-
ware from the internet (during all this book, only open source software will be
used, regardless of the license as long as it is OSI approved). Again the only
required component is the MinPSPW, however for the course of this book, you
will need some extra components: Java Runtime, Eclipse IDE, Python 2.5 and
Blender3D.

2.1 MinPSPW
The MinPSPW toolchain is available at: http://minpspw.sf.net. At the
moment of the writing of this book the current version is 0.8.10. Once you
download it to your PC, start the installation and follow the wizard:

Figure 2.1: MinPSPW Installer

The installer will ask you to agree with the license, which basically is a
collection of open source licenses for all the components inside the SDK. BSD
license for the SDK itself, GPL for the MinPSPW and some of the included libs
and LGPL for some of the included libs. There are no closed source compo-
nents included.
Once you are done with the license you can choose which components to
install, If you are not sure, just select everything unless you don’t have around
150Mb of disk space.

3
4 CHAPTER 2. INSTALL & SETUP THE ENVIRONMENT

Figure 2.2: MinPSPW Installer Options

At this moment you have a working compiler that allows you to unleash
the power of your PSP. To make sure that everything works lets make a simple
test. Let’s check the version of a couple of components that were just installed.
Open a DOS console prompt and type:

Figure 2.3: Command Line check

If you don’t know what those commands are, I’ll explain: The first one is
the build tool, that will automate your build process of compiling and package
your code into a PBP file that can run on your PSP. The second is the PSP
compiler and linker.

2.2 Eclipse IDE

Eclipse IDE can be downloaded from the project web site at: http://www.
eclipse.org. This book covers Eclipse 3.4.1 (Ganymede). In order to get
eclipse running you need to have an updated Java Runtime. So before starting
looking for the right Eclipse for you download the Java Runtime from http:
//www.java.com/getjava. The Java page is quite good explaining on how
to download and install the runtime. At this moment you might be asking the
2.3. BLENDER3D 5

question: “can I code in java for the PSP?” Well the answer is yes and no; yes you
can if you use something like pspkvm; and no because the native compilers
do not support gcj (yet).
I assume that you already have the java runtime installed, so the next step
is to install Eclipse. As said before get it from http://www.eclipse.org
and select the “Eclipse for C/C++ Developers”. You can choose any of the
other options as you make sure that later you install the CDT (C Development
Tools) plug-in. For now just download the Eclipse for C/C++ Developers.
Once you download the zip file, unzip it to a simple directory in your PC.
I assume you unzip to C:\. In order to make it easier make a shortcut to your
desktop to the executable file on C:\eclipse\.exe.

Starting Eclipse for the first time

Use the link you just created to start Eclipse. The first time you open it, you
see the workspace location page, which informs the IDE where all your work
is located in your computer (see 2.4).

Figure 2.4: Eclipse workspace launcher

Once you have decided where to store your work you are shown the wel-
come page. This page exists inside the workbench (see 2.5). As an Eclipse user,
you’ll be given a few options of going to an overview page, which I recom-
mend. See what’s new, explore some samples, or go through some tutorials.
The Eclipse workbench consists of several panels known as views, such
as the navigator or outline views. A collection of these views is called a per-
spective. One of the most common perspectives is the Resource perspective,
which is a basic set of views for managing projects and viewing and editing
files in a project.
I recommend most novice users start with the Overview page featured in
Figure 2.5 and learn about Eclipse. The workbench basics section contains a
lot of good starter information about the various pieces of Eclipse and how
they interact.

2.3 Blender3D
Blender3D relies heavily on Python scripting language. In order to get the full
potential from this package you should install Python (version 2.5 for binary
compatibility) into your PC. Install Python is easy as it was to install the Java
Runtime. Python can be downloaded from the project website http://www.
6 CHAPTER 2. INSTALL & SETUP THE ENVIRONMENT

Figure 2.5: Eclipse welcome screen

python.org, go to the download page and download the latest 2.5.x installer.
Do not install the latest version since Blender3D might have some trouble
using it. Get the release MSI and install it. Follow the wizard and again try to
use the default installation path C:\Python25.
Once you PC has Python installed download and install Blender3D. By
the time of writing this book, Blender 2.48a is the current release, download
it from: http://www.blender.org and install it. Again I advice you to
install to the default path.

Starting Blender3D
Blender3D user interface is not easy for the beginner 2.6. Just explore the
menus and if you really interested there are some nice tutorials and books
that can help you getting into shape with Blender.

2.4 Setup the Environment

Although you have installed all the required tools there are some extra con-
figurations you need to do to your Eclipse in order to have it fully inter-
operational with the PSP SDK tools. There are 3 things you need to config-
ure, the first is the C compiler discovery features, the second some external
tools that will help you with debugging and the third is a USB driver to allow
remote debugging from your PSP within your Eclipse IDE.
2.4. SETUP THE ENVIRONMENT 7

Figure 2.6: Blender3D main window

Makefile Discovery Options

Open your Eclipse and go to the “Window > Preferences” menu. Once you are
there navigate to the “C/C++ > New CDT Project Wizard > Makefile Project” on
the navigation tree. This panel will allow you to configure a compiler which
is not the host system GCC. Since we are using a cross compiler (not a native
compiler) we need to change some parameters to get the full power of Eclipse.
On the first tab, “Binary Parsers” 2.7, enable the “ELF” parser. PSP runs
binary files in ELF format. Allowing this configuration to parse them will
show you once you compile which functions are available in your object files.
This might seem not important but can help to identify bugs later on. As a
rule of thumb enable it even if you don’t really think you need it since there
are no side effects either in code size or performance of your system.
The second item to configure on this panel is the “Discovery Options” 2.8.
This is a very important configuration because not doing it, although your
system would still work, all the productivity features such as code complete
and API navigation will not be available. Go to the third tab Discovery Op-
tions, and change the “Compiler Invocation Command” to “psp-gcc”. Once you
do this Eclipse will pick the correct compiler from your system and enable
code complete and code navigation features, assisting you to produce faster
code.

External Tools
The MinPSPW SDK is an open source SDK for the PlaySation Portable, it does
not contain hardware debugging facilities as the official Sony SDK. To debug
a Homebrew application you would usually code your game, compile, link,
plug the PSP usb cable, transfer the PBP file to the memory stick, unplug the
cable, start the game and on error you would either be lost or you would have
some text file in your memory stick with your printf debug statements.
This approach can become impractical for real projects, that is when PSPLink
8 CHAPTER 2. INSTALL & SETUP THE ENVIRONMENT

Figure 2.7: Eclipse Binary Parser Configuration

comes into place. We will cover PSPLink later during the debug chapter, for
now just be aware that the PSPLink is composed of 4 parts:

• USBHostFS_PC - USB communication between the PSP and your PC

• pspsh - A simple shell that controls the USBHostFS

• PSPLink PBP - A PSP application that will be the bridge between your
application and all the debugging facilities.

• USB Driver - A special USB block device driver that does the low level
communication between the PSP and your PC.

The first 2 features that need to be configured into Eclipse. In the main
Eclipse window, locate the “External Tools button” This is a simple green run
button with a red toolbox under. Note that there is a drop-down option in the
button, activate it and select “External Tools Configurations...”.
Create a new tool under “Program” called “usbhostfs 2.9. On the location
find the folder where you installed the PSPSDK and under the bin folder you
will find an executable named: “usbhostfs_pc.exe”. Apply your changes. On
the working directory use the variable “project_loc”. Apply your changes and
close.
Still in the same configuration window, create a new tool under “Pro-
gram” called “pspsh 2.10. On the location find the folder where you installed
2.4. SETUP THE ENVIRONMENT 9

Figure 2.8: Eclipse Discovery Options Configuration

Figure 2.9: Eclipse External Tools (USBHostFS_PC) Configuration

10 CHAPTER 2. INSTALL & SETUP THE ENVIRONMENT

the PSPSDK and under the bin folder you will find an executable named:
“pspsh.exe”.

Figure 2.10: Eclipse External Tools (PSPsh) Configuration

Drivers & PSPLink

Your environment is almost ready, locate the MinPSPW installation folder and
inside you will find another folder named: “psplink”. Inside the “psp” sub
folder you see a couple of sub folders. Pick the right folder name according
to your firmware version, for most people the right one is the oe. Copy the
folder to your GAME folder in the PSP memory stick. Optionally rename
it into something more readable since your might forget what it is in your
memory stick later on.
PSPLink communicates through a special USB driver. This allows you to
remotely debug your application. It needs Administration rights in your ma-
chine since it is a Windows OS driver. To install follow the next steps:

1. Connect your PSP to the USB cable and make sure that the USB link is
disabled, in other words you should not be able to see the memory stick
contents from your PC.

2. Start the PSPLink application on the PSP

3. A New Hardware Wizard will popup asking for the correct driver. The
driver is in the MinPSPW “bin” folder. Locate it and point to the “driver”
folder.
2.4. SETUP THE ENVIRONMENT 11

4. If you have a 64 bit OS use the “driver_x64 folder.

At this moment your USB driver should be installed and ready for use. To
try out and see if everything when right, go back to your eclipse and start the
USBHostFS external application, once you have done it, the console window
in the bottom should show something like this 2.11.

Figure 2.11: Eclipse connected to PSPLink

 3
C programming

In this chapter you will learn how to code your first game. You will learn how
to setup your project under eclipse and use the features that it gives to you
such as code complete. You will also learn some of the internal differences of
coding for the PSP and coding for a normal PC.

3.1 Not an Hello World

For your first example you will not use the Hello World example. You will
be more advanced and create a spinning cube. I will not cover the details of
programming the code is self explanatory and there are lots of good tutorials
and books on C development available.
For this first application you will not even need to code, we will use one of
the samples that ship with the MinPSPW SDK.

Create a Project
Open Eclipse and create a new C project. Select File > New > Project and fi-
nally select C project. From the project type tree pick Makefile Project > Empty
Project. This will be your standard project type for most of the PSP develop-
ment with Eclipse. Selected this project for –Other Toolchain– and then enter
“Spinning Cube” in the project name and point the location to “C:\pspsdk \psp
\sdk \samples \gu \cube” after checking out the default location checkbox. Fi-
nally click Finish 3.1.
Next, we’ll take a look at the C/C++ perspective (if you aren’t already
there). Depending on how you like to manage your screen, you can change
the perspective in the current window by selecting Window > Open Perspective
> C/C++ or you can open a new window by selecting Window > New Window
and selecting the new perspective.
The C/C++ perspective, as you might expect, has a set of views that are
better suited for C/C++ development. One of these includes, as the top-left
view, a hierarchy containing various C/C++ namespaces, classes, includes,
libs and miscellaneous files. This view is the called the Package Explorer.
Also notice that the main menu has expanded to include two new menu items:
Source and Refactor.
If you have not noticed yet, you just compiled your first PSP application.
This is because Eclipse build your project automatically. Now that you are fa-
miliar with the workbench you can see in the project explorer that a file named
EBOOT.PBP is present. Before running and putting this file in your PSP lets

13
14 CHAPTER 3. C PROGRAMMING

Figure 3.1: New Eclipse C Makefile project

look a bit closer to the workbench. Double click on the cube.c file. Eclipse will
highlight the C language keywords and even bold out your function names
3.2.
Eclipse will allow you to navigate through the code by “Ctrl + Click” a
function name or include file. This will open the definition of the method or
open the file. While typing “Ctrl + Space” will start the code complete feature
like visual studio’s Intellisense. Hovering over a function will trigger Eclipse
to parse any documentation in the source code written in a Doxygen/Javadoc
compatible way. These are just some of the features you can have with Eclipse,
feel free to explore the menus and the internet for more productive tips.

3.2 Debug your Game

Now that you are already know how to code for the PSP in a productive way,
let’s cover the debugging of your game. Sooner or later you will need to de-
bug, that is a fact. Eclipse makes it easy just by using the visual IDE. Starting
from the previous example, open the cube.c file 3.2.
This is the main source code for your game, lets say the spinning is to
slow and you want it to be doubled. Assuming you did not know anything
about the code one possible solution would be to add a breakpoint on the last
instruction of the main loop. Locate the line containing val++ and with the
mouse double click on the gutter bar to add a breakpoint.
However this looks like enough it will not work. The default Makefiles
from the MinPSPW are not compiling your sources with debug information
and the current PSPLink for OE firmware only allows the debugging of PRX
modules. To get it working (and I assume you also know a bit from Makefiles)
you should open the Makefile by double click it on the project resources and
3.2. DEBUG YOUR GAME 15

Figure 3.2: Eclipse C perspective

add “-g” to the CFLAGS variable. Also to build a PRX you should just the
BUILD_PRX = 1 line to the Makefile. Now clean your project using the Project
> Clean menu and you have a debuggable game.
The debugging process is a bit tricky and can be described as the following
steps:

• Plug the PSP to the PC using the USB cable

• Start PSPLink on the PSP

• Start the USBHostFS application by selecting the project and using the
external tools button

• Start the PSPSh external tool by selecting the project and using the ex-
ternal tools button

• On the PSPSh type: debug cube.prx where cube.prx is your project PRX
file

• Start the Eclipse debugger (the little bug button).

If you are debugging for the first time you need to configure the debugger
for the project. This is a project specific configuration that is the reason it was
not included in the previous chapter. Select the drop down from the debug
button and pick “Debug Configurations...” A new window pops up and you
should select C/C++ Local Application. The project should be filled in be default
16 CHAPTER 3. C PROGRAMMING

Figure 3.3: Eclipse C Debug Config 1

Figure 3.4: Eclipse C Debug Config 2

3.2. DEBUG YOUR GAME 17

with your working project and in the C/C++ Application your application ELF
should be entered, for out example it should be cube.elf 3.3.
This is the first step, the second step is to inform Eclipse that we are run-
ning a remote debugger, so switch to the debugger tab and the GDB debugger
should be replaced from gdb to psp-gdb 3.4, once this is done on the connection
sub tab, the type should be TCP and the port 10001 3.5.

Figure 3.5: Eclipse C Debug Config 3

Your debugger is now ready and should allow you to debug your code.
Once the debugger starts you are asked to switch to the debug perspective,
do it and inspect your code 3.6.
18 CHAPTER 3. C PROGRAMMING

Figure 3.6: Eclipse Debug Perspective