.\"  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
.\"  Copryright 2017, Joyent, Inc.
.\" 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]
.Dd October 22, 2017
.Dt CDIO 4I
.Os
.Sh NAME
.Nm cdio
.Nd CD-ROM control operations
.Sh SYNOPSIS
.In sys/cdio.h
.Sh DESCRIPTION
The set of
.Xr ioctl 2
commands described below are used to perform audio and
.Sy CD-ROM
specific operations.
Basic to these
.Sy cdio
ioctl requests are the definitions in
.In sys/cdio.h .
.Pp
Several
.Sy CD-ROM
specific commands can report addresses either in
.Sy LBA
(Logical Block Address) format or in
.Sy MSF
(Minute, Second, Frame) format.
The
.Sy READ HEADER ,
.Sy BREAD SUBCHANNEL ,
and
.Sy BREAD TABLE OF CONTENTS
commands have this feature.
.Pp
.Sy LBA
format represents the logical block address for the
.Sy CD-ROM
absolute address field or for the offset from the beginning of the current
track expressed as a number of logical blocks in a
.Sy CD-ROM
track relative address field.
.Sy MSF
format represents the physical address written on
.Sy CD-ROM
discs, expressed as a sector count relative to either the
beginning of the medium or the beginning of the current track.
.Sh IOCTLS
The following
.Sy I/O
controls do not have any additional data passed into or received from them.
.Bl -tag -width CDROMCLOSETRAY
.It Dv CDROMSTART
This
.Xr ioctl 2
spins up the disc and seeks to the last address requested.
.It Dv CDROMSTOP
This
.Xr ioctl 2
spins down the disc.
.It Dv CDROMPAUSE
This
.Xr ioctl 2
pauses the current audio play operation.
.It Dv CDROMRESUME
This
.Xr ioctl 2
resumes the paused audio play operation.
.It Dv CDROMEJECT
This
.Xr ioctl 2
ejects the caddy with the disc.
.It Dv CDROMCLOSETRAY
This
.Xr ioctl 2
closes the caddy with the disc.
.El
.Pp
The following
.Sy I/O
controls require a pointer to the structure for that
.Xr ioctl 2 ,
with data being passed into the
.Xr ioctl 2 .
.Bl -tag -width CDROMPLAYTRKIND
.It Dv CDROMPLAYMSF
This
.Xr ioctl 2
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
.Sy MSF
format.
The third argument of this
.Xr ioctl 2
call is a pointer to the type
.Vt "struct cdrom_msf" .
.Bd -literal -offset 2n
/*
 * definition of play audio msf structure
 */
struct cdrom_msf {
	/* starting minute */
	unsigned char	cdmsf_min0;
	/* starting second */
	unsigned char	cdmsf_sec0;
	/* starting frame */
	unsigned char	cdmsf_frame0;
	/* ending minute */
	unsigned char	cdmsf_min1;
	/* ending second */
	unsigned char	cdmsf_sec1;
	/* ending frame */
	unsigned char	cdmsf_frame1;
};
.Ed
.Pp
The
.Dv 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
.Dv CDROMREADTOCENTRY
ioctl request to retrieve the start time of the track
following the current track.
.Pp
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.
.It Dv CDROMPLAYTRKIND
This
.Xr ioctl 2
command is similar to
.Dv CDROMPLAYMSF .
The starting and ending address is in track/index format.
The third argument of the
.Xr ioctl 2
call is a pointer to the type
.Vt "struct cdrom_ti" .
.Bd -literal -offset 2n
/*
 * definition of play audio track/index structure
 */
struct cdrom_ti {
	/* starting track */
	unsigned char	cdti_trk0;
	/* starting index */
	unsigned char	cdti_ind0;
	/* ending track */
	unsigned char	cdti_trk1;
	/* ending index */
	unsigned char	cdti_ind1;
};
.Ed
.It Dv CDROMVOLCTRL
This
.Xr ioctl 2
command controls the audio output level.
The
.Sy SCSI
command allows the control of up to four channels.
The current implementation of the supported
.Sy CD-ROM
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
.Xr ioctl 2
call is a pointer to
.Vt "struct cdrom_volctrl"
which contains the output volume values.
.Bd -literal -offset 2n
/*
 * definition of audio volume control structure
 */
