288 lines
16 KiB
Plaintext
288 lines
16 KiB
Plaintext
PSXSDK 0.6.2
|
|
ReadMe and FAQ
|
|
Last updated: April 10th 2019
|
|
-----------------------------
|
|
|
|
What is PSXSDK?
|
|
|
|
PSXSDK is an unofficial and homebrewed software development kit for the Sony PlayStation(TM).
|
|
Its programming tools (compiler, assembler, linker, etc.) are based on GNU Binutils and GNU
|
|
Compiler Collection (GCC) while the PlayStation-specific tools, which you need to convert data
|
|
to PSX format, were either written from scratch or adapted from already existing open source programs.
|
|
|
|
It is expected that you are already familiar with programming.
|
|
If you want to learn how to program, I recommend starting programming for the operating system
|
|
your computer uses and not here.
|
|
|
|
This readme is structured as a FAQ which also contains information which is not exclusive to the PSXSDK,
|
|
but that is generally informative.
|
|
|
|
Q: What do I need to run my programs on my PlayStation console?
|
|
|
|
A: There are several methods to do that, either a modchip, a boot disk, a cheating device
|
|
like Caetla, or the "swap trick".
|
|
|
|
The "modchip" method involves soldering a chip on the motherboard of your PlayStation to make it
|
|
think it's reading an original licensed disc. The kind of modchip depends on the model of your console,
|
|
and they are quite hard to find nowadays (as of 2010). You might already have one, as it was very
|
|
common to install it in many parts of the world.
|
|
|
|
I might be actually telling you to ignore your laws (in case you have EUCD and DMCA), and I recommend
|
|
to do it. The constant eroding of our rights as citizens is getting very annoying, and these
|
|
laws need to be fought. Let's not be hypocrites.
|
|
Big money influences law (TM).
|
|
|
|
The "boot disk" method uses a specially-made CD-ROM which looks like it is an original licensed disc
|
|
to the PlayStation. Once booted they show you a menu where you can boot an unlicensed disc.
|
|
You might be able to still find one for sale.
|
|
|
|
The "cheating device" method was very used back in the golden days of the PlayStation scene.
|
|
I have never used this method so I cannot describe it here. Search for "caetla" on your favourite
|
|
search engine and something interesting about that should come up.
|
|
|
|
The "swap trick" consists in first putting an original licensed disc in the PlayStation, so that
|
|
the PlayStation can authenticate, then when the drive is still spinning you replace it with an
|
|
unlicensed disc, and the PlayStation boots the disc as it already authenticated earlier.
|
|
The exact method of the "swap trick" varies between different models of the console.
|
|
It ruins your CD-ROM drive in the long run and spare PSX CD-ROM drives aren't very easy to find
|
|
(maybe harder to find than entire consoles), so I recommend to use something else if you can.
|
|
Search for this on your favourite search engine, something will surely come up.
|
|
|
|
On SCPH1001 PlayStations (Early American models) there seems to be an easier way to do the swap trick, also called audio menu exploit.
|
|
Make the SCPH1001 PlayStation go into the BIOS menu by not inserting any CD,
|
|
then go to the cd player, let it read an original PS1 disc until it stops spinning,
|
|
swap the disc with a burned CD-R disc, and exit the cd player.
|
|
|
|
This trick might also work on early Japanese consoles but I'm not sure of that.
|
|
|
|
Q: How do I get started?
|
|
|
|
A: In most cases, you will simply need one of the precompiled toolchains tarballs which you can find
|
|
on the PSXSDK website (http://unhaut.fav.cc/psxsdk). Extract them so that the PSXSDK can
|
|
be found at /usr/local/psxsdk and you're ready.
|
|
|
|
If you want to do it the hard way, there is no precompiled tarball for your operating system or
|
|
you want to help in developing the PSXSDK, read below on how to build it from sources.
|
|
|
|
Q: How do I compile a program?
|
|
|
|
A: This is easy. It is done almost as you do it usually, but with an additional step:
|
|
|
|
psx-gcc -o myprogram myprogram.c
|
|
elf2exe myprogram myprogram.exe
|
|
|
|
Why the additional step? It is needed because the GNU compiler outputs an ELF executable file,
|
|
which can't be run on the PlayStation. elf2exe converts that ELF file to a PS-X EXE, which
|
|
is the PlayStation's executable format, and which can be booted.
|
|
|
|
Q: How do I make a CDROM image?
|
|
|
|
A: I will first describe how to make your executable boot.
|
|
There are two ways to make your executable boot: you either name it "PSX.EXE" and you
|
|
put it in the CDROM filesystem's root directory, or you set a file named "SYSTEM.CNF" up
|
|
which describes a bit of information about your executable.
|
|
|
|
A SYSTEM.CNF file looks like this:
|
|
|
|
BOOT = cdrom:PROGRAM.EXE;1
|
|
TCB = 4
|
|
EVENT = 16
|
|
STACK = 801FFFF0
|
|
|
|
The BOOT field contains the filename of your program (in this case PROGRAM.EXE in the
|
|
root directory of the CDROM filesystem). I would advise you to not touch the other fields.
|
|
Modifying STACK is even useless (as the starting address of the stack is reset by the PSXSDK
|
|
library to 0x801FFFF0)
|
|
|
|
Now, you can make the ISO9660 filesystem for the CDROM with any program which does that.
|
|
This, for example, is the command you would use to do it with the cdrtools:
|
|
|
|
mkisofs -o test.iso -V TEST -sysid PLAYSTATION cd_root
|
|
|
|
Then you will have to use mkpsxiso to convert the ISO image to a format the PlayStation understands
|
|
and to license it. mkpsxiso outputs a .BIN/.CUE pair, which is supported by most CD burning
|
|
applications.
|
|
NOTE: Some Linux distributions (like Debian and Mint) don't provide mkisofs, but genisoimage instead.
|
|
Replace the command name in the command line and that's it.
|
|
|
|
mkpsxiso test.iso test.bin /usr/local/psxsdk/misc/infousa.dat
|
|
|
|
This will create test.bin and test.cue, and the license applied to the image will be American.
|
|
|
|
Now you can burn the .BIN/.CUE pair with your favourite burning application.
|
|
|
|
Q: Where can I find the function reference for the PSXSDK?
|
|
|
|
A: You can find it either in /usr/local/psxsdk/misc/docs or in the docs subdirectory in the source
|
|
code archive.
|
|
|
|
Q: Are there any examples which show how to use the PSXSDK library?
|
|
|
|
A: Yes. Download the examples archive from the PSXSDK website and compile the examples in it.
|
|
In this way you can also test that your PSXSDK compiler is working correctly.
|
|
You can build them all by running ``make build_examples''
|
|
|
|
Q: What does PSXSDK support?
|
|
|
|
A: It can use the GPU (or GS, Graphic Synthesizer), the SPU, handle the VBlank Interrupt, handle
|
|
the joysticks and read files from the CDROM drive. Which is more than enough to do a 2D game.
|
|
|
|
Q: What is missing from PSXSDK?
|
|
|
|
A: Root counter support and a lot more...
|
|
Even if the PlayStation was very common back in its golden days, there is scarce documentation about it.
|
|
Since version 0.6.2 there is preliminary Geometry Transformation Engine (GTE) support provided by libmeidogte
|
|
|
|
Q: Why does the C library appear incomplete?
|
|
|
|
A: Many standard C library functions are wrapped around their implementation in the BIOS which keeps
|
|
code size low and eases implementation, but this also means that they have less features than
|
|
most C libraries of today. That isn't a big problem, because for games you don't need a lot of features.
|
|
Anyway, you can modify the PSXSDK to remove the wrapper and use your functions.
|
|
The PSXSDK already does that for BIOS functions which were found not working or too buggy (like memcpy).
|
|
|
|
Q: Help! My PlayStation crashed / something odd appeared on screen / other hardware bug
|
|
|
|
A: PSXSDK was primarily tested on a PAL SCPH-102 PSOne, on SCPH-5552, SCPH-7002 and SCPH-9002 PlayStations and on the PCSX emulator.
|
|
There are probably several hardware quirks and oddities I've not accounted for but which happen
|
|
on other models of the console. Please send an email if something like that happens.
|
|
Be sure to read realhw.txt in the documentation directory first, though, as it might be
|
|
an easily fixable error on your part.
|
|
|
|
Q: What program can I use to convert my images to PlayStation format?
|
|
|
|
A: You can use bmp2tim which is included in the PSXSDK or any program which converts an image to
|
|
PlayStation TIM format. It is a fairly standard format in the PlayStation field.
|
|
|
|
Q: What program do I use in case I want to convert sound?
|
|
|
|
A: You can use the included wav2vag or any other program which converts to that format.
|
|
As it is the case for TIM, VAG is a quite standard format in the PlayStation environment.
|
|
|
|
VABs are just find compilations of more VAG files.
|
|
|
|
Q: Can I sell a game I make with my PSXSDK?
|
|
|
|
A: Yes, as you are not infringing any copyright.
|
|
|
|
Q: I want to use Caetla to upload and test programs on my PlayStation, but I cannot find a version of CatFlap for an operating system which is not DOS or Windows. Are there?
|
|
|
|
A: Very recently Fabio Battaglia (hkzlabs) released his CatFlap for Linux. You can use that on Linux, and use its source
|
|
code as a starting point for a port to other operating systems.
|
|
|
|
Q: When uploading and running programs with CatFlap, they hang after some PSXSDK initialization messages.
|
|
How can I make them not hang? I cannot run anything!
|
|
|
|
A: Insert a CD into the drive of your PlayStation. It doesn't have to be a PlayStation CD, any CD is good.
|
|
This happens due to the initialization routines of the CDROM subsystem. Hopefully it will be fixed someday.
|
|
|
|
Q: How can I change the writing and the logo at the "Licensed by Sony" PlayStation bootscreen?
|
|
|
|
A: That information is contained inside the license file that you use to license the CD-ROM image that you burn.
|
|
Thus, to modify the information you must use the "lictool" program included in the PSXSDK tools.
|
|
lictool modifies various information contained in the license file such as the writing, the logo, etc.
|
|
|
|
For example, to output a new modified American license file which uses your logo contained in new.tmd:
|
|
|
|
lictool /usr/local/psxsdk/share/licenses/infousa.dat my_new_license_file.dat -tmd=new.tmd
|
|
|
|
Remember to use my_new_license_file.dat when you use mkpsxiso, otherwise you will use the standard
|
|
American license file, and your new logo won't appear!
|
|
|
|
Logos are in TMD format, the format for 3D models in Sony's original development kit.
|
|
|
|
Q: My music module sounds wrong or weird when I play it with libmodplay
|
|
|
|
A: Most music module formats have a lot of built-in effects, which are often poorly documented,
|
|
very complex to implement and which are often thought for personal computer hardware which is less
|
|
limited than the PlayStation SPU in some aspects. Luckily most modules don't really use them
|
|
or sound quite right when those effects are not implemented.
|
|
|
|
Q: I heard that it is possible to make the PlayStation read CD-RW discs (CD-rewritable). Is this true?
|
|
|
|
A: Yes, it is. But it is only really usable if you want to do hardware programming tests, as the amount
|
|
that the CD drive of your PlayStation may be able to read might be around 128-150 kilobytes. You will
|
|
not be able to read original PlayStation games or CD-Rs, and if you try to do it, your laser pickup might
|
|
get stuck and you may have to unblock it by unscrewing it and sliding it with your hands...
|
|
With a relatively good laser and very good tuning you might be even able to play full fledged games.
|
|
|
|
To read CD-RWs on later model PlayStation/cd drives you have to tune the potentiometer on the CD drive
|
|
from its original position to 12-13 hours. It actually sort of looks like a clock. Remember the original
|
|
position to not ruin anything. Use a precision screwdriver to tune the potentiometer.
|
|
This will stress the laser in the CD drive more than it is in normal operation, and it will shorten its life.
|
|
|
|
The trick to tuning the potentiometer correctly is burning an audio track on the CD-RW and playing the audio track
|
|
in the PlayStation CD player. If the audio track plays smoothly enough, it will be able to read CD-RWs.
|
|
|
|
You may need several tries before you succeed booting a disk, this happens due to the extensive read checks done
|
|
by the PlayStation BIOS when booting a game.
|
|
|
|
This is my (Giuseppe Gatta's) experience, and it might work much better on your PlayStation/PS cd drive
|
|
or it might work much worse. PlayStation cd drives are very finicky, I myself have PlayStations which read
|
|
like new and some which almost do not read at all. The CD drive is the lowest quality item inside
|
|
a PlayStation.
|
|
|
|
On the other hand this is the cheapest way to test things on your modded PlayStation.
|
|
|
|
Q: I don't use double buffering in my program/game. Nothing is shown on the emulator but it displays fine
|
|
on the real hardware. Where is the issue?
|
|
|
|
A: You are using a buggy GPU plugin. If you're using version 1.0.16 of the P.E.Op.S SoftX Driver or most other
|
|
P.E.Op.S GPU plugins, update to P.E.Op.S SoftX Driver 1.0.18 and the problem should go away.
|
|
|
|
Q: What is a .PSF music file?
|
|
|
|
A: A .PSF music file is in the Portable Sound Format which is used to store video game music data.
|
|
Actually the .PSF just contains a tiny bit of information data in its header and then a compressed executable
|
|
which can be executed by an emulator (or a video game console). A PSF player is just a stripped-down emulator,
|
|
which supports only the SPU and the executable inside the PSF is an executable hacked to play only music.
|
|
Originally it was meant only for the PlayStation but now there are music files in this platform-indipendent format
|
|
from many consoles. You can play a .psf music just by using your console or emulator. Use the psfex tool shipped
|
|
with the PSXSDK, extract the .exe from the PSF and then run the executable.
|
|
More info here: http://www.neillcorlett.com/psf/
|
|
|
|
Q: Why are filenames limited to the MSDOS-like 8.3 naming convention?
|
|
|
|
A: Because the ISO-9660 filesystem used on PlayStation CDs has the 8.3 limit for filenames.
|
|
It is plain ISO-9660 without any extension like Joliet or Rock Ridge, which are commonly added on CDs meant
|
|
to be read on computers to overcome the filename limit and to add new features.
|
|
The PSXSDK can make use of TRANS.TBL files in the directories of your CD to emulate long filenames.
|
|
TRANS.TBL is a normal text file which assigns long filenames to normal ISO9660 filenames.
|
|
Its rows look like this:
|
|
F SYSTEM.CNF;1 system.cnf
|
|
|
|
What this row does is assign to long filename system.cnf the short filename SYSTEM.CNF;1
|
|
'F' denotes that system.cnf is a file, otherwise 'D' denotes directories.
|
|
|
|
Good ISO image making tools will support the automatic creation of a TRANS.TBL file for each directory at image creation.
|
|
For instance, adding the -T parameter to your mkisofs command line makes mkisofs do just that.
|
|
|
|
To make fopen() use long filenames you will have to use the cdromL: pseudo device instead of cdrom:
|
|
Spaces are allowed in paths and both the slash and the back slash can be used to separate directories.
|
|
Examples: cdromL:/Path To/My Filename , cdromL:\Path To\This Name
|
|
|
|
There is a perfomance penalty when using long filenames because doing that requires reading the
|
|
TRANS.TBL for every directory which is encountered.
|
|
|
|
firstfile() does not support long filenames (yet) and open() does not support them, either.
|
|
|
|
Q: I'm running <linux distribution> and audio doesn't work in PCSX!
|
|
A: Many new Linux distributions are using PulseAudio. Run 'padsp pcsx' instead of 'pcsx'.
|
|
|
|
Q: Why is this SDK called PSXSDK? The PSX is a DVR+PS2 hybrid released by Sony in Japan!
|
|
A: Almost nobody knows about the Japanese PSX from 2004, and on top of that, it was a marketing flop.
|
|
Seriously, PSX ('PlayStation eXperimental') is the name the original PlayStation went by during development and it continued being called like that later. The name stuck and it is here to stay.
|
|
|
|
Q: Can I use UPX to pack an executable I made with PSXSDK?
|
|
A: Sure, you can. Due to a technicality of elf2exe, you need to specify --force on the UPX command line.
|
|
It seems to work well, but I did no extensive testing, so it is at your own risk.
|
|
|
|
Q: Why do programs not work on the ePSXe/pSX/... emulators?
|
|
A: Despite popular belief, ePSXe and pSX are not as accurate as it is thought.
|
|
It is recommended to use PCSX Reloaded for testing.
|
|
The rule of thumb is that when something works fine on real hardware, and the
|
|
emulator freezes or does something unexpected, it's the emulator's fault.
|
|
|
|
Written by Giuseppe Gatta
|
|
E-mail: tails92@gmail.com
|