Ioctl Requests cdio(7I)
NAME
cdio - CD-ROM control operations
SYNOPSIS
#include
DESCRIPTION
The set of ioctl(2) commands described below are used to
perform audio and CD-ROM specific operations. Basic to these
cdio ioctl requests are the definitions in .
Several CD-ROM specific commands can report addresses either
in LBA (Logical Block Address) format or in MSF (Minute,
Second, Frame) format. The READ HEADER, READ SUBCHANEL, and
READ TABLE OF CONTENTS commands have this feature.
LBA format represents the logical block address for the CD-
ROM absolute address field or for the offset from the begin-
ning of the current track expressed as a number of logical
blocks in a CD-ROM track relative address field. MSF format
represents the physical address written on CD-ROM discs,
expressed as a sector count relative to either the beginning
of the medium or the beginning of the current track.
IOCTLS
The following I/O controls do not have any additional data
passed into or received from them.
CDROMSTART This ioctl() spins up the disc and seeks
to the last address requested.
CDROMSTOP This ioctl() spins down the disc.
CDROMPAUSE This ioctl() pauses the current audio play
operation.
CDROMRESUME This ioctl() resumes the paused audio play
operation.
CDROMEJECT This ioctl() ejects the caddy with the
disc.
CDROMCLOSETRAY This ioctl() closes the caddy with the
disc.
SunOS 5.11 Last change: 4 Oct 2001 1
Ioctl Requests cdio(7I)
The following I/O controls require a pointer to the struc-
ture for that ioctl(), with data being passed into the
ioctl().
CDROMPLAYMSF This ioctl() command requests the drive
to output the audio signals at the speci-
fied starting address and continue the
audio play until the specified ending
address is detected. The address is in
MSF format. The third argument of this
ioctl() call is a pointer to the type
struct cdrommsf.
/*
* definition of play audio msf structure
*/
struct cdrommsf {
unsigned char cdmsfmin0; /* starting minute*/
unsigned char cdmsfsec0; /* starting second*/
unsigned char cdmsfframe0; /*starting frame*/
unsigned char cdmsfmin1; /* ending minute */
unsigned char cdmsfsec1; /* ending second */
unsigned char cdmsfframe1; /* ending frame */
};
The CDROMREADTOCENTRY 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 CDROM-
READTOCENTRY ioctl request to retrieve
the start time of the track following the
current track.
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.
CDROMPLAYTRKIND This ioctl() command is similar to
CDROMPLAYMSF. The starting and ending
address is in track/index format. The
third argument of the ioctl() call is a
pointer to the type struct cdromti.
/*
* definition of play audio track/index structure
*/
struct cdromti {
unsigned char cdtitrk0; /* starting track*/
unsigned char cdtiind0; /* starting index*/
SunOS 5.11 Last change: 4 Oct 2001 2
Ioctl Requests cdio(7I)
unsigned char cdtitrk1; /* ending track */
unsigned char cdtiind1; /* ending index */
};
CDROMVOLCTRL This ioctl() command controls the audio
output level. The SCSI command allows the
control of up to four channels. The
current implementation of the supported
CD-ROM drive only uses channel 0 and
channel 1. The valid values of volume
control are between 0x00 and 0xF, with a
value of 0xF indicating maximum volume.
The third argument of the ioctl() call is
a pointer to struct cdromvolctrl which
contains the output volume values.
/*
* definition of audio volume control structure
*/
struct cdromvolctrl {
unsigned char channel0;
unsigned char channel1;
unsigned char channel2;
unsigned char channel3;
};
The following I/O controls take a pointer that will have
data returned to the user program from the CD-ROM driver.
CDROMREADTOCHDR This ioctl() command returns the header
of the table of contents (TOC). The
header consists of the starting track-
ing number and the ending track number
of the disc. These two numbers are
returned through a pointer of struct
cdromtochdr. While the disc can start
at any number, all tracks between the
first and last tracks are in contiguous
ascending order.
/*
* definition of read toc header structure
*/
struct cdromtochdr {
unsigned char cdthtrk0; /* starting track*/
unsigned char cdthtrk1; /* ending track*/
};
SunOS 5.11 Last change: 4 Oct 2001 3
Ioctl Requests cdio(7I)
CDROMREADTOCENTRY This ioctl() command returns the infor-
mation of a specified track. The third
argument of the function call is a
pointer to the type struct
cdromtocentry. The caller needs to
supply the track number and the address
format. This command will return a 4-
bit adr field, a 4-bit ctrl field, the
starting address in MSF format or LBA
format, and the data mode if the track
is a data track. The ctrl field speci-
fies whether the track is data or
audio.
/*
* definition of read toc entry structure
*/
struct cdromtocentry {
unsigned char cdtetrack;
unsigned char cdteadr :4;
unsigned char cdtectrl :4;
unsigned char cdteformat;
union {
struct {
unsigned char minute;
unsigned char second;
unsigned char frame;
} msf;
int lba;
} cdteaddr;
unsigned char cdtedatamode;
};
To get the information from the leadout
track, the following value is appropri-
ate for the cdtetrack field:
CDROMLEADOUT Leadout track
To get the information from the data
track, the following value is appropri-
ate for the cdtectrl field:
CDROMDATATRACK Data track
The following values are appropriate
for the cdteformat field:
CDROMLBA LBA format
SunOS 5.11 Last change: 4 Oct 2001 4
Ioctl Requests cdio(7I)
CDROMSF MSF format
CDROMSUBCHNL This ioctl() command reads the Q sub-
channel data of the current block. The
subchannel data includes track number,
index number, absolute CD-ROM address,
track relative CD-ROM address, control
data and audio status. All information
is returned through a pointer to
struct cdromsubchnl. The caller needs
to supply the address format for the
returned address.
struct cdromsubchnl {
unsigned char cdscformat;
unsigned char cdscaudiostatus;
unsigned char cdscadr: 4;
unsigned char cdscctrl: 4;
unsigned char cdsctrk;
unsigned char cdscind;
union {
struct {
unsigned char minute;
unsigned char second;
unsigned char frame;
} msf;
int lba;
} cdscabsaddr;
union {
struct {
unsigned char minute;
unsigned char second;
unsigned char frame;
} msf;
int lba;
} cdscreladdr;
};
The following values are valid for the
audio status field returned from READ
SUBCHANEL command:
CDROMAUDIOINVALID Audio status
not supported.
CDROMAUDIOPLAY Audio play
operation in
progress.
SunOS 5.11 Last change: 4 Oct 2001 5
Ioctl Requests cdio(7I)
CDROMAUDIOPAUSED Audio play
operation
paused.
CDROMAUDIOCOMPLETED Audio play
successfully
completed.
CDROMAUDIOEROR Audio play
stopped due to
error.
CDROMAUDIONOSTATUS No current
audio status
to return.
CDROMREADOFSET This ioctl() command returns the abso-
lute CD-ROM address of the first track
in the last session of a Multi-Session
CD-ROM. The third argument of the
ioctl() call is a pointer to an int.
CDROMCDA This ioctl() command returns the CD-DA
data or the subcode data. The third
argument of the ioctl() call is a
pointer to the type struct cdromcdda.
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 CDROMREADTOCEN-
TRY ioctl() to find out which tracks
contain CD-DA data before issuing this
ioctl().
/*
* Definition of CD-DA structure
*/
struct cdromcdda {
unsigned int cddaaddr;
unsigned int cddalength;
caddrt cddadata;
unsigned char cddasubcode;
};
SunOS 5.11 Last change: 4 Oct 2001 6
Ioctl Requests cdio(7I)
cddaaddr signifies the starting logi-
cal block address.
cddalength signifies the transfer
length in blocks. The length of the
block depends on the cddasubcode
selection, which is explained below.
To get the subcode information related
to CD-DA data, the following values
are appropriate for the cddasubcode
field:
CDROMDANOSUBCODE CD-DA data
with no sub-
code.
CDROMDASUBQ CD-DA data
with sub Q
code.
CDROMDALSUBCODE CD-DA data
with all sub-
code.
CDROMDASUBCODEONLY All subcode
only.
To allocate the memory related to CD-
DA and/or subcode data, the following
values are appropriate for each data
block transferred:
CD-DA data with no subcode
2352 bytes
CD-DA data with sub Q code
2368 bytes
CD-DA data with all subcode
2448 bytes
SunOS 5.11 Last change: 4 Oct 2001 7
Ioctl Requests cdio(7I)
All subcode only
96 bytes
CDROMCDXA This ioctl() command returns the CD-ROM
XA (CD-ROM Extended Architecture) data
according to CD-ROM XA format. The
third argument of the ioctl() call is a
pointer to the type struct cdromcdxa.
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 CDROM-
READTOCENTRY ioctl() to find out which
tracks contain CD-ROM XA data before
issuing this ioctl().
/*
* Definition of CD-ROM XA structure
*/
struct cdromcdxa {
unsigned int cdxaaddr;
unsigned int cdxalength;
caddrt cdxadata;
unsigned char cdxaformat;
};
To get the proper CD-ROM XA data, the
following values are appropriate for
the cdxaformat field:
CDROMXADATA CD-ROM XA data
only
CDROMXASECTORDATA CD-ROM XA all
sector data
CDROMXADATAWEROR CD-ROM XA data
with error
flags data
To allocate the memory related to CD-
ROM XA format, the following values are
appropriate for each data block
transferred:
SunOS 5.11 Last change: 4 Oct 2001 8
Ioctl Requests cdio(7I)
CD-ROM XA data only
2048 bytes
CD-ROM XA all sector data
2352 bytes
CD-ROM XA data with error flags data
2646 bytes
CDROMSUBCODE This ioctl() command returns raw sub-
code data (subcodes P ~ W are described
in the "Red Book," see SE ALSO) to
the initiator while the target is
playing audio. The third argument of
the ioctl() call is a pointer to the
type struct cdromsubcode. 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.
/*
* Definition of subcode structure
*/
struct cdromsubcode {
unsigned int cdsclength;
caddrt cdscaddr;
};
The next group of I/O controls get and set various CD-ROM
drive parameters.
CDROMGBLKMODE This ioctl() command returns the current
block size used by the CD-ROM drive. The
third argument of the ioctl() call is a
pointer to an integer.
CDROMSBLKMODE This ioctl() command requests the CD-ROM
drive to change from the current block
size to the requested block size. The
SunOS 5.11 Last change: 4 Oct 2001 9
Ioctl Requests cdio(7I)
third argument of the ioctl() call is an
integer which contains the requested block
size.
This ioctl() command operates in
exclusive-use mode only. The caller must
ensure that no other processes can
operate on the same CD-ROM device before
issuing this ioctl(). read(2) behavior
subsequent to this ioctl() remains the
same: the caller is still constrained to
read the raw device on block boundaries
and in block multiples.
To set the proper block size, the follow-
ing values are appropriate:
CDROMBLK512 512 bytes
CDROMBLK1024 1024 bytes
CDROMBLK2048 2048 bytes
CDROMBLK2056 2056 bytes
CDROMBLK2336 2336 bytes
CDROMBLK2340 2340 bytes
CDROMBLK2352 2352 bytes
CDROMBLK2368 2368 bytes
CDROMBLK2448 2448 bytes
CDROMBLK2646 2646 bytes
CDROMBLK2647 2647 bytes
SunOS 5.11 Last change: 4 Oct 2001 10
Ioctl Requests cdio(7I)
CDROMGDRVSPED This ioctl() command returns the current
CD-ROM drive speed. The third argument of
the ioctl() call is a pointer to an
integer.
CDROMSDRVSPED This ioctl() command requests the CD-ROM
drive to change the current drive speed to
the requested drive speed. This speed set-
ting is only applicable when reading data
areas. The third argument of the ioctl()
is an integer which contains the requested
drive speed.
To set the CD-ROM drive to the proper
speed, the following values are appropri-
ate:
CDROMNORMALSPED 150k/second
CDROMDOUBLESPED 300k/second
CDROMQUADSPED 600k/second
CDROMAXIMUMSPED 300k/second (2x
drive) 600k/second
(4x drive)
Note that these numbers are only accurate
when reading 2048 byte blocks. The CD-ROM
drive will automatically switch to normal
speed when playing audio tracks and will
switch back to the speed setting when
accessing data.
SEE ALSO
ioctl(2), read(2)
N. V. Phillips and Sony Corporation, System Description Com-
pact Disc Digital Audio, ("Red Book").
N. V. Phillips and Sony Corporation, System Description of
Compact Disc Read Only Memory, ("Yellow Book").
SunOS 5.11 Last change: 4 Oct 2001 11
Ioctl Requests cdio(7I)
N. V. Phillips, Microsoft, and Sony Corporation, System
Description CD-ROM XA, 1991.
Volume and File Structure of CD-ROM for Information Inter-
change, ISO 9660:1988(E).
SCSI-2 Standard, document X3T9.2/86-109
SCSI Multimedia Commands, Version 2 (MC-2)
NOTES
The CDROMCDA, CDROMCDXA, CDROMSUBCODE, CDROMGDRVSPED,
CDROMSDRVSPED, and some of the block sizes in CDROMSBLK-
MODE are designed for new Sun-supported CD-ROM drives and
might not work on some of the older CD-ROM drives.
CDROMCDA, CDROMCDXA and CDROMSUBCODE will return error if
the transfer length exceeds valid limits as determined
appropriate. Example: for MC-2 drives, length can not
exceed 3 bytes (i.e. 0xffffff). The same restriction is
enforced for older, pre-MC-2 drives, as no limit was pub-
lished 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.
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 incor-
porated.
SunOS 5.11 Last change: 4 Oct 2001 12
|
