Technical Note DV22

CD-ROM Driver Calls

CONTENTS Topics Driver Summary Control Call Descriptions Status Call Descriptions References Change History Downloadables

This Technical Note discusses the public interface to the Apple CD-ROM driver. This information supersedes the "Macintosh CD-ROM Device Driver" chapter of the AppleCD SC Developer's Guide. If you're writing special purpose application software that needs to access the audio or data portions of a CD-ROM directly, this Note will be of interest to you. [Apr 06 1999]

Topics

• Status & Control calls for the Apple CD-ROM Driver.
• Differences between the various Apple CD-ROM drives.

This Technote describes version 4.0.X through version 5.2.X of the Apple CD-ROM driver. Previous versions of the Apple CD-ROM driver are documented in the AppleCD SC Developer's Guide.

Version 5.2.X History: Version 5.2 adds support for ATAPI CD-ROM drives.

Version 5.1.X History: Version 5.1 adds support for the AppleCD 600, support for multi-session CDs, support for an independent icon for CD-Extra, support for asynchronous calls, and support for playing audio track lists with 5 new calls: SetTrackList, GetTrackList, GetTrackIndex, SetPlayMode, and GetPlayMode.

Version 5.0.X History: Version 5.0 adds support for the AppleCD 300 Plus and three new calls: DriverGestalt, ReturnDeviceIdent, and GetCDFeatures. Version 5.0 is also the first version to support asynchronous I/O using SCSI Manager 4.3. The ReadMCN and ReadISRC calls did not return the correct information in version 4.0.X when using an AppleCD 300. Those two calls now work in version 5.0, but the format of the returned parameters has changed for all drives. Version 5.0.1 fixes the following problems: an empty tray can be ejected using the Eject control call; when third-party SCSI accelerator cards are installed, the driver now sees the CD-ROM drives, and the WhoIsThere call works correctly; and DriverGestalt will no longer modify csParam[0].

Version 4.0.X History: Version 4.0 of the Apple CD-ROM extension was the first version to support dual-speed operation and multiple-session Photo CDs on the AppleCD 300. Version 4.0 also supports single-session Photo CDs on all other Apple CD-ROM drives. Version 4.0 had problems with certain CD-ROMs that used encryption technology to restrict access to files. When the customer was given a decryption key to gain access to a file, the file would not always appear in the Finder. Version 4.0.1 was produced to fix this problem. However, this version was tested only on the Macintosh IIvx and Performa 600. Version 4.0.2 was tested on all Macintosh computers, and a few changes were made to ensure compatibility across the Macintosh product line. Version 4.0.2 corrected problems when sending audio commands using block addressing only. Audio calls using minute-second-frame addressing continued to work correctly.

Audio compact discs and CD-ROM discs conform to two standards, called the Red Book and the Yellow Book. The Red book specifies audio standards; the Yellow book specifies additional standards for CD-ROM. "Red Book" is the common name of the "Compact Disc Digital Audio Standard" standard, CEI IEC 908. When a disc conforms to the Red Book standard, it will usually have "digital audio" printed below the "disc" logo. Most music CDs conform to this standard. "Yellow Book" is the standard for CD-ROM, ISO 10149. When a disc conforms to the Yellow Book, the words "data storage" usually are printed beneath the "disc" logo.

There are several other standards usually associated with CD-ROM technology: the "Green Book" standard defines CD-I (Compact Disc Interactive); "Orange Book" defines write-once compact discs; and "Blue Book" defines CD-Extra (Compact Disc Digital Audio plus Data).

You can get the Red Book and Yellow Book from:

ANSI
Attn: Sales
1430 Broadway
New York, NY 10018
(212) 642-4900

Red Book: CEI IEC 908
Yellow Book: ISO 10149:1989

You can get the Green Book from:

American CD-I Association
11111 Santa Monica, Suite 750
Los Angeles, CA 90025
(310) 444-6619

The other standards are available only to Sony/Philips licensees. Contact Sony or Philips for licensing details.

Beginning with version 4.0 of the Apple CD-ROM software, several new Gestalt selectors are installed by Foreign File Access and various file system translators. Each selector is a version number, as defined in Inside Macintosh volume VI, page VI-3-34. The list includes:

