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