path: root/usr/src/man/man7i/cdio.7i

'\" te
.\"  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CDIO 7I "Oct 4, 2001"
.SH NAME
cdio \- CD-ROM control operations
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/cdio.h>\fR
.fi

.SH DESCRIPTION
.sp
.LP
The set of \fBioctl\fR(2) commands described below are used to perform audio
and \fBCD-ROM\fR specific operations. Basic to these \fBcdio\fR ioctl requests
are the definitions in \fB<sys/cdio.h>\fR\&.
.sp
.LP
Several \fBCD-ROM\fR specific commands can report addresses either in \fBLBA\fR
(Logical Block Address) format or in \fBMSF\fR (Minute, Second, Frame) format.
The \fBREAD HEADER\fR, \fBREAD SUBCHANNEL\fR, and \fBREAD TABLE OF CONTENTS\fR
commands have this feature.
.sp
.LP
\fBLBA\fR format represents the logical block address for the \fBCD-ROM\fR
absolute address field or for the offset from the beginning of the current
track expressed as a number of logical blocks in a \fBCD-ROM\fR track relative
address field. \fBMSF\fR format represents the physical address written on
\fBCD-ROM\fR discs, expressed as a sector count relative to either the
beginning of the medium or the beginning of the current track.
.SH IOCTLS
.sp
.LP
The following \fBI/O\fR controls do not have any additional data passed into or
received from them.
.sp
.ne 2
.na
\fB\fBCDROMSTART\fR\fR
.ad
.RS 18n
This \fBioctl()\fR spins up the disc and seeks to the last address requested.
.RE

.sp
.ne 2
.na
\fB\fBCDROMSTOP\fR\fR
.ad
.RS 18n
This \fBioctl()\fR spins down the disc.
.RE

.sp
.ne 2
.na
\fB\fBCDROMPAUSE\fR\fR
.ad
.RS 18n
This \fBioctl()\fR pauses the current audio play operation.
.RE

.sp
.ne 2
.na
\fB\fBCDROMRESUME\fR\fR
.ad
.RS 18n
This \fBioctl()\fR resumes the paused audio play operation.
.RE

.sp
.ne 2
.na
\fB\fBCDROMEJECT\fR\fR
.ad
.RS 18n
This \fBioctl()\fR ejects the caddy with the disc.
.RE

.sp
.ne 2
.na
\fB\fBCDROMCLOSETRAY\fR\fR
.ad
.RS 18n
This \fBioctl()\fR closes the caddy with the disc.
.RE

.sp
.LP
The following \fBI/O\fR controls require a pointer to the structure for that
\fBioctl()\fR, with data being passed into the \fBioctl()\fR.
.sp
.ne 2
.na
\fB\fBCDROMPLAYMSF\fR\fR
.ad
.RS 19n
This \fBioctl()\fR command requests the drive to output the audio signals at
the specified starting address and continue the audio play until the specified
ending address is detected. The address is in \fBMSF\fR format. The third
argument of this \fBioctl()\fR call is a pointer to the type \fBstruct
cdrom_msf\fR.
.sp
.in +2
.nf
/*
 * definition of play audio msf structure
 */
struct cdrom_msf {
	unsigned char	cdmsf_min0;	/* starting minute*/
	unsigned char	cdmsf_sec0;	/* starting second*/
	unsigned char	cdmsf_frame0;	/*starting frame*/
	unsigned char	cdmsf_min1;	/* ending minute */
	unsigned char	cdmsf_sec1;	/* ending second */
	unsigned char	cdmsf_frame1;	/* ending frame */
};
.fi
.in -2

The \fBCDROMREADTOCENTRY\fR ioctl request may be used to obtain the start time
for a track. An approximation of the finish time can be obtained by using the
\fBCDROMREADTOCENTRY\fR ioctl request to retrieve the start time of the track
following the current track.
.sp
The leadout track is the next consecutive track after the last audio track.
Hence, the start time of the leadout track may be used as the effective finish
time of the  last audio track.
.RE

.sp
.ne 2
.na
\fB\fBCDROMPLAYTRKIND\fR\fR
.ad
.RS 19n
This \fBioctl()\fR command is similar to  \fBCDROMPLAYMSF\fR. The starting and
ending address is in track/index format. The third argument of the
\fBioctl()\fR call is a pointer to the type \fBstruct cdrom_ti\fR.
.sp
.in +2
.nf
/*
 * definition of play audio track/index structure
 */