To call the Macintosh driver, you need to understand the possible addressing formats for audio blocks on a CD. The three addressing formats are:

1. logical block
2. absolute minute, second, and frame
3. track number

An audio CD contains up to 74 minutes of sound. (By decreasing the inter-track gap and other tricks, you can put more than 74 minutes of sound on a CD. Doing this is only marginally within the standard. Such CDs may not be playable on all drives.) These minutes are divided into 60 seconds. Each second contains 75 frames. There is a two-second lead-in area at the beginning of the disc that contains table of contents information about the tracks on that CD. You can have a maximum of 99 tracks on a CD.

You can address sound down to the frame level, that is, down to the 1/75th of a second. You can address sound by specifying an absolute block number (e.g., start playing at absolute block 1,234,567 from the start of the disc), or by absolute minute, second, and frame number (e.g., start playing at minute 42, second 30, frame 15 on the disc), or by logical track number (e.g., start playing at track 2).

The driver requires that the logical track number or absolute minute-second-frame numbers be specified in BCD (e.g., the decimal number 12 is stored as hex 0x0012, not as 0x000C).

Optical Positioning Type

Many calls require an optical pick-up positioning type. This is used to specify what kind of address is being used in other parameters of a given call. There are four different optical pick-up positioning types:

Track Control Field

Many calls return a control field. This field describes the format of the current track, and has the following values:

Audio Play Mode

Many calls require a play mode. This field describes how to play the audio track, and this field has the following values:

*Not available on AppleCD 300 Plus

In the absolute minute-second-frame address, the ranges are as follows:

Making a High-Level Driver Call

The Apple CD-ROM driver does not conform to the normal design of a driver. In particular, the Apple CD-ROM driver returns some additional status information in some of its control calls, and expects to receive some additional control information in some of its status calls. The high-level control and status calls weren't designed with this in mind. The glue for control does not fill in the csParamPtr field with the results of any changes due to a control call, and the glue for status does not use the csParam field passed in as part of the call it creates on the stack. Do not use high-level control and status calls to access the Apple CD-ROM driver; use only the PBControl and PBStatus calls.

Making a Low-Level Driver Call

The low-level calls require that you pass in two parameters: a pointer to a parameter block, and a flag indicating synchronous or asynchronous completion. You must fill in the parameter block yourself, and may find it easier to define your own custom parameter block variants for the various calls. Here's some example MPW C code to get audio status:

#include <Devices.h>

short gDrvRefNum;         // set up somewhere else

// this is a custom version of the CntrlParam parameter
// block defined on page II-181 and II-183 or in
// Devices.h

#if PRAGMA_STRUCT_ALIGN
    #pragma options align=mac68k
#endif
typedef struct {
    QElemPtr qLink;
    int qType;
    int ioTrap;
    Ptr ioCmdAddr;
    ProcPtr ioCompletion;
    OsErr ioResult;
    StringPtr ioNamePtr;
    int ioVRefNum;
    int ioRefNum;
    int csCode;
    // Everything below this replaces: short csParam[11]
    unsigned char status;
    unsigned char play;
    unsigned char control;
    unsigned char minute;
    unsigned char second;
    unsigned char frame;
    char unused[16]; // for the rest
} CDCntrlParam;
#if PRAGMA_STRUCT_ALIGN
    #pragma options align=reset
#endif

// GetAudioStuff
//     requires one input, the driver reference number that we
//     got by calling PBOpen().
//     fills in six parameters with appropriate information
//     from the driver call.
//     We're assuming that only one CD player is attached.
//     To generalize this code, fill in the ioVRefNum dynamically.

OSErr GetAudioStuff(status, play, control, minute, second, frame)
unsigned char *status, *play, *control, *minute, *second, *frame;
{
    OSErr result;
    CDCntrlParam myPB;
    myPB.ioCompletion = 0;
    myPB.ioVRefNum = 1; // assuming only 1 volume
    myPB.ioRefNum = gDrvRefNum; // determined elsewhere
    myPB.csCode = 107;
    result = PBControl(&myPB, false);
    if (result == noErr)
    {
    *status = myPB.status;
    *play = myPB.play;
    *control = myPB.control;
    *minute = myPB.minute;
    *second = myPB.second;
    *frame = myPB.frame;
    }
    return(result);
}