struct cdrom_volctrl {
	unsigned char	channel0;
	unsigned char	channel1;
	unsigned char	channel2;
	unsigned char	channel3;
};
.Ed
.El
.Pp
The following
.Sy I/O
controls take a pointer that will have data returned to
the user program from the
.Sy CD-ROM
driver.
.Bl -tag -width CDROMREADOFFSET
.It Dv CDROMREADTOCHDR
This
.Xr ioctl 2
command returns the header of the  table of contents (TOC).
The header consists of the starting track number and the ending track number
of the disc.
These two numbers are returned through a pointer of
.Vt "struct cdrom_tochdr" .
While the disc can start at any number, all tracks between the
first and last tracks are in contiguous ascending order.
.Bd -literal -offset 2n
/*
 * definition of read toc header structure
 */
struct cdrom_tochdr {
	unsigned char	cdth_trk0; /* starting track */
	unsigned char	cdth_trk1; /* ending track */
};
.Ed
.It Dv CDROMREADTOCENTRY
This
.Xr ioctl 2
command returns the information of a specified track.
The third argument of the function call is a pointer to the type
.Vt "struct cdrom_tocentry" .
The caller needs to supply the track number and the address format.
This command will return a 4-bit
.Sy adr
field, a 4-bit
.Sy ctrl
field, the starting address in
.Sy MSF
format or
.Sy LBA
format, and the data mode if the track is a data track.
The
.Sy ctrl
field specifies whether the track is data or audio.
.Bd -literal -offset 2n
/*
 * 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;
};
.Ed
.Pp
To get the information from the leadout track, the following value is
appropriate for the
.Fa cdte_track
field:
.\" These next few lists all use the same width so they align better
.Bl -tag -offset indent -width CDROM_DATA_TRACK
.It Dv CDROM_LEADOUT
Leadout track
.El
.Pp
To get the information from the data track, the following value is appropriate
for the
.Fa cdte_ctrl
field:
.Bl -tag -offset indent -width CDROM_DATA_TRACK
.It Dv CDROM_DATA_TRACK
Data track
.El
.Pp
The following values are appropriate for the
.Fa cdte_format
field:
.Bl -tag -offset indent -width CDROM_DATA_TRACK
.It Dv CDROM_LBA
.Sy LBA
format
.It Dv CDROM_MSF
.Sy MSF
format
.El
.It Dv CDROMSUBCHNL
This
.Xr ioctl 2
command reads the Q sub-channel data of the current block.
The subchannel data includes track number, index number, absolute
.Sy CD-ROM
address, track relative
.Sy CD-ROM
address, control data and audio status.
All information is returned through a pointer to
.Vt "struct cdrom_subchnl" .
The caller needs to supply the address format for the returned address.
.Bd -literal -offset 2n
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;
};
.Ed
.Pp
The following values are valid for the audio status field returned from
.Sy "READ SUBCHANNEL"
command:
.Bl -tag -width CDROM_AUDIO_NO_STATUS
.It Dv CDROM_AUDIO_INVALID
Audio status not supported.
.It Dv CDROM_AUDIO_PLAY
Audio play operation in progress.
.It Dv CDROM_AUDIO_PAUSED
Audio play operation paused.
.It Dv CDROM_AUDIO_COMPLETED
Audio play successfully completed.
.It Dv CDROM_AUDIO_ERROR
Audio play stopped due to error.
.It Dv CDROM_AUDIO_NO_STATUS
No current audio status to return.
.El
.It Dv CDROMREADOFFSET
This
.Xr ioctl 2
command returns the absolute
.Sy CD-ROM
address of the first track in the last session of a Multi-Session
.Sy CD-ROM .
The third argument of the
.Xr ioctl 2
call is a pointer to an
.Vt int .
.It Dv CDROMCDDA
This
.Xr ioctl 2
command returns the
.Sy CD-DA
data or the subcode data.
The third argument of the
.Xr ioctl 2
call is a pointer to the type
.Vt "struct cdrom_cdda" .
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
.Dv CDROMREADTOCENTRY
.Xr ioctl 2
to find out which tracks contain
.Sy CD-DA
data before issuing this
.Xr ioctl 2 .
.Bd -literal -offset 2n
/*
 * Definition of CD-DA structure
 */