struct cdrom_ti {
	unsigned char	cdti_trk0;	/* starting track*/
	unsigned char	cdti_ind0;	/* starting index*/
	unsigned char	cdti_trk1;	/* ending track */
	unsigned char	cdti_ind1;	/* ending index */
};
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBCDROMVOLCTRL\fR\fR
.ad
.RS 19n
This \fBioctl()\fR command controls the audio output level. The \fBSCSI\fR
command allows the control of up to four channels. The current implementation
of the supported \fBCD-ROM\fR drive only uses channel 0 and channel 1. The
valid values of volume control are between 0x00 and 0xFF, with a value of 0xFF
indicating maximum volume. The third argument of the \fBioctl()\fR call is a
pointer to \fBstruct\fR \fBcdrom_volctrl\fR which contains the output volume
values.
.sp
.in +2
.nf
/*
 * definition of audio volume control structure
 */
struct cdrom_volctrl {
	unsigned char	channel0;
	unsigned char	channel1;
	unsigned char	channel2;
	unsigned char	channel3;
};
.fi
.in -2

.RE

.sp
.LP
The following \fBI/O\fR controls take a pointer that will have data returned to
the user program from the \fBCD-ROM\fR driver.
.sp
.ne 2
.na
\fB\fBCDROMREADTOCHDR\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command returns the header of the  table of contents (TOC).
The header consists of the starting tracking number and the ending track number
of the disc. These two numbers are returned through a pointer of  \fBstruct
cdrom_tochdr\fR. While the disc can start at any number, all tracks between the
first and last tracks are in contiguous ascending order.
.sp
.in +2
.nf
/*
 * definition of read toc header structure
 */
struct cdrom_tochdr {
	unsigned char	cdth_trk0;	/* starting track*/
	unsigned char	cdth_trk1;	/* ending track*/
};
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBCDROMREADTOCENTRY\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command returns the information of a specified track. The
third argument of the function call is a pointer to the type \fBstruct
cdrom_tocentry\fR. The caller needs to supply the track number and the address
format. This command will return a 4-bit  \fBadr\fR field, a 4-bit \fBctrl\fR
field, the starting address in \fBMSF\fR format or \fBLBA\fR format, and the
data mode if the track is a data track. The \fBctrl\fR field specifies whether
the track is data or audio.
.sp
.in +2
.nf
/*
 * definition of read toc entry structure
 */
struct cdrom_tocentry {
	unsigned char  cdte_track;
	unsigned char  cdte_adr   :4;
	unsigned char  cdte_ctrl   :4;
	unsigned char  cdte_format;
	union {
		struct {
			unsigned char  minute;
			unsigned char  second;
			unsigned char  frame;
		} msf;
		int	lba;
	} cdte_addr;
	unsigned char  cdte_datamode;
};
.fi
.in -2

To get the information from the leadout track, the following value is
appropriate for the \fBcdte_track\fR field:
.sp
.ne 2
.na
\fB\fBCDROM_LEADOUT\fR\fR
.ad
.RS 17n
Leadout track
.RE

To get the information from the data track, the following value is appropriate
for the \fBcdte_ctrl\fR field:
.sp
.ne 2
.na
\fB\fBCDROM_DATA_TRACK\fR\fR
.ad
.RS 20n
Data track
.RE

The following values are appropriate for the  \fBcdte_format\fR field:
.sp
.ne 2
.na
\fB\fBCDROM_LBA\fR\fR
.ad
.RS 13n
\fBLBA\fR format
.RE

.sp
.ne 2
.na
\fB\fBCDROM_MSF\fR\fR
.ad
.RS 13n
\fBMSF\fR format
.RE

.RE

.sp
.ne 2
.na
\fB\fBCDROMSUBCHNL\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command reads the Q sub-channel data of the current block.
The subchannel data includes track number, index number, absolute \fBCD-ROM\fR
address, track relative  \fBCD-ROM\fR address, control data and audio status.
All information is returned through a pointer to  \fBstruct cdrom_subchnl\fR.
The caller needs to supply the address format for the returned address.
.sp
.in +2
.nf
struct cdrom_subchnl {
	unsigned char	cdsc_format;
	unsigned char	cdsc_audiostatus;
	unsigned char	cdsc_adr:	4;
	unsigned char	cdsc_ctrl:	4;
	unsigned char	cdsc_trk;
	unsigned char	cdsc_ind;
	union {
		struct {
			unsigned char 	minute;
			unsigned char 	second;
			unsigned char 	frame;
		} msf;
		int	lba;
	} cdsc_absaddr;
	union {
		struct {
			unsigned char 	minute;
			unsigned char 	second;
			unsigned char 	frame;
		} msf;
		int	lba;
	} cdsc_reladdr;
};
.fi
.in -2