Back to top

Driver Summary

Name

.AppleCD

Conventions

• Each call description will follow this format:

• Function Name

A detailed description of the device driver function is given here.

• Input Parameters:

Relevant csCode and csParam[] requirements are listed here.

• Output Produced:

Any returned data is listed here.

• Status Return Codes:

A list of possible status return codes this function can return are listed here.

• Reserved fields are assumed to be filled with zeros, to ensure compatibility with future releases of the driver.
• Several status return codes are generic to any driver call and will not be repeated within each call description. Suggested possible meanings for these error codes are given in Inside Macintosh. The generic status return codes are:

controlErr
badUnitErr
notOpenErr
ioErr
wPrErr
paramErr
offLinErr


• All control calls not listed below will return controlErr.

Supported Control Calls

Standard Driver Calls

Back to top

Control Call Descriptions

KillIO

The purpose of this call is to allow the interruption of all asynchronous device driver operations. This call is not supported and returns noErr if called.

Input Parameters:

VerifyTheDisc

The purpose of this call is to ensure the validity of the data on the disc. Since CD-ROMs cannot be changed (they are read-only, as the name implies), when this control call is made, the CD-ROM driver will return noErr (as long as a disc is mounted). If no disc is mounted, the CD-ROM driver will return offLinErr.

Input Parameters:

FormatTheDisc

The purpose of this call is to format and initialize the CD-ROM disc for use in the Macintosh. However, a CD-ROM cannot be modified after it has been pressed, so this command always returns a writErr status code.

Input Parameters:

EjectTheDisc

The purpose of this call is to cause a disc eject at a specified device ID. First, a Prevent/Allow Medium Removal command is issued to reactivate the external Eject button on the front panel of the CD-ROM drive. Then, the specified device is sent an "eject" command to eject the disc. Next, the dNeedTime flag in the specified device ID's DCE is set so that new disc insertions will be periodically checked for (see the accRun control call for more details). Finally, the drive queue entry associated with this drive is marked as being Off-Line and Ejected.

Input Parameters:

GetDriveIcon

The purpose of this call is to return ICN#-style icon data and name string that is typically displayed by the Startup Disk Control Panel module. The drive icon is the same as the media icon in this driver. There is no true drive icon because there is no way of determining if an internal or external drive should represented. Starting on version 5.1, the driver returns a special icon when a CD-Extra is present in the drive, and a generic icon when any other type of CD is present. See Figure 1 for a picture of the icons returned.

Input Parameters:

Output Produced:

Status Return Codes:

GetMediaIcon

The purpose of this call is to return ICN#-style icon data and name string that is displayed whenever the disc media is shown. This icon can be seen on the desktop or when the "Get Info" (Cmd-I) command from the Finder is executed under System 7. See Figure 2 for a picture of the icons returned.

Input Parameters:

Output Produced:

Status Return Codes:

Figure 2 : Icons returned by GetDriveIcon control call

DriveInfo

The purpose of this call is to return information describing drive characteristics for the specified device ID. The values to be returned are defined in Inside Macintosh, volume V, pages 470-471. The 32-bit value returned by the Apple CD-ROM driver is $00000B01. Bits 7-0 equal to 0x01 means that this is an "unspecified" drive. Bit 8 equal to 1 means that this is an "external" drive (this will be set even if the drive is actually mounted internally). Bit 9 equal to 1 means that this is a SCSI drive (this will be set even if the drive is actually an ATAPI drive). Bit 10 equal to 0 means that this is a removable media drive. Bit 11 equal to 1 means that this is a "secondary" drive. All other bits are reserved.

Input Parameters:

Output Produced:

Status Return Codes:

accRun

The purpose of this call is to perform operations required by the driver on an "as-needed" basis.

