CD/Streaming Library (libcd)

Provides functions for controlling the CD-ROM drive and streaming data.

Overview

The CD/Streaming Library (libcd) consists of two separate libraries. The CD-ROM library controls the built-in CD-ROM drive and provides CD sound control and other services. The streaming library is a group of functions that continuously read real-time data such as movies, sounds or vertex data from high-capacity media.¹

A program that uses libcd links with libcd.lib and includes libcd.h. A program that uses only streaming may include libds.h instead.¹

This library is part of the run-time library that Sony distributed with the Psy-Q development tools.²

CD-ROM Sectors

Digital data is recorded on a CD-ROM in a spiral, as on a CD audio disc, and is handled in units called sectors. One second of data is divided into 75 sectors. Each sector is one of the following types:¹

An audio sector holds 44.1 kHz digital stereo audio, which is ordinary CD audio. The CdlPlay command plays it, and it cannot be read as user data. A data sector holds user data, and although its user area varies somewhat with the mode, the standard is 2048 bytes in the mode 1 format. An ADPCM sector, strictly a real-time or mode 2 form 2 sector, holds ADPCM compressed audio that plays in the same way as an audio sector.¹

Interleave

ADPCM compresses the audio of an audio sector to 1/4. ADPCM sectors are therefore placed on the disc every four sectors, so that the drive plays ADPCM without seeking for each sector. This arrangement is called interleaving. The remaining sectors can hold other data, which the drive reads while the audio plays. At double speed the ADPCM sectors are placed every 8 sectors.¹³⁴

Sectors of other ADPCM channels can be interleaved in the same way. For example, with 8 channels (A0 to A7) interleaved, the program switches between 8 channels of audio without seeking. The CdlSetfilter command selects the channel by the file and channel members of a CdlFILTER structure, and it is effective only when CdlModeSF is set in the mode.⁴⁵

Addressing

For compatibility with CD audio, a position on the disc is given by the track number, the index number and a time in minutes, seconds and sectors. A second has 75 sectors and a minute 60 seconds, and the first sector is at 00 minutes 02 seconds 00 sectors. A track signal is recorded at the start of each track, and the table of track positions is recorded at the start of the disc as the TOC (Table of Contents).³

To make position calculation easy, a data sector may also be addressed by the total number of sectors from 00:02:00, which is called the absolute sector. CdIntToPos() and CdPosToInt() convert between the two forms. Minute, second and sector are BCD values in the CdlLOC structure, in which each decimal digit has a 4-bit field, so decimal 60 is written 0x60.³⁶

File System

On a disc recorded in the ISO-9660 format, the position of a file can also be found through the file system. A CD-ROM is read-only, so the sectors of each file are arranged contiguously and a file is read from its start position alone. The disc therefore needs nothing like a FAT (File Allocation Table), and CdSearchFile() serves as the index of file names.³

CdSearchFile() searches by the absolute path of the file and stores the result in a CdlFILE structure. ISO-9660 positions are more accurate than TOC positions, which have only second resolution, but they cannot address audio sectors. CdGetToc() reads the TOC. The positions of all tracks and files are fixed before the disc is made, so these utilities serve mainly in development and debugging.⁵

Transfer Rate

The drive rotates the disc at normal speed, the same as an ordinary CD player, or at double speed. The transfer rates are therefore 150 KB/sec and 300 KB/sec, which means 75 sectors per second at normal speed and 150 sectors per second at double speed.³

Sector Buffer

The CD-ROM transfer rate is very slow compared with the 132 MB/sec main bus. The CD-ROM system therefore has a local memory for one sector of data, called the sector buffer. A read command places each sector in the sector buffer, where it stays valid until the next sector overwrites it. CdGetSector() transfers it to main memory at high speed.⁷⁸

Because the sector buffer is overwritten constantly, each sector must be transferred before the next arrives. Data for the frame buffer or the sound buffer goes through main memory first. The sector size depends on the mode but is usually 2 KB. In that case one CdGetSector() transfers at most 2 KB. CdGetSector() is a blocking function, so the transfer is complete when it returns.⁹

Sound Control

The CD-ROM subsystem outputs left and right audio for both CD audio and ADPCM. The audio goes to the SPU, where it is mixed with the SPU voices and output as one sound. Four attenuators control the CD-ROM audio output, and CdMix() sets them with a CdlATV structure.⁷

Primitive Commands

The lowest level of operation is to issue commands directly to the CD-ROM subsystem with CdControl(), which takes the command, a parameter and a result buffer. These low-level commands are called primitives:⁷¹⁰

B is blocking and N is non-blocking. CdlSetloc, CdlReadN, CdlReadS and CdlPlay take a CdlLOC start position, CdlSetfilter takes a CdlFILTER, CdlSetmode takes the mode byte and CdlGetTD takes a BCD track number. The other commands take NULL.¹⁰⁶

