🏠 Atari Jaguar Developer Reference ▸ CD-ROM Subsystem ▸ CD-ROM BIOS API

CD-ROM BIOS API

The Jaguar CD BIOS is the only supported way to access the CD subsystem. It provides hardware-transparent control of speed, data path, transfer, and audio.

Source: Jaguar CD-ROM developer manual (scanned), © Atari Corp. 1995, §2 “Jaguar CD-ROM BIOS” (pp. 5–14, printed). Routine addresses are defined in CD.INC.

Requirement: All access to the CD must be through the BIOS. The BIOS insulates your title from CD-vendor and data-transfer-mechanism changes.

Calling convention

  1. Load the documented values into the required registers.
  2. jsr CD_routine (a 68000 subroutine call) to the routine you want.
  3. Routine addresses come from CD.INC.

Each CD BIOS call may use up to 64 bytes of stack, so A7 must be set up correctly before any call.

In a retail Jaguar CD system the BIOS is present automatically; in a development setup it must be loaded into DRAM by your tooling before any CD BIOS call. Two BIOS revisions exist (2.x and 4.x): a Butch 1 CD interface chip can run only revision 2, while Butch 2 supports either — see CD-ROM Hardware.

Error handling

CD.INC defines a global error variable err_flag:

Proper error checking is mandatory. Failure to check and handle errors may block your product from final production approval. Always check err_flag after calls that set it, and implement a timeout so your program never waits forever for a call to return.

Error recovery for read operations (§2.6)

To retry a failed CD read (i.e. CD_ptr returns an error) while in double-speed mode:

  1. Switch to single speed with CD_mode.
  2. Switch back to double speed with CD_mode.
  3. Re-execute the CD_read.

This makes recovery reliable wherever recovery is actually possible (i.e. the disc isn’t physically damaged).

Command acknowledge (§2.5)

Several calls offer a choice: wait for an acknowledge that the command completed, or return immediately. The rule for “return immediately” mode: a CD_ack must be issued before any subsequent CD BIOS command. With CD_read in seek mode this delayed acknowledge is implied, so you must still CD_ack before the next CD BIOS command. Returning immediately lets you do other processing while the command runs.

Reading data (§2.4)

Data is normally read by calling one of three CD_init variants once, followed by any number of CD_read calls. With current hardware each CD_init loads GPU interrupt code that handles interrupts redirected from Jerry’s I²S interrupt.

Variant Speed Locates data? Registers Notes
CD_init average no none (non-interrupt) general use
CD_initf fastest (~30% faster) no more uses R18–R31
CD_initm slowest yes none (non-interrupt) partition-marker search + circular buffers

Warning: the CD BIOS GPU code cannot tell which interrupts truly came from Jerry. Never enable other interrupts in JINTCTRL while any CD_init handler is active, or they will be mistaken for CD interface interrupts.

Latency budget: at double speed these interrupts occur about every 90 µs; interrupt overhead reduces the usable max latency to ≈54 µs (less if the Object Processor is heavily used). No processor with priority over the GPU may hold the bus longer than this. 68000 vertical-blank handlers are a common offender — prefer doing object-list updates on the GPU, or keep the 68k handler tiny.

Using the DSP instead of the GPU: install a DSP I²S interrupt handler, call CD_jeri appropriately, and set SMODE to $14 (Boot ROM default is $15, restore it when done). This needs no CD_init. DSP transfers are subject to infrequent unreported data errors — checksum any data that must be perfect.

Red Book audio: use a simple handler that reads incoming CD data and writes it to the DACs (see INOUT.DAS in \JAGUAR\CDROM). Then call CD_read with the “Just Seek” bit set and the track’s time code; audio plays via your handler and no CD_init stores data.

Function reference (§2.7)

Conventions below mirror the manual: Input, Register Usage (registers the call clobbers), Returns, Purpose. “NADA”/”none” = nothing. Many calls set err_flag rather than returning a value in registers.

Calls:

Initialization & setup

CD_setup

CD_mode

CD_init

CD_initf

CD_initm

(CD BIOS Rev 3.0 and up)

Reading

CD_read

Behavior by CD_init variant in effect:

In effect Behavior
CD_init Reads into the buffer until its end. Request a time code 6 frames before the data you need; the start-of-data partition marker may be anywhere in the first 31 frames (72,912 bytes).
CD_initf Same as CD_init, faster.
CD_initm Scans incoming data for the partition marker in D1; data immediately past the marker is read into the buffer (auto-located in memory). Supports circular buffers (reads indefinitely until CD_uread). If the marker is never found, this call searches forever.
(none / DSP) If CD_jeri set the path to I²S ($14), your custom interrupt handler reads the data.

CD_uread

CD_ptr

CD_ack

Audio & playback control

CD_jeri

(Set the serial path to $14 for the DSP-handler read method described in Reading data.)

CD_mute

CD_umute

CD_osamp

CD_paus

CD_upaus

Transport & disc control

CD_spin

CD_stop

CD_switch

(CD BIOS Rev 4.0 and up)

Debug-only

CD_getoc

Debug only — never use on a bootable CD. The Boot ROM loads the TOC to $2C00 automatically.

First record (disc info):

Offset Meaning
+0 Unused, reserved (0)
+1 Unused, reserved (0)
+2 Minimum track number
+3 Maximum track number
+4 Total number of sessions
+5 Start of last lead-out time, absolute minutes
+6 Start of last lead-out time, absolute seconds
+7 Start of last lead-out time, absolute frames

Track records:

Offset Meaning
+0 Track # (non-zero)
+1 Absolute minutes (0..99), start of track
+2 Absolute seconds (0..59), start of track
+3 Absolute frames (0..74), start of track
+4 Minute # (0..99)
+5 Track duration minutes
+6 Track duration seconds
+7 Track duration frames

See also

◀ Prev: CD-ROM Subsystem Overview  ·  🏠 Home  ·  Next: Disc & Data Format ▶

Jump to: Architecture · Memory Map · Registers · Instructions · Glossary · CD-ROM