The following values are valid for the audio status field returned from
\fBREAD\fR \fBSUBCHANNEL\fR command:
.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_INVALID\fR\fR
.ad
.RS 25n
Audio status not supported.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_PLAY\fR\fR
.ad
.RS 25n
Audio play operation in progress.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_PAUSED\fR\fR
.ad
.RS 25n
Audio play operation paused.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_COMPLETED\fR\fR
.ad
.RS 25n
Audio play successfully completed.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_ERROR\fR\fR
.ad
.RS 25n
Audio play stopped due to error.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_AUDIO_NO_STATUS\fR\fR
.ad
.RS 25n
No current audio status to return.
.RE

.RE

.sp
.ne 2
.na
\fB\fBCDROMREADOFFSET\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command returns the absolute \fBCD-ROM\fR address of the
first track in the last session of a Multi-Session \fBCD-ROM\fR. The third
argument of the \fBioctl()\fR call is a pointer to an \fBint\fR.
.RE

.sp
.ne 2
.na
\fB\fBCDROMCDDA\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command returns the \fBCD-DA\fR data or the subcode data.
The third argument of the \fBioctl()\fR call is a pointer to the type \fBstruct
cdrom_cdda\fR. In addition to allocating memory and supplying its address, the
caller needs to supply the starting address of the data, the transfer length in
terms of the number of blocks to be transferred, and the subcode options. The
caller also needs to issue the \fBCDROMREADTOCENTRY\fR \fBioctl()\fR to find
out which tracks contain \fBCD-DA\fR data before issuing this \fBioctl()\fR.
.sp
.in +2
.nf
/*
 * Definition of CD-DA structure
 */
struct cdrom_cdda {
	unsigned int	cdda_addr;
	unsigned int	cdda_length;
	caddr_t		cdda_data;
	unsigned char	cdda_subcode;
};
.fi
.in -2

\fBcdda_addr\fR signifies the starting logical block address.
.sp
\fBcdda_length\fR signifies the transfer length in blocks. The length of the
block depends on the \fBcdda_subcode\fR selection, which is explained below.
.sp
To get the subcode information related to  \fBCD-DA\fR data, the following
values are appropriate for the  \fBcdda_subcode\fR field:
.sp
.ne 2
.na
\fB\fBCDROM_DA_NO_SUBCODE\fR\fR
.ad
.RS 25n
\fBCD-DA\fR data with no subcode.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_DA_SUBQ\fR\fR
.ad
.RS 25n
\fBCD-DA\fR data with sub Q code.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_DA_ALL_SUBCODE\fR\fR
.ad
.RS 25n
\fBCD-DA\fR data with all subcode.
.RE

.sp
.ne 2
.na
\fB\fBCDROM_DA_SUBCODE_ONLY\fR\fR
.ad
.RS 25n
All subcode only.
.RE

To allocate the memory related to  \fBCD-DA\fR and/or subcode data, the
following values are appropriate for each data  block transferred:
.sp
.ne 2
.na
\fB\fBCD-DA\fR data with no subcode\fR
.ad
.sp .6
.RS 4n
2352 bytes
.RE

.sp
.ne 2
.na
\fB\fBCD-DA\fR data with sub Q code\fR
.ad
.sp .6
.RS 4n
2368 bytes
.RE

.sp
.ne 2
.na
\fB\fBCD-DA\fR data with all subcode\fR
.ad
.sp .6
.RS 4n
2448 bytes
.RE

.sp
.ne 2
.na
\fBAll subcode only\fR
.ad
.sp .6
.RS 4n
96 bytes
.RE

.RE