Every command returns 8 bytes, so the result buffer needs 8 bytes even when the result is only the status. A NULL result pointer suppresses the result. The first byte of the result of almost every command is the CD-ROM status:¹¹

The CdlNop command clears the shell open flag. To learn whether the cover is open now, the program therefore issues CdlNop at least once before it tests the flag.¹¹

Command Details

CdlSetloc sets the target position without moving the head, and CdlPlay, CdlReadN, CdlReadS, CdlSeekP and CdlSeekL use it when their own argument is NULL. CdlPlay seeks the target and starts CD-DA play. CdlReadN and CdlReadS seek the target and then read data sectors into the local buffer.¹²

CdlReadS does not retry after an error and is used for real-time reading such as streaming. CdlReadN retries for up to 8 seconds after a read error, and the read may still fail. Because a retry reads the sector again, CdlReadN cannot be used while ADPCM plays or where a fixed transfer rate is needed.¹²⁸

CdlSeekL and CdlSeekP seek the target and wait in pause status. A CD-ROM has a long seek time, so moving the head in advance speeds up access when the target is known. CdlSeekL is a logical seek, which reads the address in the header of a data sector and is therefore accurate, but it works only on data sectors. CdlSeekP is a physical seek, which uses the subcode and works on every sector type, including audio sectors without a header, but it is imprecise.¹²

CdlStandby waits with the spindle motor turning. CdlStop stops the motor and returns the head to its home position, and the next seek, read or play starts faster from standby than from stop. CdlPause halts read or play and waits at the position of the head.¹²

CdlSetmode sets the basic mode of the drive from the logical OR of the following bits, and CdlGetparam returns the current mode:¹³

CdlGetlocL returns the minute, second and sector of the data sector being read or the ADPCM being played, with the mode and the file and channel numbers, and it does not work while an audio sector plays. CdlGetlocP returns the track, the index, the time within the track and the absolute time from the subcode, so it works on every sector type. CdlGetTN returns the first and last track numbers, and CdlGetTD returns the TOC minute and second of a track, or the total time for track 0.¹³¹⁴

Command Synchronization

A command that takes time returns before its processing completes and is called a non-blocking command. A blocking command waits for completion. A non-blocking command continues in the background after CdControl() returns, and its result at that point is only temporary. CdSync() or a callback reports the real completion, and CdControlB() blocks for every command.¹⁴¹⁵

The execution status of a command is CdlNoIntr while it runs, CdlComplete when it has finished and the next command can be received, and CdlDiskError after an error. CdSync(0) waits until the status leaves CdlNoIntr and CdSync(1) returns at once. Commands are not queued, so while the status is CdlNoIntr a new command waits for the previous one to finish.¹⁵

CdSyncCallback() registers a function called when the status changes from CdlNoIntr to CdlComplete or CdlDiskError. For example, the callback of a CdlSeekL can issue CdlPlay, so the program is not blocked during the seek. CdControl() also blocks briefly until the subsystem acknowledges the command. CdControlF() returns without this wait, in which case CdSync() and polling must check for errors.¹⁶

Sector Ready

CdReady() reports the state of the sector buffer: CdlNoIntr while the sector is prepared, CdlDataReady when it is ready and CdlDiskError after an error. CdReady(0) blocks until the state leaves CdlNoIntr, and after it returns the state goes back to CdlNoIntr. CdReadyCallback() registers a function called when each sector is ready. This callback works at a lower level than CdReadSync() and CdReadCallback(), which report the end of a CdRead().⁸⁹

In double speed mode 300 sectors arrive each second, which leaves 1/300 second for each sector. A sector can therefore be skipped. A program that reads with the low-level functions therefore sets CdlModeSize1 to read the sector header. It then checks with CdGetSector() that the address in the first 12 bytes follows the address of the previous sector.¹⁷

The libcd ready callback takes two parameters, and the intr parameter must be checked, since the callback is also called when a read fails. A callback that is no longer needed is cleared at once, or a later CdlDataReady may call it unexpectedly. A command issued from a CdSyncCallback() function can call the same callback again and loop without end.¹⁷¹⁸

High-Level Interface

CdRead() combines CdlReadN and CdGetSector() and reads several sectors into main memory. It uses CdReadyCallback() internally, so that callback is not available while CdRead() runs. CdRead() is non-blocking. In non-blocking mode CdReadSync() returns the number of unread sectors, which may not decrease steadily because CdRead() retries internally.⁹⁴¹⁹

From library version 3.5, CdRead() checks the continuity of the sector headers, and a sector with an incorrect header is not read. Many errors in CdRead() therefore point to the recording format of the disc. CdReadFile() reads a file, CdReadExec() loads an executable file and CdPlay() plays CD-DA tracks.¹⁹²⁰