struct cdrom_cdda {
	unsigned int	cdda_addr;
	unsigned int	cdda_length;
	caddr_t		cdda_data;
	unsigned char	cdda_subcode;
};
.Ed
.Pp
.Sy cdda_addr
signifies the starting logical block address.
.Sy cdda_length
signifies the transfer length in blocks.
The length of the block depends on the
.Sy cdda_subcode
selection, which is explained below.
To get the subcode information related to
.Sy CD-DA
data, the following values are appropriate for the
.Sy cdda_subcode
field:
.Bl -tag -width CDROM_DA_SUBCODE_ONLY
.It Sy CDROM_DA_NO_SUBCODE
.Sy CD-DA
data with no subcode.
.It Sy CDROM_DA_SUBQ
.Sy CD-DA
data with sub Q code.
.It Sy CDROM_DA_ALL_SUBCODE
.Sy CD-DA
data with all subcode.
.It Sy CDROM_DA_SUBCODE_ONLY
All subcode only.
.El
.Pp
To allocate the memory related to
.Sy CD-DA
and/or subcode data, the
following values are appropriate for each data  block transferred:
.Bl -tag -width "CD-DA data with all subcode"
.It Sy CD-DA data with no subcode
2352 bytes
.It Sy CD-DA data with sub Q code
2368 bytes
.It Sy CD-DA data with all subcode
2448 bytes
.It Sy "All subcode only"
96 bytes
.El
.It Dv CDROMCDXA
This
.Xr ioctl 2
command returns the
.Sy "CD-ROM XA"
(CD-ROM Extended Architecture) data according to
.Sy "CD-ROM XA"
format.
The third argument of the
.Xr ioctl 2
call is a pointer to the type
.Vt "struct cdrom_cdxa" .
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
.Sy CDROMREADTOCENTRY
.Xr ioctl 2
to find out which tracks contain
.Sy "CD-ROM XA"
data before issuing this
.Xr ioctl 2 .
.Bd -literal -offset 2n
/*
 * 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;
};
.Ed
.Pp
To get the proper
.Sy "CD-ROM XA"
data, the following values are appropriate for the
.Fa cdxa_format
field:
.Bl -tag -width CDROM_XA_DATA_W_ERROR
.It Dv CDROM_XA_DATA
.Sy "CD-ROM XA"
data only
.It Dv CDROM_XA_SECTOR_DATA
.Sy "CD-ROM XA"
all sector data
.It Dv CDROM_XA_DATA_W_ERROR
.Sy CD-ROM \fBXA\fR
data with error flags data
.El
.Pp
To allocate the memory related to
.Sy "CD-ROM XA"
format, the following values are appropriate for each data  block transferred:
.Bl -tag -width "CD-ROM XA data with error flags data"
.It Sy "CD-ROM XA" data only
2048 bytes
.It Sy "CD-ROM XA" all sector data
2352 bytes
.It Sy "CD-ROM XA" data with error flags data
2646 bytes
.El
.It Dv CDROMSUBCODE
This
.Xr ioctl 2
command returns raw subcode data (subcodes P ~ W are
described in the "Red Book," see
.Sx SEE ALSO )
to the initiator while the target is playing audio.
The third argument of the
.Xr ioctl 2
call is a pointer to the type
.Vt "struct cdrom_subcode" .
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.
.Bd -literal -offset 2n
/*
 * Definition of subcode structure
 */
