diff options
Diffstat (limited to 'usr/src/man/man4i/cdio.4i')
| -rw-r--r-- | usr/src/man/man4i/cdio.4i | 692 |
1 files changed, 692 insertions, 0 deletions
diff --git a/usr/src/man/man4i/cdio.4i b/usr/src/man/man4i/cdio.4i new file mode 100644 index 0000000000..cf86e92801 --- /dev/null +++ b/usr/src/man/man4i/cdio.4i @@ -0,0 +1,692 @@ +.\" 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. |