Coding for the PlayStation® 2

Linux for PlayStation 2 allows you to try your hand at PlayStation 2 specific programming, using the hardware in the same way as professional game developers do.

We recognise that it's not immediately obvious how to get into programming the PlayStation 2 using your Linux kit. This guide aims to give you some starting points for getting set up, lay out the development options you've got, and head you off in the right direction towards PlayStation 2 developer guru status.

1. Getting started
• If you haven't done anything with your Linux kit
• What do I have to work with?
• Other useful stuff
2. First reading material
3. Development options
• Coding for the PlayStation 2
• Using the SPS2 module
• Using the libps2dev library
• VU Coding
• Higher level APIs
• PS2GL
4. Useful resources
5. Tips
• Other tools worth knowing about
6. Further reading

Getting started

If you haven't done anything with your Linux kit

Start off by doing a full install^[1] on your Linux kit (select 'custom', then 'everything'). It only takes up 1 GB out of 40GB on the HDD, so there is plenty of room to do this, and really no reason not to. During this process mentally prepare yourself for what is to come, and read ahead in this document.

Don't worry if you don't have a Sync On Green compatible monitor. If you have a PC you can network with the kit, you don't need a SOG monitor - just connect the PlayStation 2 to your TV and boot in NTSC or PAL. You can either edit your files on your PC and copy them over the network, or connect to the PlayStation 2 from your PC using ssh or telnet, and edit the files using a console text editor such as emacs or vi(m).

You will almost certainly want to start the ssh or telnet server, and ftp server on your Linux kit. Ssh/telnet servers let you connect into your PlayStation 2 from your PC using a ssh/telnet client such as Putty (recommended). FTP is an easy way of transferring files between machines; once you're running an FTP server on your Linux kit you can use one of many FTP clients to connect to it on your PC^[2] and transfer files between the machines.

To start these useful services, log in as root:

cd /etc
emacs inetd.conf

and within the file (use the arrow keys to navigate):

1. Delete the '#' at the start of the line with 'ftp'
2. Then on the line underneath, do exactly the same thing and delete the '#' in front of 'telnet'.
3. Press control-x and then control-s (to save the changes to the file)
4. Press control-x and then control-c (to quit the emacs text editor)

/etc/rc.d/init.d/inetd restart
chkconfig --level 3 sshd on

The ftp and telnet services are controlled by inetd, which is why we had to edit inetd.conf and restart the inetd service. sshd is independent; we used 'chkconfig' to set sshd to start by default when we're in runlevel 3 (this is the normal runlevel that you kit boots into when you start it up).

Then next time you boot, sshd will load automatically. To start it immediately you can do service sshd start.

Where to get started depends on where you're coming from. Real PlayStation 2 development is done using C or C++, and assembly.

If you have some experience coding in C, and you are familiar with basic hardware elements such as registers, you're in a good position to start reading the hardware manuals and trying some low level PlayStation 2 development.

If you're not as experienced with C, but you have done some programming, don't worry. You might want to try working through some game programming or C tutorials out there on the web^[3]...but feel free to have a go at some of the suggestions below and then see how you feel.

What do I have to work with?
Here's your development environment:

• Your favourite text editor
• GCC on your Linux kit
• gdb and printf for debugging^[4]
• A cross compiler, if you so wish

It's perfectly possible to program just by sitting at the black keyboard of the PlayStation 2. Edit files using an editor such as emacs, pico ^[5]or vi(m) in the 'console' (eg DOS prompt style interface), then compile and run code at the prompt. There is an obvious disadvantage if you use an editor that requires an X windows based GUI; every time you want to test your code, you have to drop out of X, run your graphics code, and then start X again. Switching between X and the console is not something that the kit does very well^[6].

If you would prefer to edit your files using your favourite PC editor, that is possible too. If your PlayStation 2 and PC are on the same network, your updated files can be saved and transferred to the PlayStation 2 either using an FTP client, or by creating a windows file share on the PlayStation 2 using samba, and dragging the files across in Windows Explorer, or just editing the files directly on the PlayStation 2 file share.

If you prefer a much more integrated development environment, some people have spent time configuring their favourite IDE to compile PlayStation 2 code using the cross compiler available from the ps2stuff project.

