What's this?
|
This little document was written in order to make it easier for you to get started
with coding the psx. (Ehrm... well... infact the huge amount of questions
hitting my inbox somewhat 'motivated' me to write this as well ;=) hehe....) However, this doc is dedicated to PSX-newbies, not PROGRAMMING-newbies, so if you don't have a certain amount of programming knowledge better get a good book from your local library - This will not teach you how to code but it will make it possible to use your existing programming skills... if you are interested in getting started with psx code, you may want to save this page for further reference, 'coz a lot of the so called FAQs (oh G0d i hate this word =) may be answered here. |
What's new?
| 01/06/99 | nothing... or everything... whatever ;) |
Contents
|
What IS ...? - Terms and abbreviations What do i need to program the PSX? Hardware Software Now when i got all this, how to make it work? commslink, action replay/gameshark setting up your Tools fighting your makefiles |
First Aid Programming basics So far so good... Now, may i look at some examples? Is it legal to program the PSX?
Info on the Internet
|
| SN | System News ... uh, no that's wrong =) Actually, the abbreviation 'SN' had been invented back in the 'old days' and no one really remembers it's exact meaning .) However, these are the ones responsible for PSYQ (the professional/commercial compiler set). |
| SCEE | Sony Computer Entertainment Europe |
| SCEA | Sony Computer Entertainment America |
| SCEI | Sony Computer Entertainment Japan |
| NDA | Non Disclosure Argument - the contract you have to seal with SONY in order to become a licenced developer or net yaroze member (it basically tells you not to spread anything and not to talk to anyone...nice, hu? =) |
| PSX |
Playstation, a 32-bit video-game Console (developed by Sony Corporation) 2 Mb System-RAM, 512K Kernel ROM I/O: 2 serial (PAD), 1 serial (non RS232, can be interfaced with Skywalker's YAROZE cable), 1 parallel port 3 16-bit root counters 7 DMA channels |
| YAROZE | (Ya-rou-ze: japanese for "let's do it!"). 'black' PSX designed for hobby-development |
| CPU |
Central Processing Unit 32-bit MIPS RISC R3051, 34 MHz (developed by LSI Logic) |
| GTE |
Geometric Transformation Engine Equivalent to the numerical-value operation processor which takes charge of operation of 3D. By being only for 3D operations, it differs from the standard floating-point coprocessor of R3000 |
| MDEC | Motion jpeg DECoder engine |
| GPU |
Graphic Processing Unit 1 Mb Video RAM Equivalent to 3D accelerator board of PC, takes charge of polygon drawing |
| SPU |
Sound Processing Unit 12K of Sound RAM 24 ADPCM channels, 44.1 Khz Equivalent to sound boards, such as sound blaster. |
| MMU |
Memory Management Unit |
| CD-ROM |
double speed ISO9660 compatible file-system 256KB cache |
| SIO |
serial input/output |
| PIO |
parallel input/output |
| ARP/AR | Action RePlay |
| PAR | Pro Action Replay |
| GS | Game Shark |
| OT |
Ordering Table An OT is basically a list of drawing primitives to be drawn by the GPU, similar to openGL display lists |
| CLUT |
Color LookUp Table In 4 or 8 bit graphics mode the palette of colors is defined in a CLUT |
| LIBPS |
Usually, if a program is created in NET YAROZE environment, it will be using libps.
libps consists of libps.a and libps.exe, where libps.a is linked to a program,
and libps.exe is read from system CD-ROM of NET YAROZE. The relation of libps.exe and libps.a resembles the relation of the dynamic link library (.DLL) of MS-Windows, and the import library for using DLL. Only the jump table to the library, not the library main part which is in libps.exe, is recorded by libps.a and linked to a program. If you want to execute a Yaroze intro/game on gray PSX, you must load LIBPS.EXE to 0x8000f800 before running the intro or game. |
| .tim |
image format that is supported by psyq/yaroze libraries |
| .tmd |
psyq/yaroze 3d-object format |
| .vag |
ADPCM packed sample that can be played by SPU |
| .seq |
sort of midi file that can be used with psyq/yaroze libs |
Hardware
| professional Devkit, debugstation ("blue PSX") |
| This is only available from Sony for licensed developers, so you either already got one or prolly never will ;=) |
Software
| Action Replay flash-ROM replacement |
|
Inside ARP there is a flash EEPROM, that contains the code executed by Playstation
when the ARP itself is turned on. A ROM Replacement is a binary file that
can be flashed inside the ARP. You need to replace the original ROM by one that is more suitable for coding (so you can manually load executables and data file inside PSX memory, inspect/modify memory and registers, etc.) or else you will go mad for sure after working with the tools that came with the cart (since they are mostly made for cheating games, not running 3l337 code hehe) ;=) |
| myAR (by Foo Chen Hon) get it here (15kb) |
|
This is a skeleton example of an AR/GS rom replacement. It comes complete with source
for reference and its quite easy to add whatever desired function. |
| Ez-o-Ray (by Snake & McBain) |
| EZ-o-Ray is the historical ROM replacement. It is simple to use, but development was discontinued for unknown reasons. |
| Caetla (by K-Comm) |
| Caetla has tons of features, and it is under development. These days 100% translated english versions are available, it has support for both AR and xploder. Although the only way to get it is to register for an account at their pages with a NON-anonymous mail account (they filter out shit like hotmail, gmx, yahoo etc). This was a reaction to Caetla being ripped by EMS, and since k-comm still don't charge no money or whatever i'd just advice you to respect their wishes. |
| Compilers/Assemblers |
| unless you don't like diehard hexeditor coding, you'll need one of these 8=) |
| PsyQ (by SN and SONY) |
| PsyQ is the official compiler set, included in the official Sony Development Kit for Playstation. It is available from Sony Corporation for licensed developers only, so i suggest you to forget it. |
| YAROZE (by SONY, partially GNU) |
| The tools coming with the yaroze devkit generally are a mips-crosscompiler built on GNU, but they come with copyright protected libraries and some tools. You cannot legally use it unless you are a member of NET YAROZE. |
| MIPSGCC (by CO) get it here (2404kb) |
| This is a Cross compiler build on the GNU sources. It doesn't come with any libs nor examples, but nevertheless its FREE. |
| spASM (by Silpheed/Hitmen) get it here (41kb) |
| This is a free r3000/PSX assembler |
| Tools |
| ECO2EXE (by Silpheed/Hitmen) get it here (30kb) |
| Black EXEs are the executable generated by Yaroze compilers (that is, GNU gcc compilers). They are in ECOFF format, and can be converted to Gray EXE with ECO2EXE . Black EXEs don't contain the libraries, that are indeed located inside an external file, called LIBPS.EXE. If you want to execute a Yaroze intro/game on real PSX, you must load this file to 0x8000f800 before running the intro or game. |
| MODE (by Nik/Napalm) get it here (23kb) |
| Use this to change the video mode (PAL/NTSC) in psx- or yaroze .exe's |
| COMBINE (by Barubary) get it here |
| Links a Gray-Exe and LIBPS together in order to get a one-filed executable. |
| CPE2EXE (by Nagra/Blackvision) get it here |
| .CPE is an intermediate executable format generated by PsyQ. You can use CPE2EXE to convert it to a Gray EXEs. |
| ByteKiller (by Silpheed/Hitmen) get it here (32kb) |
| This is a port of the known packer from Amiga. |
| GfxConv (by Silpheed/Hitmen) get it here (31kb) |
| Image data needs to be converted to a format suitable for uploading to the psx's vram. Use this tool to do it... |
| HitLice (by Jihad/Hitmen) get it here (21kb) |
| Use this tools to insert the licence data into your homemade .iso images so they will boot on a chipped psx. |
| HitMod (by Silpheed/Hitmen) get it here (405kb) |
| This includes everything you need to play .mod files in your productions. |
| SinusLab (by Groepaz/Hitmen) get it here exe only (21kb) full install (844kb) |
| This is an easy to use sinus-table generator. |
| CatFlap (by ?/Napalm) get it here |
| An excellent replacement for psexe to be used with caetla rom (worx under nt as well!) |
Setting up your Tools
|
fighting with your makefiles A make-utility generally provides functionality similar to ms-dos batch files and it can be used for various purposes. However, since different make utilities can be used and there also is no space to give a detailed overview about how to write makefiles, i list the necessary commands required to compile mycode.c and get a 'black' executable in the end. If you are not familiar with makefiles yet, i'd suggest you using simple batch files first to get used to the compiler-you will find your favourite make utility sooner or later =) |
| Psyq |
|
ccpsx -O2 -Xo010000 mycode.c mylib.o -o mycode.cpe cpe2x mycode.cpe |
| Yaroze |
|
gcc -O2 -Xlinker -Ttext -Xlinker 80010000 -o mycode.exe mycode.c eco2exe -p mycode.exe |
| CO's MIPSGCC |
|
for a program using systemcalls and your own lib mipsgcc -O2 -Xlinker -mpsx -Xlinker -Ttext -Xlinker 80010000 -o mycode.exe mycode.c mylib.o syscall.o start.o for a program using libps mipsgcc -O2 -Xlinker -mpsx -Xlinker -Ttext -Xlinker 80010000 -lps -o mycode.exe mycode.c start.o |
GNU options
| never worked with GNU tools? this might help you out for a start! |
| common | |
| -S | output assembler code (.s) |
| -c | output object code (.o) |
| -O2 | Effective in optimization |
| -o <file> | specify output filename |
| -D <macro> | define a symbol (same as #define <macro>) |
| -D <macro=def> | define a symbol (same as #define <macro> <def>) |
| -l<xx> | link library named "libxx.a" |
| -Xlinker <option> | An option is passed to a linker. |
| -v | output lotsa debugging info |
| --help | guess what |
| linker options | |
| -Xlinker -Ttext -Xlinker <hex address> | start address (CO's mipsgcc default is 80100000) |
| -Xlinker -meco/-mpsx | generate ECOFF/PSX-EXE format (CO gcc mipsgcc default is ELF) |
Creation of a library for MIPSGCC
| Start up code get it here |
|
Since in GCC the code is performed from _start, a startup code that rises main is needed.
_start just initializes bss area and gp registers here, and __main does nothing. However, initializing heap and other general stuff may also be performed before main() is called. (also, using the heap routines from system calls is NOT recommended, since they are buggy crap =)) extern long _fbss; extern long _end; extern long _gp; register long *gp asm("gp"); _start(){ long *adr; for(adr = _fbss;adr<_end;*adr++=0); // init bss area gp = _gp; // setup gp registers main(); // call main() } __main(){} // called at the head of main() compile: mipsgcc -O2 -c start.c |
| System call library get it here |
|
Although dividing it into standard header files (strings.h,memory.h...) would be
more desireable (so it may not link what is not necessary) it has not been done here
since it had been a little troublesome-so it makes one object file here. Using system calls To use system-calls from c, you need to write yourself a wrapper function that passes the arguments from/to the called bios-routine. When an argument is required in a system call, it is always passed by $a0, $a1, $a2, and $a3, and five or more arguments are passed by $sp+0x10. Also, the system call number is put into $t1 (), and the address (0xa0, 0xb0, 0xc0) of a system call is called. return value (if any), is returned by $v0 (). The return format is the same as that of function call agreement of mips-gcc, so an argument (state of $a0,$a1,$a2,$a3 and a stack) is left intact, and $t1 () is set up. .macro BIOSCALL type,no,name .text .align 2 .globl name .text .ent name name: li ,type .set noreorder jr li ,no .set reorder .end name .endm .macro SYSTEMCALL no,name .text .align 2 .globl name .text .ent name name: li ,no syscall jr .end name .endm Example of a wrapper function: prototype declaration: int open (char * name, int mode); substance:(assembler) open: li ,0xa0 #system call address .set noreorder jr li ,0 #system call number .set reorder Here, although it is using for the temporary register for a jump, if it is except the register with the necessity saving within a function, it will not care about anything. Although it is puzzling just for a moment because of delay branch of mips, if it writes plainly li ,0xa0 #system call address li ,0 #system call number jr #nop When open function is called, an argument is passed to $ a0 and $ a1 like the function of usual C, and the return address is put into $ ra, and open is called. By open, then, $ a0, $ a1, and $ ra put a system call number into $ t1, and jump it to a system call. In a system call, a system call is processed from passed $ a0 and $ a1, and it returns to the place where the address, i.e. open function, of $ ra were called. Back is easy, once it has written the wrapper function by the assembler or the in-line assembler of GCC, although knowledge of an assembler is required for this neighborhood a little. assemble syscall.s: mipsgcc -c syscall.s |
| standard C library |
| Although most C standard functions are in a system call, it can have from libc of GNU the thing for which it is insufficient. Although a floating-point operation coprocessor is not in PlayStation, there is also a floating-point operation library of software. |
| matrix library get it here |
| A GTE optimized matrix library hasnt been published yet, but for now you can have a look at this standard-c version |
| libps import library and header file get it here |
| Although libps.a and header files are not available for the public, it was possible for someone to create them from looking at libps.exe. This is considered to be legal since cygwin32 and mingw32 (which are gcc for Win32) provide similar files for Win32.DLL. |
First Aid
| my Commslink cable fucked up ...! |
| The cable is just a standard 25-pin sub-D male>female, ALL pins connected straight through. If you don't care about building one yourself, a normal modem cable (also the cable for Iomega ZIP drive) is said to work. |
| my ARP seems to be fucked up and i can not reflash it ...! |
| First make sure all the rest of your stuff is fine... check all your environment variables, cables etc again. If all that doesn't help and you have access to a cd-writer, try the 'Ez-O-Ray flasher' (cdrwin/24kb) (easycd/20kb) which will probably help you to solve your problems. |
Programming Basics
| Memory Map | |
|
00000000 - 001FFFFF (2mb) 1F000000 - 1F7FFFFF (up to 8mb) 1F801000 - 1F801xxx (8kb) 80000000 - 801FFFFF (2mb) 80000000 - 8000FFFF (64kb) - 801FFFF0 bfc00000 - bfc7ffff (512kb) |
RAM (uncached) adaptor rom shadow (action replay/gameshark) hardware i/o map: gpu, pads, memcard, pio port, sio port RAM -System Area -Stack Area System ROM (BIOS) |
|
Controlling the Hardware generally the control of hardware is performed through the memory mapped I/O from 0x1F801000 to 0x1F801???. |
| GPU |
|
In order to control GPU (draw lines, flat triangle polygon, gouraud textured
square polygon, etc.) send the command packet with specific structure by
each primitive (basic figure). This is the same thing as Execute Buffer
of Direct3D Immediate Mode. In order to send a command to GPU, there are two, the method of sending 1 word (32 bits) every by CPU using a memory mapped I/O (primitives will be drawn immediately), and method of sending the link list of two or more packets (=an OT list/Ordering Table) at a stretch using DMA, and both are in a system call. The pointer to packet size and the following packet is attached to the head of a packet usual in a link list. 8bit 24bit |size|next ptr| |pkt | |pkt | |pkt | . . |pkt | 24 bits of low ranks are 24 bits of the low ranks of the address of the following packet. Since only 2 M has memory, PlayStation can be expressed enough by 24 bits (it can express up to 16M). 8 bits of highest order are size in word (32 bits) of the packet. In 0, it is the packet of the empty without substance of a packet. An end of a list is -1 (0xffffffff) probably. simple automated pal/ntsc detection (well, it actually detects the bios version but that should be reliable enough): if (*(char *)0xbfc7ff52=='E') SetVideoMode(1); // PAL else SetVideoMode(0); // NTSC |
| parallel port |
|
checking the action replay's switch state: volatile u_long* ar_switch=(u_long*)0x1f020018; // up: 0xffffffff down: 0xfefefefe if ((*ar_switch)&1) { // do something for switch up } else { // do something for switch down } |
| Input and output of a file |
|
Input and output of a file can be treated systematically by the system call equivalent
to the low level input-and-output function of C, such as open/read/write/lseek/close.
read/write/lseek needs to carry out in a block unit peculiar to device.
CD-ROM is 2048 bytes and the memory card is 128 bytes. It seems that it
precedes using these and interruption needs to be permitted by ExitCriticalSection();. The file name is passed in the form of "device name:filename". device name device note cdrom: CD-ROM (read only-naturally ;=) bu00: Memory card of slot 1 bu10: Memory card of slot 2 pcdrv: Hard disk of PC (caetla extension, CWD is root) In order to use a memory card, It seems that InitCARD(1); StartCARD(); _bu_init(); needs to be performed first. It seems that moreover, what in which the file name of a memory card had a certain law nature so that the file name of save data of each soft hat might not overlap is long is used. CD-ROM must be initialized using CDInit(); _96_init(); to make the ISO filesystem operational. According to level 1 of ISO, as for the file name of CD-ROM, ";1" is attached to the end of English capital-letter 8.3 form. In order to see information (file size etc.) and the directory of a file, a system call of firstfile/nextfile is used. This resembles the treatment of DOS or Windows. Since lseek can carry out only in block, the technique of lseeking at the file end and making the file pointer of the position file size cannot be used. In order to load and start an exe from within another exe, use this fragment of code: ResetGraph(3); PadStop(); StopCallback(); _96_init(); LoadExec("cdrom:my.exe;1",0x801ffff0,0); |
| creating a bootable CD |
|
1. prepare your Files - make sure your files have a multiple length of 2048 bytes and your exe-headers are ok. (EXEFIXUP helps with that nicely) - in order to let the psx find the exe to boot at startup, either simply name it "PSX.EXE" or write a "SYSTEM.CNF" file that must be placed in the root dir of the cd. example: BOOT = cdrom:MY.EXE;1 TCB = 4 EVENT = 16 STACK = 801FFFF0 2. make a proper cd image (EasyCD pro 95/HITLICE) - Use EasyCd pro 95 to build an iso (if you intend using HITLICE for inserting the license info.Most other programs won't create suitable sector data). - Use HITLICE to insert the licence data into the .iso - Use EasyCDpro 95 to burn your CD - you're set. or (CDR-WIN/BUILD-CD) - use BUILDCD to create a cd image file (notice this is NOT some .iso that you can burn to a cd!) example .cti file: Disc XA_PSX ;disk format LeadIn XA ;lead in track, track 0 Empty 1000 ;defines lead in size min (150) PostGap 150 ;required gap at end of lead in EndTrack ;end of lead in track Track XA ;start of XA (data) track Pause 150 ;required pause in first track after lead in Volume ISO9660 ;define ISO 9660 volume SystemArea LICENSE.DAT ;required licence data file PrimaryVolume ;start point of primary volume SystemIdentifier "PLAYSTATION" ;required identifier VolumeIdentifier "ECTSDEMO" ;app specific identifiers VolumeSetIdentifier "ECTSDEMO" PublisherIdentifier "SCEE" DataPreparerIdentifier "AJM" ApplicationIdentifier "ECTSDEMO" Lpath ;Path tables as specified for PlayStation OptionalLpath Mpath OptionalMpath Hierarchy ;start point of root directory definition File PSX.EXE;1 XAFileAttributes Form1 data Source psx.exe EndFile EndHierarchy ;ends root directory definition EndPrimaryVolume ;ends primary volume definition EndVolume ;ends ISO 9660 definition PostGap 150 ;required to change track type EndTrack ;ends track definition LeadOut XA Empty 150 EndTrack EndDisc -use STRIPISO to fix your image file, so it can be burned with CDRWIN stripiso s 2336 my.img my.iso -write the .iso to a CDR (or CDRW if your PSX is capable to read them, you may try that by playing some audio from CDRW first) with CDRWIN. example cuesheet: FILE C:MY.ISO BINARY TRACK 01 MODE2/2336 INDEX 01 00:00:00 POSTGAP 00:02:00 |
| the serial Port | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Control Register bit Contents
Mode Register bit Contents
|
So far so good... Now, may i look at some examples?
|
Hello World a first dumb program that you can use to test your setup |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| hello.s | ? | ? | ? | MIPSAS | ? |
| hello.c | ? | ? | ? | MIPSGCC | ? |
|
Simple 2D Stuff setting up GPU, simple Primitive drawing |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| GreenTro | Silpheed | 14-09-1998 | 44kb | spASM | Grab the source to Silpheed's GreenTro intro now! |
| Sprite Sample | Jihad | 05-09-1997 | 73kb | Psy-Q | This is a very basic example of the Playstation and all its capabilities. |
| Sprite Sample | Jihad | 05-09-1997 | 126kb | Yaroze | - |
| poly2d.c | ? | ? | ? | MIPSGCC | ? |
| Liamgall Tim Stuff | Liamgall | 12-10-1998 | 133kb | Psy-Q | How to handle images in your releases, really nice example! |
|
Simple 3D Stuff initializing 3D subsystem, displaying objects in TMD format |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| Car 1.0 | Sachiko | 11-11-1995 | 153kb | Yaroze | Another probably never seen before source, and it about, euhm, cars. |
| SPU Stuff |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| Vag-Pack 0.1 | Bitmaster | 28-05-1998 | 1kb | Psy-Q | Source to Pack VAG samples |
| Vag-Depack 0.1 | Bitmaster | 28-05-1998 | 3kb | Psy-Q | Source to Depack VAG samples |
| misc - Intros/Demos |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| Remembers Amiga | BrainWalker | 16-09-1998 | 251kb | Yaroze | look here for a Starfield, a Scroller and some Sprite-Stuff |
| advanced Stuff - Games |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| Breakout | L. Evans | 25-09-1996 | 100kb | Yaroze | A really nice, probably never seen before, source of this kick ass game! |
| Clone | S. Ashley | 28-02-1997 | 383kb | Yaroze | They are taking over the world! Yet another cool source in your face! |
| tech Stuff |
| Release | Coder | We got it on | How big | Compiler | What the fuck is it |
| Psx Movie Finder 1.0 | S-Man | 05-10-1998 | 3kb | C | Grab this tools Source now! Get your Psx Movie's now! |
| Psx Xa Copier 1.0 | S-Man | 05-10-1998 | 3kb | C | Grab this Source as well! Extracts tunes from Psx CD's. |
Where to get Information on PSX so i don't have to re-invent the wheel again?
|
First of all look at these www-sites, i suppose
a lot of your questions will be answered there, if you are a member of
NET YAROZE i suggest you reading your docs again, also looking at some
example Sources might help you out. Nevertheless don't be scared about asking on the psxdev-mailing list or at #psxdev on effnet ... (keep in mind there are no stupid questions, just stupid answers... 8=) |
Is it legal to program the PSX?
| Licensed developers |
| Naturally it is legal for those, but on the other hand the situation is somewhat tricky if you wanted to spread your work to the public without going the 'official' way (due to your NDA)... nevertheless i don't think you are a licensed coder reading this... so ?! ;=) |
| Members of Net Yaroze |
| If ya own a Yaroze you can legally use Yaroze libs (LIBPS.EXE) and compilers, but still are not allowed to spread LIBPS.EXE (which is absolutely necessary to run your code). However, don't expect your amount of friends at SONY getting bigger by spreading anything else either. |
| Hobby programmer using CommsLink+ActionReplay/Gameshark |
| GNU gcc for MIPS, compiled for DOS, Win32 and Linux is available on the Net, as well some assemblers (for e.g. SPASM by Silpheed/Hitmen). As long as you don't use either PSYQ or YAROZE libs it'll be legal to program and spread your work. I am not sure if SONY likes you burning 'un-officially' licensed cd's though. |
boring Stuff
| disclaimer |
| The information is provided "as is". Although i am doing my best i can not give any warranty that it is right or not, so use it at your own risk. You should also be aware of the fact that you shouldn't use this information for other than educational purposes. I can not be made responsible for any misuse of the provided information, nor may you blame me for your fucked up GS or your lame code deleting memorycards instead of drawing lines. |
| credits |
| The provided information was assembled from various sources such as the above mentioned web-sites and nevertheless some of my own experience. |