Building a Vagrant Box for PS2 Development

One of my new colleagues recently told me that he knew about PS2rd and that he had used it in the past to do some reverse engineering. In case you haven’t heard of it (really?), PS2rd stands for Playstation 2 remote debugger and used to be my pet project back when I was into homebrew and game hacking. Its killer feature is the ability to dump the PS2’s RAM to PC while playing a game. Best thing: it’s all open source and completely legal.

Without a doubt, it’s always motivating to see people actually using your software. And even though active development of PS2rd has been on hold for over 1.5 years, the mere fact that my colleague mentioned the project spurred my interest in it again. Incidentally, I’ve been a happy Mac user since last Christmas and trying to get my Linux stuff running on OS X anyway. So I set out to find a way to compile and use PS2rd under Mac OS X as well.

For a DevOps guy like me, the most appealing solution to that problem is Vagrant. FYI, Vagrant is awesome – it allows you to easily set up lightweight development environments based on virtual machines (or boxes in Vagrant speak). The cool thing about those boxes is that they can be used by others on any platform that Vagrant runs, including Windows, Linux, and Mac OS X. What follows is a step-by-step guide on how to create such a box for your everyday PS2 development.

The Vagrant Box

First of all, install the Vagrant base image for Ubuntu 10.04 (Lucid Lynx). In the past I’ve used Ubuntu exclusively for PS2 homebrew, so that’s where we’re starting from:

$ vagrant box add lucid64 http://files.vagrantup.com/lucid64.box

Then create a VM based on the Ubuntu box and boot it up:

$ mkdir ps2dev
$ cd ps2dev/
$ vagrant init lucid64
$ vagrant up

Next, SSH into the VM and install Git before cloning the PS2 toolchain scripts from GitHub:

$ vagrant ssh
vm$ sudo apt-get install -y git-core
vm$ git clone git://github.com/ps2dev/ps2toolchain.git

The toolchain scripts will automatically download, compile, and install everything we need for PS2 development, including cross compilers for PS2’s EE and IOP processors and a homebrew PS2 SDK. Start the setup, which will take several minutes to finish, this way:

vm$ cd ps2toolchain/
vm$ sudo ./toolchain-sudo.sh

When done, new compilers etc. can be found under /usr/local/ps2dev. We need to modify the $PATH variable in order to run them from the command line. Edit the login script ~/.profile to add the following:

vm$ cat >> ~/.profile <<'EOF'
export PS2DEV=/usr/local/ps2dev
export PS2SDK=$PS2DEV/ps2sdk
export PATH=$PATH:$PS2DEV/bin:$PS2DEV/ee/bin:$PS2DEV/iop/bin:$PS2DEV/dvp/bin:$PS2SDK/bin
EOF

After manually sourcing the login script again (done automatically next time you log in), we can run the EE cross compiler, for instance:

vm$ source ~/.profile
vm$ ee-gcc --version
ee-gcc (GCC) 3.2.2
...

At that point, we’re basically done with the PS2 build environment. We could package up the VM in the form of a Vagrant box file and distribute it. However, there’re a few useful tricks that will drastically reduce the size of the final box:

vm$ sudo rm -rf ~/ps2toolchain/build/
vm$ sudo apt-get clean
vm$ sudo dd if=/dev/zero of=/EMPTY bs=1M
vm$ sudo rm -f /EMPTY

Finally, exit the VM and package it up into a box file called ps2dev.box. After the packaging is complete, install the box locally for later use:

vm$ exit
$ vagrant package --output ps2dev.box
$ vagrant box add ps2dev ps2dev.box

If you don’t want to do all those steps yourself, you can also install the ready-to-use box I’ve uploaded to GitHub:

$ vagrant box add ps2dev https://github.com/downloads/mlafeldt/ps2toolchain/ps2dev.box

Compiling PS2rd

With our brand-new Vagrant box, compiling PS2rd under OS X is a piece of cake. Simply clone the code repository of PS2rd and set up a VM in the project folder:

$ git clone git://github.com/mlafeldt/ps2rd.git
$ cd ps2rd/
$ vagrant init ps2dev
$ vagrant up

Inside the VM, the contents of the project folder is shared at /vagrant. Go to that folder and invoke make to build PS2rd:

$ vagrant ssh
vm$ cd /vagrant/
vm$ make
PS2RD_VERSION = 0.5.3.60.gaea6.dirty
* [IOP] Building debugger ...
* [IOP] Building dev9 ...
* [IOP] Building eesync ...
...
* [EE] Building loader ...
vm$ file ee/loader/ps2rd.elf
ee/loader/ps2rd.elf: ELF 32-bit LSB executable, MIPS, MIPS-III version 1 (SYSV), statically linked, stripped

In order to run cross-compiled binaries like ee/loader/ps2rd.elf on your PS2, I recommend installing ps2client directly on OS X, so you can use it outside of the VM too:

$ git clone git://github.com/ps2dev/ps2client.git
$ cd ps2client/
$ make
$ make install PREFIX=$HOME
$ which ps2client
/Users/mlafeldt/bin/ps2client
$ ps2client execee host:path/to/your.elf

That’s it. Happy hacking.

tl;dr

Vagrant is awesome. Here’s a Vagrant box to cross-compile Playstation 2 homebrew like PS2rd under Windows, Linux, and Mac OS X.

---

Update (2012-07-04)

Just a small update to add two tidbits that didn’t make it in the original post.

First, here’s a Vagrantfile that, once added to your PS2 project, will make the Vagrant setup even simpler. That file basically tells vagrant up to use the ps2dev box we built before. If that box isn’t already available on your system, Vagrant will automatically download and install it for you.

# Vagrantfile
Vagrant::Config.run do |config|
  config.vm.box = "ps2dev"
  config.vm.box_url = "https://github.com/downloads/mlafeldt/ps2toolchain/ps2dev.box"
end

With the Vagrantfile and an SSH shortcut, it only takes four commands to clone and compile PS2rd:

$ git clone git://github.com/mlafeldt/ps2rd.git
$ cd ps2rd/
$ vagrant up
$ vagrant ssh -c "make -C /vagrant"

Second, I built another Vagrant box, this time based on the brand-new Ubuntu 12.04 release (Precise Pangolin). The only difference I noticed while creating the box was that I had to install make in addition to git-core. Get the new box from GitHub:

$ vagrant box add ps2dev-precise64 https://github.com/downloads/mlafeldt/ps2toolchain/ps2dev-precise64.box