• Sauce wrote this HOWTO document about using Visual Studio with the kit.
• Also posted in the same 'HOWTO' project, is a similar howto by MisterJ, which actually inspired Sauce to write the updated document.

Other useful stuff

If you haven't explored your Linux kit much yet, there are a few utilities that you should know about that will make developing easier. Some of these are commands that you will find on any Linux system.

1. setcrtmode
   setcrtmode is used to change the video output from the console in real time. This is great if you are using the AV adaptor to connect your kit to a monitor and a TV at the same time. It's also a useful tool to 'reset' your display if you've just run a demo or some of your own code that has left the display outputting in something that you can't see (e.g., VGA on a TV).
2. locate
   Use locate to find a file that you're trying to locate on your harddrive. Locate relies on you running "updatedb" as root to keep the index of your HDD recent; it'll warn you if the DB is more than 8 days old. Locate always returns anything that includes the string you give it anywhere in its own name. Example: locate libps2 ...will generate a list of all the files on your HDD that have 'libps2' somewhere in the file or the path to it.
3. grep
   Grep searches a file for a particular expression, and prints out the line it was found on, if it is found in the file.
   Usage:grep <pattern> <file>
   Note that the file can also be an expression, using * as a wildcard to match against anything.
4. | less
   If you run a command (like locate) and it outputs more text that you can fit on the screen, you can laboriously press Shift+PageUP to scroll back through it, or you can run the command again and append | less to the end, to redirect the output through less. Less is a pager which will pause when the screen is full, and let you browse the output at your leisure. Use space to view the next page, return to scroll down one line at at time, and 'q' to quit less.

First Reading material

The first thing to do is get the Hardware Manuals from Disc 1 of the Linux DVD set. They are in a folder called "sm_pdf". Some of the manuals are huge and way too detailed to be useful as tutorial material - they are just a comprehensive reference of how the hardware works. For now, the best place to start is by reading the 'EE Overview manual' (EEOVER_E.pdf)^[7]. It's significantly shorter than the others, and aims to describe the architecture of the PlayStation 2 and explain what each component can do. If you're not familiar with the architecture of the PlayStation 2, take the time to familiarise yourself now. Establish the basic connections between the EE - both CPU Core and the Vector Units - and the Graphic Synthesiser. Note the significance of Paths 1, 2, and 3 to the GS. Understand that the DMA controller is fundamental to moving data around between each component. Take note of the scratch pad, and the speed advantage it offers if used. Notice also how Vector Unit 0 is flexible, able to run either in macro mode, bound to the main CPU core as a co-processor, or in micro mode, as a totally independent processor. Consider how code that runs on the PlayStation 2 will get the best performance by trying to keep all these different components busy simultaneously.

Open up the other hardware manuals just to take notice of what they are and what they contain, but don't try to read right through them right now - there is far too much information to digest at once. Consider them reference material, and slowly as you revisit them things will fall into place. The EE Users Manual (EEUSER_E.pdf) is most invaluable, containing information about DMA, and the VIF and GIF. Keep it next to your pillow :) Similarly the VU Users Manual and GS Users Manual are the next most useful to refer to.

If you're not adverse to reading Powerpoint presentations, have a look at Introducing the PS2 to PC programmers, by David Carter from SCEE's developer support team. The slide comments provide a good commentary, and the talk gives an overview of how the hardware is intended to be used.

If you'd like some more material about the architecture of the PlayStation 2 there are some online articles that discuss it in some detail:

• ArsTechnica: A Technical Overview of the Emotion Engine
• The Playstation2 vs. the PC: a System-level Comparison of Two 3D Platforms
• Benefits of A Micro-programmable Graphics Architecture (This article requires you to create a free account on gamasutra.com. This is well worth doing anyway.)

Hopefully that has given you a feel for how the PlayStation 2 is a little different to the PC, and you feel acquainted with the hardware you'll be working with. Now to look at some code!

You have a few places to use as starting points. I would strongly recommend the first in the following list, unless you have a particular interest in the alternatives.

Development Options