Report Mode

With CdlModeRept set during audio play, the status changes to CdlDataReady 10 times each second, and the result holds the following report:²¹

The report alternates between absolute and relative time. When it is relative, the highest bit of the frame byte is set, which is possible since frames run only from 0 to 74. The level takes 15 bits of two bytes, and the remaining bit gives the L or R channel. Report mode is turned on only while CD-DA plays, since during a data read its interrupts cannot be told from the data interrupts.²²

Events and Callbacks

At initialization a default callback is registered for each callback, and these callbacks deliver the following events:²¹

An event handler can therefore detect the end of a command or a read. However, a new callback releases the default callback and the events stop, and restoring the default is left to the application. The synchronization functions and callbacks are the following:²¹

Disc Notes

A disc must meet the CD-ROM XA specifications, so its data tracks come before its optional DA tracks. Autopause may fail with no gap or a very short gap between tracks, so the gaps are at least two seconds. A track jump within three minutes of the outer edge can throw the head off the disc. The outer three minutes are therefore not accessed and are usually filled with NULLs or with one continuous file such as an ending movie.²²²³¹⁷

The CD-ROM decoder has 32 KB of local memory, but its control software does not read ahead. A read must therefore start within 6.6 msec at double speed and 13.3 msec at normal speed after the data ready interrupt, or data may be skipped. FF and FR cannot be used while data is read, and opening the cover cancels the operation in progress.²³

A watchdog checks the state of the CD-ROM subsystem every few vertical syncs. The watchdog returns the drive to normal operation after any error. During CD-DA or CD-XA play it issues CdlNop and plays the track again when CdlStatPlay is off. During a read it restarts all reads when no CdlDataReady has come for a few seconds.¹⁸¹⁹

Swapping Discs

Before a disc is swapped, the CD subsystem is set to normal speed and may be stopped with CdlStop. A swap is detected with CdlNop. CdlStatShellOpen is always 1 while the cover is open and 1 only the first time after it closes, so a change from 1 to 0 means the disc may have changed. After the cover closes the subsystem reads the TOC, and only CdlNop and CdlGetTN may be issued until CdlGetTN succeeds.²⁰

A logical read then checks that the disc is a PlayStation disc. On another disc it returns a command error. A command error is a CdlDiskError with bit 0 of result[0] and bit 6 of result[1] set. The only recovery is to open the cover and mount the disc again. The debugging station accepts CD-Rs as PlayStation discs, while the PlayStation accepts only black discs.²⁴

Changing the Motor Speed

A command that moves the head issued right after a change in transfer speed loses control of the head, which can run to the mechanical stopper and make a strange sound. The program therefore waits at least three vertical syncs after a speed change before it issues CdlSeekP, CdlSeekL, CdlReadS, CdlReadN or CdlPlay. CdInit() sets the speed to normal.²⁴²⁵

Debug Messages

CdSetDebug() sets the debug level. Messages of level 0 are always printed, and messages of levels 1 and 2 when the debug level is 1 or 2. They include CD timeout, when no callback came from the subsystem in the expected time. They also include DiskError for a fatal error and CdRead: sector error, when the sector addresses were out of sequence and CdRead() retried from the first sector.²⁵²⁶²⁷

Streaming Library

The streaming library reads real-time data from high-capacity media in units called frames. A frame consists of one or more sectors, and each frame the library delivers is complete and contiguous without omissions. The library reads the CD-ROM and places the data in memory in units of time, while the user program displays the data and outputs the sound.²⁸

When sectors are read continuously, each frame must be processed in less time than one frame takes to read. Otherwise the data accumulates and the buffer overflows. The library solves this by discarding read data in whole frames when processing is late, so the data that remains is always complete. When a frame must not be discarded, the head can be moved back instead, but XA audio and streaming then cannot be used together.²⁸²⁹

The library stores the data in a ring buffer whose size is set in sectors by StSetRing(). StGetNext() returns the start of a frame when a whole frame is available, and StFreeRing() releases it so that new data can be read into it. The ring buffer has a header region of 32 bytes per sector and a data region of 2016 bytes per sector.²⁹³⁰

A sequence that fits in the ring buffer can be repeated from memory without the CD-ROM, when end_frame of StSetStream() or StSetEmulate() is 0. StCdInterrupt() handles the CD-ROM interrupts during streaming and makes 2 KB DMA transfers, which hold the bus for a long time. For 24-bit RGB movies it can therefore be called by the program at a suitable time when the StCdIntrFlag flag is set.³⁰³¹

Structures

In the tables below, Introduced is the run-time library version that added the item.³²

libcd has the following structures:³²

Functions

libcd has the following functions:³³

References