Imported pristine psxsdk-20190410 from official repo

1 files changed, 287 insertions, 0 deletions

diff --git a/readme.txt b/readme.txt
new file mode 100644
index 0000000..8086d8b
--- /dev/null
+++ b/readme.txt
@@ -0,0 +1,287 @@
+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