• Using the SPS2 module - recommended!
  The SPS2 module is a great development framework for programmers to adopt to get a lot closer to the PlayStation 2 hardware. As a kernel module, it is Linux friendly, but it also takes care of many of the inconveniences of having to access the hardware through the full Linux operating system rather than the very minimal PS2 native kernel.
  
  SPS2's author, Steven Osman, wrote the module while taking a lot of advice from developers with access to professional development hardware. As a result, the framework that SPS2 provides is certainly a much more similar experience to developing for native PlayStation 2.
  
  Where to get it: SPS2 comes in two parts: the kernel module itself (which is all you need if you just want to run programs that use SPS2), and the supporting framework and header files that developers use to access the hardware through SPS2. Both parts are available from the SPS2 project page on playstation2-linux.com.
  
  Where to start: Download the SPS mod and dev packages. Step by step (as root):
  1. wget http://playstation2-linux.com/files/sps2/sps2dev-0.4.0.tgz
  2. wget http://playstation2-linux.com/files/sps2/sps2mod-0.4.0.tgz
  3. tar zxvf sps2mod-0.4.0.tgz
  4. cd sps2mod-0.4.0
  5. make depend
  6. make
  7. make install

  This will compile and set up the SPS2 module so that it is loaded by your kernel every time that you start Linux. To load the module straight way, you can run sps2_load, and if you want to remove it again you can use sps2_unload.

  Next take a look at the sps2dev packages:

  It's advisable to be root when you do this (at least for now^[8]). If you are already logged in, don't worry. Just type 'su' and then the root password when prompted, and you will 'superuser' to root until you log out by typing 'exit' (or hitting control-D).
  
  1. tar zxvf sps2dev-0.4.0.tgz
  2. cd sps2dev-0.4.0
  3. cd samples
  4. less readme.txt (if you'd like to read some comments on the samples included)
  5. cd vspeed
  6. make (to compile the code for the example)
     Now the moment of truth - run a sample that uses sps2
  7. If you haven't loaded the sps2 module yet^[9], do: sps2_load
  8. ./vspeed
     
  Et voila - you should now see 600,000 odd polys revolving on your screen (woo!).

  Now is a great time to cd ../../docs, print out SPS2-0.4.0.pdf and take a look through the excellently written documentation provided by Sauce.

  After that, check out the tutorials (also in the docs directory) and then check out Henry Fortuna's tutorials.



• Using the libps2dev library
  libps2dev is an alternative way of programming the PlayStation 2 hardware in "PS2 Style". This library is included in the supplied Linux distribution. Compared to SPS2, it is much less structured and convenient to use, however you might want to take a look at the two graphics demos included with it, out of curiosity if nothing else.
  
  Where to get it: Libps2dev comes installed in your linux kit, in /usr/doc/PlayStation2/libps2dev.

  Take a look through the files there. The _en endings are the english versions, although ps2dma_jp.txt is actually in English.

  There are two code samples included with libps2dev. One is a basic texture and lit cube that can be moved around with the controllers, and one is a particle demo that displays three fountains of particles, that can also be moved around with the controller in analog mode.

  Take a look at them both (again, you may need to be root to compile these. "su" if you see any "permission denied" errors):

  1. cd /usr/doc/PlayStation2/libps2dev/sample/vu1/blow
  2. make
  3. And then, if you are in the US/Canada/use NTSC: ./blow -ntsc
  4. Or, if you are in Europe/Africa/Middle East/Australia/use PAL: ./blow -pal
  5. Or, if you're using a monitor: ./blow -vesa
  
  That's the impressive looking demo that runs mostly on Vector Unit 1. The source code for the demo is all right there in that directory, although sadly there aren't that many comments.

  You can follow a similar pattern for checking out the basic3d demo that is also in the sample directory.

• VU coding
  Are you particularly into writing graphics routines in assembly? If so, maybe you just want to get stuck into writing some VU code. (If not, maybe you'd find the Vector Unit Compiler interesting?)

  You can literally get stuck right in if you use the VU code harness that was written for our Vector Unit Coding Competition.

  The harness is designed such that you literally load your data into Vector Unit 1 and execute it, and that's all there is to it. Each different file in the project represents a different competition that has been held, either for professionals or amateurs, some in the US (SCEA), some in Europe (SCEE).

  If you want to learn more about using PATH1, or you want to test out some PATH1 ideas, using the harness is a great way to do it.

  For the most comprehensive set of demos, grab the PS2Linux entries tarball. The entries for that competition are in one harness, and then a large compendium of entries from past competitions are bundles into a harness in a previous_demos directory.

  Here's a walkthrough:

  1. wget http://playstation2-linux.com/files/vudemocontest/vu_coding_contest_2003_ps2linux_entries.tgz (to actually download the file, if your kit is online)
  2. tar zxvf vu_coding_contest_2003_ps2linux_entries.tgz
  3. cd vu_coding_contest_2003_ps2linux_entries
  4. harness -s (for VGA) or harness -p (for PAL) or harness -n(for NTSC).
  5. Cycle through the demos using L1.
  6. Hit control-C to kill it after you're done
  7. Now cd previous_demos
  8. Again run harness using the same options as above.

  One of the demos included is a simple triangle, which is used as a placeholder for entrant's code. Take a look at how it puts the triangle on the screen to see how the harness should be used.

  There are a couple of Vector Unit docs out there: Eratosthenes' VU tutorials (the homepage) and the project page, and Myrkraverk's Extremely Short MIPS Assembly HOWTO. There's also a good introduction to assembly programming for beginners online here.

  The best VU demo by far is VUniverse, written by Mike Day. Mike actually wrote a 10 page document about how he developed this demo, which is well worth a read if you're as amazed by it as us!

Higher level APIs available to you:

• ps2gl

This is really the most interesting, higher level API for developing graphics on the PlayStation 2. Tyler Daniel, a SCE developer, wrote ps2gl as a clone of OpenGL that takes advantage of the PlayStation 2 hardware.

ps2gl has a mailing list, and a project page.

Where to get it: a version of ps2gl actually comes included on the Linux kit DVDS, and will be installed on your hard drive if you've done a full install (see below).

Where to start:

1. cd /usr/doc/ps2gl-0.2.2/examples
2. make run

Pick up the latest release of ps2gl from the project page. You can also visit Tyler's ps2gl page, and join the mailing list.

Useful resources

The two most invaluable resources that haven't been mentioned so far are the IRC channel registered on freenode, and the Developers forum on this website.

The IRC channel(s)

Members of the ps2linux community have registered two channels on irc.freenode.org:

• #ps2linux for general discussion
• #sps2 for discussion about the sps2 project
  This channel probably sees more activity day to day!

While you might not get an immediate response to a question you have, you can learn a lot by spending some time on the IRC channel, listening to some of the discussion. Both channels are quite friendly.

The developers forum

You don't have to own a kit even, to take part in the discussion forums. So register on the site and subscribe!

The developers forum can be found here.

There are actually seven discussion forums:

• The general discussion forum
• The hardware forum
• The kernel forum
• The software forum
• The developers forum
• The new user forum
• The networking forum

You can either check in to the forums yourself with your web browser, and then 'save place' when you are up to date. New posts will show up bold. Alternatively you can monitor the forum by email.

Tips

• Mount /home and /usr partitions as read only. Putting together a bad DMA chain inevitably upsets the Linux kernel and causes the hardware to crash, requiring a hard reset. When Linux is shutdown without the chance to umount all the hard drive partitions first, it will check them over using 'fsck' the next time that Linux is booted. 'Fsck' takes about the same amount of time as running ScanDisk in DOS/Windows, and is just as annoying.
  If you create separate partitions for /home and /usr when installing Linux, you can set them as read only in your /etc/fstab file. This way, even when you have to hard reset, these two partitions will be fine, and only the / partition will need to be fscked.
  This is handy to know because, unlike ScanDisk, it is not possible to quit out of fsck.
• Booting off Disc 1 and memcard only. Michael Mahr has written a tutorial about booting Linux using a Memory Card and DVD 1 only, and with SPS2 loaded. This has obvious advantages for developers that crash their PS2 a lot and don't want to have to wait for the HDD to be fscked on every reset.
• File permissions. If you wish to resolve any issues you have with permissions that force you to do a lot of your work as root (most Linux users try to avoid this), you will need to use 'chmod' to change the permission settings on the relevant files and folders. Try 'man chmod' for full details about how this works.
• Quitting a demo. If you ever run a demo and there is no obvious way to quit it, just hit control-C. This will kill your current running process. If the screen is still blank, then try typing setcrtmode and then enter. This should hopefully reset your display.

Other tools worth knowing about

1. VCL
   VCL stands for 'Vector Command Line', and anyone who spends some time programming the Vector Units should get familiar with this utility. It is an invaluable aid, generating VU code with better instruction scheduling and other optimisations that are very time consuming to do by hand.
   While a version of VCL is included on Disc 1, there is an updated release available on the VCL project page. This includes a very helpful PDF manual.
2. SVVUDB
   "Sauce's Visual Vector Unit Debugger" (svvudb for short) is a graphical debugger for the vector units. It has an interface that you view on your PC while you execute code on the PS2. This is an X-Windows interface for the PS2, for a PC running linux, as well as a native Windows interface for a PC running Windows. If you're developing VU code that's not targetted towards graphics, you could also run X on your PS2 and use this to debug the code. The debugger supports both VU0 and VU1.
3. GSVNC
   GS VNC is a VNC compatible server that displays the frame buffer of the Graphic Synthesiser^[10]. This is very, very useful if you are working in a different room from your PlayStation 2, and you want to see what the PlayStation 2 is displaying when running some graphics code.
4. PS2 Conversion Utilities
   The project hosts a number of utilities for converting different 2D and 3D formats into other useful formats.
5. Texture swizzler
   ezSwizzle is a Windows MFC application that allows you to swizzle/unswizzle your textures. It reads a number of formats and has a batch feature to convert all your textures quickly. It generates TIM2 files, but with the source provided it is very easy to change it to generate any format you are using. The documentation also explains the theory behind texture swizzle and has a table with swizzleable sizes and respective speed increases.
   If this interests you, you can also read Sparky's swizzle code, which has some very simple functions for texture swizzling.
6. SPS2 demos
   Exoticorn and Sparky have put together a handful of demos that use the SPS2 module, and demonstrate what it can be used to do. These demos include code for building packets, and uploading textures, which could easily be pulled out and re-used for other projects.
   Rather than create versioned releases of the demos, they have just checked the files into CVS, so to download the files you must click on "Source repository" and then "Browse CVS Repository" and then "download tarball".
   Alternatively you can just click here.
7. VUC - Vector Unit Compiler
   If you're not keen on the idea of writing assembly, two intrepid members of our community have developed a reasonably full featured C compiler for the vector units. Impressive!

Further Reading

• Henry Fortuna's tutorials are very well written, and an excellent introduction into coding for the PlayStation 2. They make use of SPS2, which is a great framework for PlayStation2 coding in a professional style.
• If you want to write some inline assembly for the main CPU core, consider reading "See MIPS Run". It's widely considered one of the best books about programming for chips based on MIPS.
• SCEA's Robin Greene has an excellent article on procedural rendering published on gamasutra - it's free to register to read it, and well worth doing so.
• http://research.scea.com/ is SCEA's R&D website. There are some interesting papers there that have been presented at past GDC conferences and other events.
• The SCEE Technology Group website offers articles and presentations that Technology Group staff have written and presented.
  It also lists any current vacancies in the group.
• If you get into writing inline assembly on the EE core, you should check out Sparky's Guide to Assembly Speedups on the EE Core.

This document is maintained by Sarah Ewen, an employee of Sony Computer Entertainment Europe, and one of the website admins. Feel free to send me items for addition, improvement or feedback.

Thanks go to Steven Osman (Sauce), Morten Mikkelsen (Sparky), Lionel Lemarié (Hikey), Dennis Ranke (Exoticorn), Paul Smith (Eratosthenes), Henry Fortuna (hfortuna), Jonathan Hobson (Kazan), Johann Oskarsson (Myrkraverk), John S (MisterJ), and Michael Mahr (MrM) for writing so many useful utilities, tools and documents - and for the feedback I've had while writing this guide.

[10] VNC stands for Virtual Network Computing. It is remote control software which allows you to view and interact with one computer (the "server") using a simple program (the "viewer") on another computer anywhere on the Internet. The two computers don't even have to be the same type, so for example you can use VNC to view an office Linux machine on your Windows PC at home. VNC is freely and publicly available.