itdominator
/
Notes
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Notes/src/TXTs/Psf File Structure Format.txt

459 lines
16 KiB
Plaintext
Raw Blame History

-----------------------------------------------------------------------------
PSF (Playstation Sound Format) specification v1.3
by Neill Corlett
-----------------------------------------------------------------------------
Introduction
------------
The PSF format brings the functionality of NSF, SID, SPC, and GBS to the
Playstation and Playstation 2. PSF utilizes the original music driver code
from each game to replay sequenced music in a perfectly authentic, and size-
efficient, way.
The general idea is that a PSF file contains a zlib-compressed program which,
if executed on the real console, would simply play the music.
See the Revision History at the bottom of this file for information on what's
changed.
-----------------------------------------------------------------------------
Basic File Structure
--------------------
All PSF files share the same basic stucture, described below.
Alignment to any data type larger than a byte is not guaranteed in the PSF
file. Exercise appropriate caution.
- First 3 bytes: ASCII signature: "PSF" (case sensitive)
- Next 1 byte: Version byte
The version byte is used to determine the type of PSF file. It does NOT
affect the basic structure of the file in any way.
- Next 4 bytes: Size of reserved area (R), little-endian unsigned long
- Next 4 bytes: Compressed program length (N), little-endian unsigned long
This is the length of the program data _after_ compression.
- Next 4 bytes: Compressed program CRC-32, little-endian unsigned long
This is the CRC-32 of the program data _after_ compression. Filling in
this value is mandatory, as a PSF file may be regarded as corrupt if it
does not match.
- Next R bytes: Reserved area.
May be empty if R is 0 bytes.
- Next N bytes: Compressed program, in zlib compress() format.
May be empty if N is 0 bytes.
The following data is optional and may be omitted:
- Next 5 bytes: ASCII signature: "[TAG]" (case sensitive)
If these 5 bytes do not match, then the remainder of the file may be
regarded as invalid and discarded.
- Remainder of file: Uncompressed ASCII tag data.
Tag data may be subject to truncation, including removal of the excess data
from the file itself, if it exceeds 50,000 bytes. This is by design.
For future compatibility, tag editors and compressors may assume that any
PSF file uses this basic structure. However, the reserved area must be left
intact, and no assumptions may be made about the format or contents of either
the uncompressed program or reserved sections without first checking the
version byte.
Information about zlib is available at http://www.gzip.org/zlib/.
-----------------------------------------------------------------------------
Tag Format
----------
The tag consists of a series of lines of the format variable=value, as in the
following example:
title=Earth Painting
artist=Yoko Shimomura
game=Legend of Mana
year=1999
The tag is to be parsed as follows:
- All characters 0x01-0x20 are considered whitespace
- There must be no null (0x00) characters; behavior is undefined if a null
byte is present
- 0x0A is the newline character
- Additional lines of the form "variable=value" may follow
- Variable names are case-insensitive and must be valid C identifiers
- Whitespace at the beginning/end of the line and before/after the = are
ignored
- Blank lines are ignored
- Multiple-line variables must appear as consecutive lines using the same
variable name. For instance:
comment=This is a
comment=multiple-line
comment=comment.
- Tag text is to be encoded or decoded using the default system code page.
Behavior is undefined if a variable name appears more than once, if a
multiple-line variable is broken apart by an unrelated line, etc.
The following variable names are predefined:
title, artist, game, year, genre, comment, copyright
(These are self-explanatory.)
psfby
The name of the person responsible for creating the .PSF file. This does
not imply that said person wrote the music driver code.
volume
Relative volume of the PSF as a simple scale coefficient. 1.0 is the
default. It can by any real number, even negative.
length
fade
Length of the song, and the length of the ending fadeout.
These may be in one of three formats:
seconds.decimal
minutes:seconds.decimal
hours:minutes:seconds.decimal
The decmial portion may be omitted. Commas are also recognized as decimal
separators.
The following variables are reserved and should not be used:
- Anything starting with an underscore (_) character
These are reserved for information crucial to playing, i.e. the _lib tags
in MiniPSF files.
- filedir, filename, and fileext have special meanings in Highly
Experimental. While these variables may exist, they won't be usable in
title format strings.
-----------------------------------------------------------------------------
Depending on the version byte, the reserved and program sections are
interpreted differently. Some tags may also be interpreted differently.
Refer to the sections below.
-----------------------------------------------------------------------------
Version 0x01: Playstation (PSF1)
--------------------------------
Program section: PS-X EXE consumer-format executable file, including header.
Reserved section: Not used. May be ignored, removed, etc.
File extensions:
- psf, psf1 (self-contained program)
- minipsf, minipsf1 (program relying on extra library data)
- psflib, psf1lib (library for use with minipsf files)
In the case of a PSF1, the program section is an executable file for use with
the original Playstation console. It's responsible for initializing the SPU,
loading samples, setting up interrupts, etc. - anything a real program must
do. It runs at the shell level and has full access to kernel functions.
There are two important variations on PSF1: the MiniPSF and PSFLib which are
described later.
Uncompressed size of the executable must not exceed 2,033,664 bytes.
The executable must be in the standard consumer "PS-X EXE" format, which is
described below for reference.
First 0x800 bytes - header
Next N bytes - text section
Header format:
0x000 (8 bytes): ASCII "PS-X EXE"
0x010 (4 bytes): Initial PC, little-endian unsigned long
0x018 (4 bytes): Text section start address, little-endian unsigned long
0x01C (4 bytes): Text section size, little-endian unsigned long
0x030 (4 bytes): Initial SP ($29), little-endian unsigned long
0x04C: ASCII marker: "Sony Computer Entertainment Inc. for North America area"
(or similar for other regions)
Everything else is zero.
Text section should be a multiple of 2048 bytes.
-----------------------------------------------------------------------------
PSF1: MiniPSF and PSFLib
------------------------
MiniPSF files are regular PSF1 files which import data from one or more
PSFLib files residing in the same directory (for shared driver code, sound
banks, etc.)
PSFLib files are also regular PSF1 files. They can also recursively import
data from other PSFLib files.
This is done via tag variables called _lib, _lib2, _lib3, etc.
The proper way to load a minipsf is as follows:
- Load the EXE data - this becomes the current EXE
- Check for the presence of a "_lib" tag.
If present:
- RECURSIVELY load the EXE data from the given library file
(make sure to limit recursion to avoid crashing - I limit it to 10 levels)
- Make the _lib EXE the current one.
- We will use the initial PC/SP from the _lib EXE.
- Superimpose the originally loaded PSF EXE on top of the current EXE using
its text start address and text size.
- Check for the presence of "_libN" tags for N=2 and up (use "_lib%d")
- RECURSIVELY load and superimpose all these EXEs on top of the current
EXE. Do not modify the current PC/SP.
- Start at N=2. Stop at the first tag name that doesn't exist.
- (done)
EXEs must always be contiguous. When superimposing one EXE on top of
another, grow the target EXE start/end points as necessary and fill the
unused space with zeroes.
Filenames given in any _lib* tag are relative to the directory in which the
PSF file itself resides. Both forward and backward slashes should be
interpreted as path separators. For instance:
- if C:\Something\Demo.minipsf contains "_lib=Hello/Library.psflib"
- then the library is loaded from C:\Something\Hello\Library.psflib
Filenames may contain spaces within, but no leading or trailing spaces.
When determining whether a PSF1 file is a MiniPSF and will need additional
data, you should use the presence of _lib* tags to decide, rather than the
file extension. It's a MiniPSF if it includes a _lib or a _lib2.
-----------------------------------------------------------------------------
PSF1 Emulation Notes
--------------------
Though this isn't relevant to the actual format, the following information
may prove helpful. It pertains to PSF1 only.
The following are available in my emu0005 core:
- R3000 CPU
- Interrupts and syscalls
- 2MB RAM (mirrored throughout the first 8MB)
- 1KB scratchpad
- SPU
- DMA channel 4 (SPU)
- Root counters 0, 1, 2, VBlank IRQs
- All kernel functions
The following are not available and should not be used or accessed:
- Overflow exceptions
- Breakpoints
- GTE instructions
- GPU, CDROM, SIO, etc. - hardware unrelated to sound
- DMA channels other than 4
The following R3000 code sequence is detected as idle, and may be used to
conserve CPU time on the host side:
[jump or branch to the current line]
nop
-----------------------------------------------------------------------------
Version 0x02: Playstation 2 (PSF2)
----------------------------------
Program section: Not used. May be ignored, removed, etc.
Reserved section: Virtual filesystem.
File extensions:
- psf2 (self-contained filesystem)
- minipsf2 (filesystem relying on one or more psf2lib filesystems)
- psf2lib (filesystem providing extra data for minipsf2 filesystems)
A PSF2 file consists of a virtual filesystem located entirely in the Reserved
section. The Program section is unused. Filesystems may be combined using
the _lib, _lib2, ... tags, as with the MiniPSF and PSFLib formats.
Playing a PSF2 file begins by loading the "psf2.irx" IOP module from the
virtual filesystem. Loading and executing this module should perform all
necessary hardware setup and play the music.
PSF2 files are limited to playing sequenced music using the IOP and hardware
(SPU2) synthesis only. Software synthesis, generally performed by the EE, is
not considered.
-----------------------------------------------------------------------------
PSF2: Runtime environment
-------------------------
IOP modules in a PSF2 may link to the following libraries. The version
number may be no later than the listed version.
Name Ver. Name Ver. Name Ver.
-------------- -------------- --------------
dmacman 102 sifman 101 thmsgbx 101
excepman 101 ssbusc 101 thrdman 102
heaplib 101 stdio 103 thsemap 101
intrman 102 sysclib 103 thvpool 101
ioman 104 sysmem 101 timrman 103
loadcore 103 thbase 102 vblank 101
modload 106 thevent 101
sifcmd 101 thfpool 101
IOP modules should use the following technique to access files in the PSF2
virtual filesystem:
1. Take argv[0] and cut it off directly after the rightmost separator,
defined as either a forward slash, backward slash or colon (/ \ :).
This string becomes the "device prefix".
2. Append the name of the desired file to the device prefix.
3. Use the resulting string in standard calls such as open or LoadModule.
For instance, Highly Experimental may call psf2.irx with an argv[0] such as
"hefile:/psf2.irx". In this case, the device prefix is "hefile:/". You
would use the following call to open a file named "test.file":
fd = open("hefile:/test.file", O_RDONLY);
Different players or environments may use different device prefixes, so don't
always use "hefile:/".
IOP modules, as a rule, should not attempt any contact with hardware which is
unnecessary for music playing. This includes, but is not limited to: SIF,
CD/DVD, USB, iLink, ATA, pad, memory card, and network hardware. This
hardware may be emulated minimally but is not guaranteed to work.
IOP modules should use a minimal amount of memory, and make good use of the
virtual filesystem to keep large amounts of data rather than try to fit them
all in an IRX data section.
-----------------------------------------------------------------------------
PSF2: Virtual filesystem format
-------------------------------
The PSF2 virtual filesystem is a directory hierarchy with filenames of up
to 36 characters each. Filenames are case-insensitive and must consist
exclusively of characters in the ASCII 32-126 range, with the exception of
the forward slash, backslash, and colon (/, \, :) characters. The total
length of a path must be no longer than 255 bytes.
All quantities are stored in little-endian unsigned format. All offsets are
relative to the beginning of the Reserved section.
Starting at offset 0 is the root directory.
A directory has the following format:
- First 4 bytes: Number of directory entries (N)
- Next 48*N bytes: N directory entries
N may be zero to indicate the directory is empty.
The format of a directory entry is as follows:
- First 36 bytes: Filename. Must have nonzero length, and must be padded
with null (0x00) bytes. Does not have to be null-terminated if it's
exactly 36 characters.
- Next 4 bytes: Offset (O) of the file data or subdirectory
- Next 4 bytes: Uncompressed size (U)
- Next 4 bytes: Block size (B)
If U, B, and O are all zero, then the entry describes a zero-length file.
If U and B are zero and O is nonzero, the entry describes a subdirectory.
Otherwise, the file data is stored as a sequence of consecutive zlib
compress()-format blocks.
- First 4*X bytes: Size table. Each entry contains the size of a compressed
block.
X = (U + B - 1) / B;
- Remainder of file: compressed blocks where the uncompressed size must be
equal to B. The last block may have an uncompressed size smaller than B.
The offset of any subdirectory or file must be greater than the offset of its
directory entry. This provides for easier consistency checks.
-----------------------------------------------------------------------------
PSF2: MiniPSF2 and PSF2Lib
--------------------------
MiniPSF2 files are regular PSF2 files which import data from one or more
PSF2Lib files residing in the same directory (for shared driver code, sound
banks, etc.)
PSF2Lib files are also regular PSF2 files. They can also recursively import
data from other PSF2Lib files.
This is done via tag variables called _lib, _lib2, _lib3, etc.
The proper way to load a MiniPSF2 is as follows:
1. RECURSIVELY load the virtual filesystems from each PSF2 file named by a
library tag. The first tag is "_lib". The remaining tags are "_libN" for
N>=2 (use "_lib%d"). Stop at the first tag name that doesn't exist.
2. Load the virtual filesystem from the current PSF2 file.
When loading a new filesystem, any existing directory entries which have
conflicting filenames are overwritten. (The actual PSF2 files themselves
should not be overwritten, of course.)
Filenames given in any _lib* tag are relative to the directory in which the
PSF file itself resides. Both forward and backward slashes should be
interpreted as path separators. For instance:
- if C:\Something\Demo.minipsf2 contains "_lib=Hello/Library.psf2lib"
- then the library is loaded from C:\Something\Hello\Library.psf2lib
Filenames may contain spaces within, but no leading or trailing spaces.
When determining whether a PSF2 file is a MiniPSF2 and will need additional
data, you should use the presence of the _lib tags to decide, rather than the
file extension. It's a MiniPSF2 if it includes a "_lib" tag.
-----------------------------------------------------------------------------
Revision History
----------------
v1.3 (31 May 2003)
- Changed and finalized PSF2 format.
- Updated PSF1 emulation notes to reflect changes in the newest emulation
core
v1.2 (17 April 2003)
- Formalized handling of the version byte
- Details on how to handle future PSF variants
- All tags starting with an underscore (_) now reserved
- Various other clarifications
- Expanded PSF2 information, still tentative
v1.1 (11 March 2003)
- Some proposed information on PSF2
Update (24 January 2003)
- Added information on MiniPSF and PSFLib
Original version (?)
-----------------------------------------------------------------------------
Where to Find Neill Corlett
---------------------------
email: corlett@lfx.org
web: http://lfx.org/~corlett/
-----------------------------------------------------------------------------
Reference in New Issue View Git Blame Copy Permalink