.sp
.ne 2
.na
\fB\fBCDROMCDXA\fR\fR
.ad
.RS 21n
This \fBioctl()\fR command returns the \fBCD-ROM\fR \fBXA\fR (CD-ROM Extended
Architecture) data according to  \fBCD-ROM\fR \fBXA\fR format. The third
argument of the \fBioctl()\fR call is a pointer to the type \fBstruct
cdrom_cdxa\fR. In addition to allocating memory and supplying its address, the
caller needs  to supply the starting address of the data, the transfer length
in terms of number of blocks, and the format. The caller also needs to issue
the \fBCDROMREADTOCENTRY\fR \fBioctl()\fR to find out which tracks contain
\fBCD-ROM\fR \fBXA\fR data before issuing this \fBioctl()\fR.
.sp
.in +2
.nf
/*
 * Definition of CD-ROM XA structure
 */
struct cdrom_cdxa {
	unsigned int	cdxa_addr;
	unsigned int	cdxa_length;
	caddr_t		cdxa_data;
	unsigned char	cdxa_format;
};
.fi
.in -2

To get the proper  \fBCD-ROM\fR \fBXA\fR data, the following values are
appropriate for the  \fBcdxa_format\fR field:
.sp
.ne 2
.na
\fB\fBCDROM_XA_DATA\fR\fR
.ad
.RS 25n
\fBCD-ROM\fR \fBXA\fR data only
.RE

.sp
.ne 2
.na
\fB\fBCDROM_XA_SECTOR_DATA\fR\fR
.ad
.RS 25n
\fBCD-ROM\fR \fBXA\fR all sector data
.RE

.sp
.ne 2
.na
\fB\fBCDROM_XA_DATA_W_ERROR\fR\fR
.ad
.RS 25n
\fBCD-ROM\fR \fBXA\fR data with error flags data
.RE

To allocate the memory related to  \fBCD-ROM\fR \fBXA\fR format, the following
values are appropriate for each data  block transferred:
.sp
.ne 2
.na
\fB\fBCD-ROM XA\fR data only\fR
.ad
.sp .6
.RS 4n
2048 bytes
.RE

.sp
.ne 2
.na
\fB\fBCD-ROM XA\fR all sector data\fR
.ad
.sp .6
.RS 4n
2352 bytes
.RE

.sp
.ne 2
.na
\fB\fBCD-ROM XA\fR data with error flags data\fR
.ad
.sp .6
.RS 4n
2646 bytes
.RE

.RE

.sp
.ne 2
.na
\fB\fBCDROMSUBCODE\fR\fR
.ad
.RS 21n
This  \fBioctl()\fR command returns raw subcode data (subcodes P ~ W are
described in  the "Red Book," see \fBSEE ALSO\fR) to the initiator while the
target is  playing audio. The third argument of the  \fBioctl()\fR call is a
pointer to the type \fBstruct cdrom_subcode\fR. The caller needs to supply the
transfer length in terms of number of blocks and allocate memory  for subcode
data. The memory allocated should be a multiple of 96  bytes depending on the
transfer length.
.sp
.in +2
.nf
/*
 * Definition of subcode structure
 */
struct cdrom_subcode {
	unsigned int	cdsc_length;
	caddr_t		cdsc_addr;
};
.fi
.in -2

.RE

.sp
.LP
The next group of \fBI/O\fR controls get and set various \fBCD-ROM\fR drive
parameters.
.sp
.ne 2
.na
\fB\fBCDROMGBLKMODE\fR\fR
.ad
.RS 18n
This  \fBioctl()\fR command returns the current block size used by the
\fBCD-ROM\fR drive.  The third argument of the \fBioctl()\fR call is a pointer
to an integer.
.RE

.sp
.ne 2
.na
\fB\fBCDROMSBLKMODE\fR\fR
.ad
.RS 18n
This  \fBioctl()\fR command requests the \fBCD-ROM\fR drive to change from the
current block size to the requested block size. The third argument of the
\fBioctl()\fR call is an integer which contains the requested block size.
.sp
This \fBioctl()\fR command operates in exclusive-use mode only. The caller must
ensure  that no other processes can operate on the same  \fBCD-ROM\fR device
before issuing this  \fBioctl()\fR. \fBread\fR(2) behavior subsequent to this
\fBioctl()\fR remains the same: the caller is still constrained to read the raw
device on block boundaries and in block multiples.
.sp
To set the proper block size, the following values are appropriate:
.sp
.ne 2
.na
\fB\fBCDROM_BLK_512\fR\fR
.ad
.RS 18n
512 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_1024\fR\fR
.ad
.RS 18n
1024 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2048\fR\fR
.ad
.RS 18n
2048 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2056\fR\fR
.ad
.RS 18n
2056 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2336\fR\fR
.ad
.RS 18n
2336 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2340\fR\fR
.ad
.RS 18n
2340 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2352\fR\fR
.ad
.RS 18n
2352 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2368\fR\fR
.ad
.RS 18n
2368 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2448\fR\fR
.ad
.RS 18n
2448 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2646\fR\fR
.ad
.RS 18n
2646 bytes
.RE