There is no need for an application to issue this call. Almost all Macintosh programs make a call to the MacOS routine SystemTask(), and one of the functions of that routine is occasionally to make some CPU time available to all devices that request it by executing its accRun call. (See Inside Macintosh, Volume II, pg. 189 for a further discussion of accRun). This is done by setting the dNeedTime flag in the Device Control Entry (DCE) for a given device.

Since the CD-ROM device is a removable media device and does not generate interrupts when a disc is inserted, the only way to detect disc insertion is by occasionally polling all devices known by the driver to be "empty" (disc is not inserted or is still off-line). So, the main function of the accRun control call is testing for disc insertions.

In addition, during the Macintosh boot process, if the driver is installed before the System file is read in, the driver cannot install its custom CD-ROM Disk Switch subroutine. When the System file is read in and installed, it will overwrite the low-memory global that defines the address of the standard Disk Switch routine. So, the installation of our custom Disk Switch routine is held off until the first invocation of SystemTask(). At that time, the System file has already been loaded and the standard Disk Switch routine has been initialized. The accRun control call also handles track play lists.

Input Parameters:

Status Return Codes:

SetPowerMode

The purpose of this call is to select the power mode of a CD-ROM drive. The currently available power modes are:

• pmActive
• pmStandby
• pmIdle
• pmSleep

Input Parameters:

Status Return Codes:

ModifyPostEvent

The purpose of this call is to allow an application to modify the driver's behavior when non-HFS discs are inserted into the CD-ROM drive. The default action of the driver is to post a disc-inserted event for all discs that are inserted into the CD-ROM drive, regardless of whether or not the disc actually contains valid partition information and HFS file system. There may be some reason why the driver should not post the disc-inserted event and this call allows that "feature" to be turned off. When this feature is turned off for a specified device ID, it will stay off until it is reactivated via another call to ModifyPostEvent, or until the machine is restarted.

Input Parameters:

Status Return Codes:

ChangeBlockSize

The purpose of this call is to allow an application to modify the "block size" the drive is currently using to read data. The standard HFS file system block size is 512 bytes/block. Applications and file system translators dealing with non-HFS file systems may require other block sizes to read their data correctly.

The supported block sizes are 512, 2048, 2056, 2336, 2340, 2352, 2646, and 2647 bytes. The AppleCD SC cannot handle block sizes of 2056, 2352, 2646, and 2647 bytes. The AppleCD SC Plus cannot handle block sizes of 2352, 2646, and 2647 bytes.

The following tables show the type of data that is returned for each of the valid block sizes:

CD-ROM Mode 1 Data Format:

CD-ROM Mode 2 Data Format:

CD-ROM Mode 2 Form 1 Data Format (CD-XA or CD-I):

CD-ROM Mode 2 Form 2 Data Format (CD-XA or CD-I):

Input Parameters:

Status Return Codes:

SetUserEject

The purpose of this call is to allow the user to enable/disable the physical Eject button on the front of the CD-ROM device while a disc is in the drive.

The CD-ROM device does not generate an interrupt when a disc is inserted or ejected, so if the button is left active we have no way of accurately knowing whether or not there is really a disc in the drive. The MacOS assumes it has final say over when an ejectable disc is actually ejected, and issues an EjectTheDisc control call when it wishes to eject the disc.

This call provides a method to disable/enable the manual eject button for the drive on the specified device ID. Internal variables are maintained for each device ID that reflect the current state of the manual eject button. If the button is enabled, the driver sets the dNeedTime flag in the appropriate DCE, telling the driver to periodically poll the device to see whether a disc has been ejected, or inserted. This is the only way the driver has to ensure the validity of its global variables in this situation. When a disc is inserted, the button setting reverts back to disabled.

Input Parameters:

Status Return Codes:

SetPollFreq

The purpose of this call is to allow an application to specify a polling frequency (in Macintosh time ticks) different from the driver default value (120). This polling frequency is the value used for determining how often the accRun control call is issued, as well as the polling frequency for a VBL task initiated during the execution of the driver's custom Disk Switch routine.

Input Parameters:

Status Return Codes:

Quiescence

The purpose of this call is to allow the user to enable/disable the driver quiescent mode. This is used when an application wishes to communicate directly to the drive, in effect bypassing the CD driver. In this case the procedure for communicate directly with the drive, is as follows:

1. Wake up the drive using the SetPowerMode command.
   
   
2. Place the driver into quiescent mode.

During quiescent mode, the driver will be completely inactive. Note that if the driver is not put into quiescent mode immediately after it awakens the drive, the driver will during the first accRun put that empty drive back to sleep.

3. After the application is done talkimg to the drive, remove the driver from quiescent mode.

Input Parameters:

Status Return Codes:

ReadTOC

The purpose of this call is to allow an application to receive various types of Table Of Contents (TOC) data from the drive. There are six varieties of the ReadTOC call:

For transfer types 1, 2, and 5, the TOC information is returned directly in the caller's csParam[0-10] array. For types 3, 4, and 6, the caller is required to specify a buffer to place the information into. In the case of a type 4 transfer, the buffer must be 512 bytes long.

Input Parameters:

Output Produced:

For Type 1:

For Type 2:

For Type 3:

The user must specify a return buffer address and the size of the buffer. The buffer is filled with 4-byte entries for each track in the requested range. Each entry is of the form:

Note: no entries will be returned for data tracks on CD-I discs.

For Type 4 (Not available on AppleCD SC):

The user must specify a return buffer address. The buffer must be 512 bytes long, and is filled with the entire table of contents, which is returned in the form:

Each five-byte entry is of the form:

Note: this option is not valid for the AppleCD SC drive.

Type 5 (Not available on AppleCD SC, APPLECD SC Plus, and AppleCD 150):

For Type 6 (Not available on AppleCD SC, AppleCD SC Plus, and AppleCD 150):

The user must specify a return buffer address and the size of the buffer. The buffer is filled with a 4-byte header and 8-byte entries for each Q-subcode entry in the requested range. The first three entries are for points A0, A1, and A2, and are followed by the track entries for that session. After that, the Q-subcode entries are sorted in ascending order using the ADR field and within each ADR group by ascending order of the POINT field. This pattern is repeated for each session on the disc.

The 4-byte header is of the form:

Each TOC entry is of the form:

The values come directly from the disc and will be in either BCD or hexadecimal format, depending on the field. The session number, ADR/Control and POINT fields are in hexadecimal. All other fields are in BCD. For more information on the format of the TOC, please refer to the "Yellow Book" specification for CD-ROM discs, ISO 10149.

In some early CD-300 units, the values for Entries 2 and 3 are swapped. This is due to a firmware bug, which was corrected on later drives. You should always OR the two values together to always receive the proper value.

Status Return Codes:

ReadTheQSubcode

The purpose of this call is to allow an application access to the Q-subcode information for the current track. The current track is the track that the optical pickup is currently over on a disc.

Input Parameters:

Output Produced:

Status Return Codes:

ReadHeader

The purpose of this call is to allow the user/application access to the header information for a specified logical block. This information concerns the absolute AMIN-ASEC-AFRAME address of a given logical block (the absolute running time from the beginning of the disc) and the CD-ROM Data Mode of that logical block. If a requested block is within an audio track (CD-DA) of the disc, a paramErr will be returned.

Input Parameters:

Output Produced:

Status Return Codes:

AudioTrackSearch

The purpose of this call is to position the optical pick-up at the specified audio address. In addition, you can also tell the drive either to start to play at the given address, or to pause at this address until an AudioPlay command is executed and in what Play Mode it should output the audio information.

Input Parameters:

Status Return Codes:

AudioPlay

The purpose of this call is to position the optical pick-up at the specified audio address and begin playback of the audio at that address. It can be similar to the AudioTrackSearch command that automatically begins playing at the specified Search Address (see the documentation on the AudioTrackSearch call for more detail). However, this command can also be used to specify a "Stop Address."

The proper way to use the AudioPlay-related commands is:

If no stop address is specified before issuing the actual play command, the current active stop address in the drive may be lower than the address at which we are trying to play audio, causing the drive to return an error when the play command is issued.

This model should always be followed irregardless of the audio play mode to be used, even when playing track lists.

Input Parameters:

Status Return Codes