struct cdrom_subcode {
	unsigned int	cdsc_length;
	caddr_t		cdsc_addr;
};
.Ed
.El
.Pp
The next group of
.Sy I/O
controls get and set various
.Sy CD-ROM
drive parameters.
.Bl -tag -width CDROMGDRVSPEED
.It Dv CDROMGBLKMODE
This
.Xr ioctl 2
command returns the current block size used by the
.Sy CD-ROM
drive.
The third argument of the
.Xr ioctl 2
call is a pointer to an integer.
.It Dv CDROMSBLKMODE
This
.Xr ioctl 2
command requests the
.Sy CD-ROM
drive to change from the current block size to the requested block size.
The third argument of the
.Xr ioctl 2
call is an integer which contains the requested block size.
This
.Xr ioctl 2
command operates in exclusive-use mode only.
The caller must ensure  that no other processes can operate on the same
.Sy CD-ROM
device before issuing this
.Xr ioctl 2 .
.Xr read 2
behavior subsequent to this
.Xr ioctl 2
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 following values are appropriate:
.Bl -tag -width CDROM_BLK_1024
.It Dv CDROM_BLK_512
512 bytes
.It Dv CDROM_BLK_1024
1024 bytes
.It Dv CDROM_BLK_2048
2048 bytes
.It Dv CDROM_BLK_2056
2056 bytes
.It Dv CDROM_BLK_2336
2336 bytes
.It Dv CDROM_BLK_2340
2340 bytes
.It Dv CDROM_BLK_2352
2352 bytes
.It Dv CDROM_BLK_2368
2368 bytes
.It Dv CDROM_BLK_2448
2448 bytes
.It Dv CDROM_BLK_2646
2646 bytes
.It Dv CDROM_BLK_2647
2647 bytes
.El
.It Dv CDROMGDRVSPEED
This
.Xr ioctl 2
command returns the current
.Sy CD-ROM
drive speed.
The third argument of the
.Xr ioctl 2
call is a pointer to an integer.
.It Dv CDROMSDRVSPEED
This
.Xr ioctl 2
command requests the
.Sy CD-ROM
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
.Xr ioctl 2
is an integer which contains the requested drive speed.
To set the
.Sy CD-ROM
drive to the proper speed, the following values are appropriate:
.Bl -tag -width CDROM_MAXIMUM_SPEED
.It Dv CDROM_NORMAL_SPEED
150k/second
.It Dv CDROM_DOUBLE_SPEED
300k/second
.It Dv CDROM_QUAD_SPEED
600k/second
.It Dv CDROM_MAXIMUM_SPEED
300k/second (2x drive)
.Pp
600k/second (4x drive)
.El
.Pp
Note that these numbers are only accurate when reading 2048 byte blocks.
The
.Sy CD-ROM
drive will automatically switch to normal speed when playing audio
tracks and will switch back to the speed setting when accessing data.
.El
.Sh ARCHITECTURE
All
.Sh INTERFACE STABILITY
Uncommitted
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr read 2 ,
.Xr attributes 7
.Rs
.%Q N. V. Phillips
.%Q Sony Corporation
.%B System Description Compact Disc Digital Audio
.%O ("Red Book")
.Re
.Rs
.%Q N. V. Phillips
.%Q Sony Corporation
.%B System Description of Compact Disc Read Only Memory
.%O ("Yellow Book")
.Re
.Rs
.%Q N. V. Phillips
.%Q Microsoft
.%Q Sony Corporation
.%B System Description CD-ROM XA
.%D 1991
.Re
.Rs
.%T Volume and File Structure of CD-ROM for Information Interchange
.%N ISO 9660:1988(E)
.Re
.Rs
.%T SCSI-2 Standard
.%N document X3T9.2/86-109
.Re
.Rs
.%T SCSI Multimedia Commands, Version 2 (MMC-2)
.Re
.Sh NOTES
The
.Dv CDROMCDDA ,
.Dv CDROMCDXA ,
.Dv CDROMSUBCODE ,
.Dv CDROMGDRVSPEED ,
.Dv CDROMSDRVSPEED ,
and some of the block sizes in
.Dv CDROMSBLKMODE
are designed for new Sun-supported
.Sy CD-ROM
drives and might not work on some of the older
.Sy CD-ROM
drives.
.Pp
.Dv CDROMCDDA ,
.Dv CDROMCDXA ,
and
.Dv 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.
.Pp
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.