forked from cebix/psximager
-
Notifications
You must be signed in to change notification settings - Fork 0
Tools for dumping and mastering PlayStation 1 ("PSX") CD-ROM images
License
cetygamer/psximager
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
PSXImager V2.0 ============== PSXImager is a collection of tools for dumping and (pre-)mastering PlayStation 1 ("PSX") CD-ROM images. It consists of three tools: * psxrip Dumps the contents of the data track of a binary CD image ("BIN/CUE") to a directory tree plus a "catalog" file containing filesystem metadata. * psxbuild The inverse of psxrip; takes a catalog file and a directory tree to produce a binary CD image which can be burned to a CD medium. * psxinject Replaces the contents of a file inside a binary CD image. What sets PSXImager apart from standard ISO 9660 imaging tools is that PSXImager handles images in the CD-ROM XA format, which is what the PlayStation 1 uses. CD-ROM XA, defined by Sony and Philips, is an extension to the "Yellow Book" and ISO 9660 standards, and also used by Video and Photo CDs. The main extensions of XA are: - CD-ROM sectors contain an additional 8 bytes of "subheader" data for storing information related to audio/video files (data type, codec and channel information, etc.). - Directory entries contain more attributes, such as Unix-style owner/group IDs and permissions, - Most importantly, XA allows "Form 2" files with 2324 data bytes per sector (as opposed to the regular 2048 bytes) which are recorded in special CD-ROM sectors ("Mode 2, Form 2"). This allows storing more data on a CD (up to ~740MB) at the cost of having no error correction for this data. Form 2 files are primarily used for audio/video data, in particular the FMVs of most PlayStation 1 games. "Red Book" CD-DA audio tracks are not handled by PSXImager. PSXImager is based on code from the GNU VCDImager project and uses the libcdio and libvcdinfo libraries for most of its work. psxrip ------ Usage: psxrip [OPTION...] <input>[.bin/cue] [<output_dir>] -l, --lbns Write LBNs to catalog file -t, --lbn-table Print LBN table and exit -v, --verbose Be verbose -V, --version Display version information and exit -?, --help Show this help message Reads the data track of the given input CD image and dumps the filesystem contents to a directory together with a "catalog" file which specifies the directory structure and contains additional metadata which is not in the filesystem dump. The input CD image must be in raw ("MODE2/2352") format. Only the first data track is dumped, additional data and audio tracks are ignored. All files in the CD filesystem are dumped, preserving the original directory tree structure and (uppercase) naming. If no output directory is specified, the basename of the input CD image is used. The catalog file will have the name "<output_dir>.cat". The format of the catalog file is explained in the section "Catalog File Syntax", below. Additionally, psxrip will dump the system area (the first 16 sectors of the CD image) to a file named "<output_dir>.sys". On the PlayStation 1, the system area is used for storing licensing information. With the option '-l', psxrip will also write the start sector numbers (LBNs) of all files and directories to the catalog file. When invoked with the option '-t', psxrip will not dump the filesystem of the image but instead print a table which lists - the start LBN (hex) - the number of sectors used (hex) - the file or directory size (hex) - the item type ('d' = directory, 'f' = regular file, 'x' = XA Form 2 file, 'a' = CD-DA audio file) - the path name of the item for each file and directory in the filesystem. This is useful for ROM hacking because many PlayStation 1 games access files by sector number instead of going through the filesystem. Usage example: A CD image in the required format can be produced from a PlayStation 1 game CD with the cdrdao tool as follows: cdrdao read-cd --read-raw --datafile GAME.bin GAME.toc toc2cue GAME.toc GAME.cue The filesystem of the produced GAME.bin/cue can then be dumped with: psxrip GAME.cue This will create a directory named "GAME" which contains the complete filesystem tree of the CD, plus a "GAME.cat" catalog file and a "GAME.sys" file with a dump of the system area of the CD. These files can be used with psxbuild to recreate a CD image of the game. psxbuild -------- Usage: psxbuild [OPTION...] <input>[.cat] [<output>[.bin]] -c, --cuefile Create a .cue file -v, --verbose Be verbose -V, --version Display version information and exit -?, --help Show this help message Creates a raw mode BIN/CUE CD image from a catalog file and a directory tree holding the contents of the CD filesystem. The directory structure, the files to be included in the image, and additional metadata are controlled by the specified input catalog file. The format of the catalog file is explained in the section "Catalog File Syntax", below. Although it is possible to build a CD image from scratch by providing a hand-written catalog file, it is recommended to dump a PlayStation 1 CD using psxrip and use the produced catalog file as a template. The files and directories to be included in the image must be placed in a directory which has the same name as the basename of the catalog file. The files will be written to the image in the order they appear in in the catalog. Files which are present in the directory but not specified in the catalog will be ignored. Usage example: Given a catalog file named "GAME.cat" and a directory named "GAME" which holds the filesystem tree of the CD, a CD image can be built with: psxbuild -c GAME This will create the two files "GAME.bin" and "GAME.cue" which contain the CD image. They can either directly be used with a PlayStation 1 emulator, or the image be written to a CD using a standard CD burning application such as Brasero. Note 1: A CD produced in this way will not be bootable on original PlayStation hardware because the PlayStation checks a signature on the CD which is not reproducible using off-the-shelf CD burners. However, there are hardware modifications ("Modchips") available for the PlayStation which disable this check. Note 2: Rebuilding a CD image which has been dumped with psxrip is not guaranteed to preserve the start sector numbers (LBNs) of files. Since many PlayStation 1 games access their data files directly via sector numbers instead of going through the filesystem, a game whose image has been rebuilt with psxbuild may crash or not work correctly. In this case it will be necessary to adapt the game code to the changed LBNs. psxinject --------- Usage: psxinject [OPTION...] <input>[.bin/cue] <repl_file_path> <new_file> -v, --verbose Be verbose -V, --version Display version information and exit -?, --help Show this help message Replaces the contents of a file inside a standard or raw mode BIN/CUE image with a file from the local filesystem, preserving the file's name, attributes, and start sector. This is useful when patching individual files without having to rebuild the entire CD image. The new file must not require a greater number of sectors in the image, i.e. shrinking a file is allowed, but extending it beyond sector boundaries is not. If the new file is significantly larger than the existing file the image must be rebuilt in its entirety using psxrip/psxbuild. Usage example: To replace the file with the path GFX/INTRO.TIM in the CD image GAME.bin/cue with the contents of the local file "new_intro.tim", use: psxinject GAME.cue GFX/INTRO.TIM new_intro.tim Catalog File Syntax ------------------- The catalog file is a plain-text file which specifies the directory structure and additional metadata of a PlayStation 1 CD image. It is produced by psxrip when dumping a CD image, and read by psxbuild to control the creation of a CD image. The syntax of the catalog file is line-based. Extra spaces and empty lines are ignored but each data item and each item opening or closing a section must be on a line of its own. A catalog file consists of three sections: The system area section, the volume section, and the root directory section. The first two sections are optional. * System area section: The system area section has the following syntax: system_area { file "<file>" } <file> specifies the path name of the file which holds the data of the system area (first 16 sectors) of the CD image. It can have a maximum size of 32 KiB. Although this section is optional, the system area of a PlayStation 1 CD must contain special, region-specific licensing information in order for the CD to be bootable on a PlayStation. This data is not included with PSXImager. * Volume section: This section specifies metadata, most of which is stored in the ISO 9660 primary volume descriptor of the CD image. It has the following syntax: volume { system_id '[' <string> ']' volume_id '[' <string> ']' volume_set_id '[' <string> ']' publisher_id '[' <string> ']' preparer_id '[' <string> ']' application_id '[' <string> ']' copyright_file_id '[' <string> ']' abstract_file_id '[' <string> ']' bibliographic_file_id '[' <string> ']' creation_date <YYYY-MM-DD hh:mm:ss.xx ofs> modification_date <YYYY-MM-DD hh:mm:ss.xx ofs> expiration_date <YYYY-MM-DD hh:mm:ss.xx ofs> effective_data <YYYY-MM-DD hh:mm:ss.xx ofs> default_uid <integer> default_gid <integer> } All items in this section are optional. Unspecified items will be filled in with default (usually empty) values by psxbuild. Few (if any) PlayStation 1 games actually use the information defined in the volume section. The meaning of the *_id and *_date items, and their possible values, are defined in the ISO 9660 and ECMA-119 standards. The convention for PlayStation 1 games is to set the system_id to "PLAYSTATION" and the volume_id to the name of the game in caps. The volume_id is also the name the CD will appear under when mounted on a PC. In the four *_date items, the "xx" part specifies hundreds of seconds, while the "ofs" part specifies the offset from GMT in fifteen-minute units, ranging from -48 (west) to 52 (east). The default_uid and default_gid items specify the UID and GID attributes (0..65535) of all files and directories on the CD when creating an image with psxbuild. These two items are not written by psxrip. * Root directory section: The root directory section recursively defines the entire filesystem tree of the CD image. It has the follwing syntax: dir { file <file1> [@<lbn>] xafile <file2> [@<lbn>] ... dir <dir1> [@<lbn>] { file <file3> [@<lbn>] xafile <file4> [@<lbn>] ... dir <dir2> [@<lbn>] { ... } } ... } A directory section may specify file items as well subdirectory sections, which in turn may contain files and subdirectories themselves. Each "file" item specifies an ordinary data file (2048 bytes/sector), while an "xafile" item specifies an XA Form 2 file holding 2336 bytes/sector (the 8-byte XA subheader followed by 2324 bytes of data followed by 4 bytes of error detection (EDC) info per sector). An "xafile" can also interleave Form 1 sectors which are stored in "raw" (2336 bytes/sector) format (8-byte XA subheader, 2048 data bytes, 4 bytes EDC, 276 bytes ECC). psxbuild recalculates the EDC/ECC data of XA files when writing them to the output image. The file and directory names should follow ISO 9660 level 1 conventions (8.3 characters, only uppercase letters, digits, and underscores). The name of the root directory must be empty. File versions (like ";1") are not supported. The "@<lbn>" part of file and directory items is optional. If present, it specifies the start sector number (LBN) of the file's or directory's extent. When creating a CD image, LBN specifications must appear in ascending order in the catalog; it is not possible to place an item at a lower start sector than the previous item, or to overlap items. When psxbuild detects this case it will print a warning message and move the item to the next free sector. There is no way of specifying additional per-file or per-directory metadata. Permissions are set to standard values and file creation dates are set to the volume creation date by psxbuild. Example catalog file: system_area { file "license.sys" } volume { system_id [PLAYSTATION] volume_id [MYGAME] publisher_id [CEBIX] creation_date 2014-03-15 14:46:30.00 4 } dir { file SYSTEM.CNF file MYGAME.EXE dir GFX { file INTRO.TIM xafile MOVIE.STR @1000 } } Together with a corresponding directory tree of files: $ tree . |-- MYGAME | |-- GFX | | |-- INTRO.TIM | | `-- MOVIE.STR | |-- MYGAME.EXE | `-- SYSTEM.CNF |-- MYGAME.cat `-- license.sys a CD image can be built with: $ psxbuild -c MYGAME Reading catalog file "MYGAME.cat"... Reading filesystem from directory "MYGAME"... Image file written to "MYGAME.bin" Cue file written to "MYGAME.cue" The root directory of the produced image will contain the files "SYSTEM.CNF" and "MYGAME.EXE", plus the directory "GFX" with its two files "INTRO.TIM" and "MOVIE.STR", the latter being a Form 2 file. The "MOVIE.STR" file will start at sector 1000, if possible. Author ------ Christian Bauer www.cebix.net
About
Tools for dumping and mastering PlayStation 1 ("PSX") CD-ROM images
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published
Languages
- C++ 71.8%
- M4 27.7%
- Other 0.5%