.sp
.ne 2
.na
\fB\fBCDROM_BLK_2647\fR\fR
.ad
.RS 18n
2647 bytes
.RE

.RE

.sp
.ne 2
.na
\fB\fBCDROMGDRVSPEED\fR\fR
.ad
.RS 18n
This \fBioctl()\fR command returns the current \fBCD-ROM\fR drive speed. The
third argument of the  \fBioctl()\fR call is a pointer to an integer.
.RE

.sp
.ne 2
.na
\fB\fBCDROMSDRVSPEED\fR\fR
.ad
.RS 18n
This  \fBioctl()\fR command requests the \fBCD-ROM\fR drive to change the
current drive speed to the requested drive speed. This speed setting is only
applicable when reading data areas. The third argument of the  \fBioctl()\fR is
an integer which contains the requested drive speed.
.sp
To set the  \fBCD-ROM\fR drive to the proper speed, the following values are
appropriate:
.sp
.ne 2
.na
\fB\fBCDROM_NORMAL_SPEED\fR\fR
.ad
.RS 23n
150k/second
.RE

.sp
.ne 2
.na
\fB\fBCDROM_DOUBLE_SPEED\fR\fR
.ad
.RS 23n
300k/second
.RE

.sp
.ne 2
.na
\fB\fBCDROM_QUAD_SPEED\fR\fR
.ad
.RS 23n
600k/second
.RE

.sp
.ne 2
.na
\fB\fBCDROM_MAXIMUM_SPEED\fR\fR
.ad
.RS 23n
300k/second (2x drive) 600k/second (4x drive)
.RE

Note that these numbers are only accurate when reading 2048 byte blocks. The
\fBCD-ROM\fR drive will automatically switch to normal speed when playing audio
tracks  and will switch back to the speed setting when accessing data.
.RE

.SH SEE ALSO
.sp
.LP
\fBioctl\fR(2), \fBread\fR(2)
.sp
.LP
N. V. Phillips and Sony Corporation, \fISystem Description Compact Disc Digital
Audio\fR, ("Red Book").
.sp
.LP
N. V. Phillips and Sony Corporation, \fISystem Description of Compact Disc Read
Only Memory\fR, ("Yellow Book").
.sp
.LP
N. V. Phillips, Microsoft, and Sony Corporation, \fISystem Description CD-ROM
XA\fR, 1991.
.sp
.LP
\fIVolume and File Structure of CD-ROM for Information Interchange\fR, ISO
9660:1988(E).
.sp
.LP
\fISCSI-2\fR \fIStandard,\fR \fIdocument\fR \fIX3T9.2/86-109\fR
.sp
.LP
\fISCSI Multimedia Commands, Version 2 (MMC-2)\fR
.SH NOTES
.sp
.LP
The  \fBCDROMCDDA\fR, \fBCDROMCDXA\fR, \fBCDROMSUBCODE\fR,
\fBCDROMGDRVSPEED\fR, \fBCDROMSDRVSPEED\fR, and some of the block sizes in
\fBCDROMSBLKMODE\fR are designed for new Sun-supported \fBCD-ROM\fR drives and
might not work on some of the older \fBCD-ROM\fR drives.
.sp
.LP
CDROMCDDA, CDROMCDXA and CDROMSUBCODE will return error if the transfer length
exceeds valid limits as determined appropriate. Example: for MMC-2 drives,
length can not exceed 3 bytes (i.e. 0xffffff).  The same restriction is
enforced for older, pre-MMC-2 drives, as no limit was published for these older
drives (and 3 bytes is reasonable for all media). Note that enforcing this
limit does not imply that values passed in below this limit will actually be
applicable for each and every piece of media.
.sp
.LP
The interface to this device is preliminary and subject to change in future
releases. Programs should be written in  a modular fashion so that future
changes can be easily incorporated.