1.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved 2.\" Copryright 2017, Joyent, Inc. 3.\" The contents of this file are subject to the terms of the 4.\" Common Development and Distribution License (the "License"). 5.\" You may not use this file except in compliance with the License. 6.\" 7.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 8.\" or http://www.opensolaris.org/os/licensing. 9.\" See the License for the specific language governing permissions 10.\" and limitations under the License. 11.\" 12.\" When distributing Covered Code, include this CDDL HEADER in each 13.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 14.\" If applicable, add the following below this CDDL HEADER, with the 15.\" fields enclosed by brackets "[]" replaced with your own identifying 16.\" information: Portions Copyright [yyyy] [name of copyright owner] 17.Dd October 22, 2017 18.Dt CDIO 4I 19.Os 20.Sh NAME 21.Nm cdio 22.Nd CD-ROM control operations 23.Sh SYNOPSIS 24.In sys/cdio.h 25.Sh DESCRIPTION 26The set of 27.Xr ioctl 2 28commands described below are used to perform audio and 29.Sy CD-ROM 30specific operations. 31Basic to these 32.Sy cdio 33ioctl requests are the definitions in 34.In sys/cdio.h . 35.Pp 36Several 37.Sy CD-ROM 38specific commands can report addresses either in 39.Sy LBA 40(Logical Block Address) format or in 41.Sy MSF 42(Minute, Second, Frame) format. 43The 44.Sy READ HEADER , 45.Sy BREAD SUBCHANNEL , 46and 47.Sy BREAD TABLE OF CONTENTS 48commands have this feature. 49.Pp 50.Sy LBA 51format represents the logical block address for the 52.Sy CD-ROM 53absolute address field or for the offset from the beginning of the current 54track expressed as a number of logical blocks in a 55.Sy CD-ROM 56track relative address field. 57.Sy MSF 58format represents the physical address written on 59.Sy CD-ROM 60discs, expressed as a sector count relative to either the 61beginning of the medium or the beginning of the current track. 62.Sh IOCTLS 63The following 64.Sy I/O 65controls do not have any additional data passed into or received from them. 66.Bl -tag -width CDROMCLOSETRAY 67.It Dv CDROMSTART 68This 69.Xr ioctl 2 70spins up the disc and seeks to the last address requested. 71.It Dv CDROMSTOP 72This 73.Xr ioctl 2 74spins down the disc. 75.It Dv CDROMPAUSE 76This 77.Xr ioctl 2 78pauses the current audio play operation. 79.It Dv CDROMRESUME 80This 81.Xr ioctl 2 82resumes the paused audio play operation. 83.It Dv CDROMEJECT 84This 85.Xr ioctl 2 86ejects the caddy with the disc. 87.It Dv CDROMCLOSETRAY 88This 89.Xr ioctl 2 90closes the caddy with the disc. 91.El 92.Pp 93The following 94.Sy I/O 95controls require a pointer to the structure for that 96.Xr ioctl 2 , 97with data being passed into the 98.Xr ioctl 2 . 99.Bl -tag -width CDROMPLAYTRKIND 100.It Dv CDROMPLAYMSF 101This 102.Xr ioctl 2 103command requests the drive to output the audio signals at 104the specified starting address and continue the audio play until the specified 105ending address is detected. 106The address is in 107.Sy MSF 108format. 109The third argument of this 110.Xr ioctl 2 111call is a pointer to the type 112.Vt "struct cdrom_msf" . 113.Bd -literal -offset 2n 114/* 115 * definition of play audio msf structure 116 */ 117struct cdrom_msf { 118 /* starting minute */ 119 unsigned char cdmsf_min0; 120 /* starting second */ 121 unsigned char cdmsf_sec0; 122 /* starting frame */ 123 unsigned char cdmsf_frame0; 124 /* ending minute */ 125 unsigned char cdmsf_min1; 126 /* ending second */ 127 unsigned char cdmsf_sec1; 128 /* ending frame */ 129 unsigned char cdmsf_frame1; 130}; 131.Ed 132.Pp 133The 134.Dv CDROMREADTOCENTRY 135ioctl request may be used to obtain the start time for a track. 136An approximation of the finish time can be obtained by using the 137.Dv CDROMREADTOCENTRY 138ioctl request to retrieve the start time of the track 139following the current track. 140.Pp 141The leadout track is the next consecutive track after the last audio track. 142Hence, the start time of the leadout track may be used as the effective finish 143time of the last audio track. 144.It Dv CDROMPLAYTRKIND 145This 146.Xr ioctl 2 147command is similar to 148.Dv CDROMPLAYMSF . 149The starting and ending address is in track/index format. 150The third argument of the 151.Xr ioctl 2 152call is a pointer to the type 153.Vt "struct cdrom_ti" . 154.Bd -literal -offset 2n 155/* 156 * definition of play audio track/index structure 157 */ 158struct cdrom_ti { 159 /* starting track */ 160 unsigned char cdti_trk0; 161 /* starting index */ 162 unsigned char cdti_ind0; 163 /* ending track */ 164 unsigned char cdti_trk1; 165 /* ending index */ 166 unsigned char cdti_ind1; 167}; 168.Ed 169.It Dv CDROMVOLCTRL 170This 171.Xr ioctl 2 172command controls the audio output level. 173The 174.Sy SCSI 175command allows the control of up to four channels. 176The current implementation of the supported 177.Sy CD-ROM 178drive only uses channel 0 and channel 1. 179The valid values of volume control are between 0x00 and 0xFF, with a value of 1800xFF indicating maximum volume. 181The third argument of the 182.Xr ioctl 2 183call is a pointer to 184.Vt "struct cdrom_volctrl" 185which contains the output volume values. 186.Bd -literal -offset 2n 187/* 188 * definition of audio volume control structure 189 */ 190struct cdrom_volctrl { 191 unsigned char channel0; 192 unsigned char channel1; 193 unsigned char channel2; 194 unsigned char channel3; 195}; 196.Ed 197.El 198.Pp 199The following 200.Sy I/O 201controls take a pointer that will have data returned to 202the user program from the 203.Sy CD-ROM 204driver. 205.Bl -tag -width CDROMREADOFFSET 206.It Dv CDROMREADTOCHDR 207This 208.Xr ioctl 2 209command returns the header of the table of contents (TOC). 210The header consists of the starting track number and the ending track number 211of the disc. 212These two numbers are returned through a pointer of 213.Vt "struct cdrom_tochdr" . 214While the disc can start at any number, all tracks between the 215first and last tracks are in contiguous ascending order. 216.Bd -literal -offset 2n 217/* 218 * definition of read toc header structure 219 */ 220struct cdrom_tochdr { 221 unsigned char cdth_trk0; /* starting track */ 222 unsigned char cdth_trk1; /* ending track */ 223}; 224.Ed 225.It Dv CDROMREADTOCENTRY 226This 227.Xr ioctl 2 228command returns the information of a specified track. 229The third argument of the function call is a pointer to the type 230.Vt "struct cdrom_tocentry" . 231The caller needs to supply the track number and the address format. 232This command will return a 4-bit 233.Sy adr 234field, a 4-bit 235.Sy ctrl 236field, the starting address in 237.Sy MSF 238format or 239.Sy LBA 240format, and the data mode if the track is a data track. 241The 242.Sy ctrl 243field specifies whether the track is data or audio. 244.Bd -literal -offset 2n 245/* 246 * definition of read toc entry structure 247 */ 248struct cdrom_tocentry { 249 unsigned char cdte_track; 250 unsigned char cdte_adr :4; 251 unsigned char cdte_ctrl :4; 252 unsigned char cdte_format; 253 union { 254 struct { 255 unsigned char minute; 256 unsigned char second; 257 unsigned char frame; 258 } msf; 259 int lba; 260 } cdte_addr; 261 unsigned char cdte_datamode; 262}; 263.Ed 264.Pp 265To get the information from the leadout track, the following value is 266appropriate for the 267.Fa cdte_track 268field: 269.\" These next few lists all use the same width so they align better 270.Bl -tag -offset indent -width CDROM_DATA_TRACK 271.It Dv CDROM_LEADOUT 272Leadout track 273.El 274.Pp 275To get the information from the data track, the following value is appropriate 276for the 277.Fa cdte_ctrl 278field: 279.Bl -tag -offset indent -width CDROM_DATA_TRACK 280.It Dv CDROM_DATA_TRACK 281Data track 282.El 283.Pp 284The following values are appropriate for the 285.Fa cdte_format 286field: 287.Bl -tag -offset indent -width CDROM_DATA_TRACK 288.It Dv CDROM_LBA 289.Sy LBA 290format 291.It Dv CDROM_MSF 292.Sy MSF 293format 294.El 295.It Dv CDROMSUBCHNL 296This 297.Xr ioctl 2 298command reads the Q sub-channel data of the current block. 299The subchannel data includes track number, index number, absolute 300.Sy CD-ROM 301address, track relative 302.Sy CD-ROM 303address, control data and audio status. 304All information is returned through a pointer to 305.Vt "struct cdrom_subchnl" . 306The caller needs to supply the address format for the returned address. 307.Bd -literal -offset 2n 308struct cdrom_subchnl { 309 unsigned char cdsc_format; 310 unsigned char cdsc_audiostatus; 311 unsigned char cdsc_adr :4; 312 unsigned char cdsc_ctrl :4; 313 unsigned char cdsc_trk; 314 unsigned char cdsc_ind; 315 union { 316 struct { 317 unsigned char minute; 318 unsigned char second; 319 unsigned char frame; 320 } msf; 321 int lba; 322 } cdsc_absaddr; 323 union { 324 struct { 325 unsigned char minute; 326 unsigned char second; 327 unsigned char frame; 328 } msf; 329 int lba; 330 } cdsc_reladdr; 331}; 332.Ed 333.Pp 334The following values are valid for the audio status field returned from 335.Sy "READ SUBCHANNEL" 336command: 337.Bl -tag -width CDROM_AUDIO_NO_STATUS 338.It Dv CDROM_AUDIO_INVALID 339Audio status not supported. 340.It Dv CDROM_AUDIO_PLAY 341Audio play operation in progress. 342.It Dv CDROM_AUDIO_PAUSED 343Audio play operation paused. 344.It Dv CDROM_AUDIO_COMPLETED 345Audio play successfully completed. 346.It Dv CDROM_AUDIO_ERROR 347Audio play stopped due to error. 348.It Dv CDROM_AUDIO_NO_STATUS 349No current audio status to return. 350.El 351.It Dv CDROMREADOFFSET 352This 353.Xr ioctl 2 354command returns the absolute 355.Sy CD-ROM 356address of the first track in the last session of a Multi-Session 357.Sy CD-ROM . 358The third argument of the 359.Xr ioctl 2 360call is a pointer to an 361.Vt int . 362.It Dv CDROMCDDA 363This 364.Xr ioctl 2 365command returns the 366.Sy CD-DA 367data or the subcode data. 368The third argument of the 369.Xr ioctl 2 370call is a pointer to the type 371.Vt "struct cdrom_cdda" . 372In addition to allocating memory and supplying its address, the 373caller needs to supply the starting address of the data, the transfer length in 374terms of the number of blocks to be transferred, and the subcode options. 375The caller also needs to issue the 376.Dv CDROMREADTOCENTRY 377.Xr ioctl 2 378to find out which tracks contain 379.Sy CD-DA 380data before issuing this 381.Xr ioctl 2 . 382.Bd -literal -offset 2n 383/* 384 * Definition of CD-DA structure 385 */ 386struct cdrom_cdda { 387 unsigned int cdda_addr; 388 unsigned int cdda_length; 389 caddr_t cdda_data; 390 unsigned char cdda_subcode; 391}; 392.Ed 393.Pp 394.Sy cdda_addr 395signifies the starting logical block address. 396.Sy cdda_length 397signifies the transfer length in blocks. 398The length of the block depends on the 399.Sy cdda_subcode 400selection, which is explained below. 401To get the subcode information related to 402.Sy CD-DA 403data, the following values are appropriate for the 404.Sy cdda_subcode 405field: 406.Bl -tag -width CDROM_DA_SUBCODE_ONLY 407.It Sy CDROM_DA_NO_SUBCODE 408.Sy CD-DA 409data with no subcode. 410.It Sy CDROM_DA_SUBQ 411.Sy CD-DA 412data with sub Q code. 413.It Sy CDROM_DA_ALL_SUBCODE 414.Sy CD-DA 415data with all subcode. 416.It Sy CDROM_DA_SUBCODE_ONLY 417All subcode only. 418.El 419.Pp 420To allocate the memory related to 421.Sy CD-DA 422and/or subcode data, the 423following values are appropriate for each data block transferred: 424.Bl -tag -width "CD-DA data with all subcode" 425.It Sy CD-DA data with no subcode 4262352 bytes 427.It Sy CD-DA data with sub Q code 4282368 bytes 429.It Sy CD-DA data with all subcode 4302448 bytes 431.It Sy "All subcode only" 43296 bytes 433.El 434.It Dv CDROMCDXA 435This 436.Xr ioctl 2 437command returns the 438.Sy "CD-ROM XA" 439(CD-ROM Extended Architecture) data according to 440.Sy "CD-ROM XA" 441format. 442The third argument of the 443.Xr ioctl 2 444call is a pointer to the type 445.Vt "struct cdrom_cdxa" . 446In addition to allocating memory and supplying its address, the 447caller needs to supply the starting address of the data, the transfer length 448in terms of number of blocks, and the format. 449The caller also needs to issue 450the 451.Sy CDROMREADTOCENTRY 452.Xr ioctl 2 453to find out which tracks contain 454.Sy "CD-ROM XA" 455data before issuing this 456.Xr ioctl 2 . 457.Bd -literal -offset 2n 458/* 459 * Definition of CD-ROM XA structure 460 */ 461struct cdrom_cdxa { 462 unsigned int cdxa_addr; 463 unsigned int cdxa_length; 464 caddr_t cdxa_data; 465 unsigned char cdxa_format; 466}; 467.Ed 468.Pp 469To get the proper 470.Sy "CD-ROM XA" 471data, the following values are appropriate for the 472.Fa cdxa_format 473field: 474.Bl -tag -width CDROM_XA_DATA_W_ERROR 475.It Dv CDROM_XA_DATA 476.Sy "CD-ROM XA" 477data only 478.It Dv CDROM_XA_SECTOR_DATA 479.Sy "CD-ROM XA" 480all sector data 481.It Dv CDROM_XA_DATA_W_ERROR 482.Sy CD-ROM \fBXA\fR 483data with error flags data 484.El 485.Pp 486To allocate the memory related to 487.Sy "CD-ROM XA" 488format, the following values are appropriate for each data block transferred: 489.Bl -tag -width "CD-ROM XA data with error flags data" 490.It Sy "CD-ROM XA" data only 4912048 bytes 492.It Sy "CD-ROM XA" all sector data 4932352 bytes 494.It Sy "CD-ROM XA" data with error flags data 4952646 bytes 496.El 497.It Dv CDROMSUBCODE 498This 499.Xr ioctl 2 500command returns raw subcode data (subcodes P ~ W are 501described in the "Red Book," see 502.Sx SEE ALSO ) 503to the initiator while the target is playing audio. 504The third argument of the 505.Xr ioctl 2 506call is a pointer to the type 507.Vt "struct cdrom_subcode" . 508The caller needs to supply the transfer length in terms of number of blocks and 509allocate memory for subcode data. 510The memory allocated should be a multiple of 96 bytes depending on the 511transfer length. 512.Bd -literal -offset 2n 513/* 514 * Definition of subcode structure 515 */ 516struct cdrom_subcode { 517 unsigned int cdsc_length; 518 caddr_t cdsc_addr; 519}; 520.Ed 521.El 522.Pp 523The next group of 524.Sy I/O 525controls get and set various 526.Sy CD-ROM 527drive parameters. 528.Bl -tag -width CDROMGDRVSPEED 529.It Dv CDROMGBLKMODE 530This 531.Xr ioctl 2 532command returns the current block size used by the 533.Sy CD-ROM 534drive. 535The third argument of the 536.Xr ioctl 2 537call is a pointer to an integer. 538.It Dv CDROMSBLKMODE 539This 540.Xr ioctl 2 541command requests the 542.Sy CD-ROM 543drive to change from the current block size to the requested block size. 544The third argument of the 545.Xr ioctl 2 546call is an integer which contains the requested block size. 547This 548.Xr ioctl 2 549command operates in exclusive-use mode only. 550The caller must ensure that no other processes can operate on the same 551.Sy CD-ROM 552device before issuing this 553.Xr ioctl 2 . 554.Xr read 2 555behavior subsequent to this 556.Xr ioctl 2 557remains the same: the caller is still constrained to read the raw 558device on block boundaries and in block multiples. 559To set the proper block size, the following values are appropriate: 560.Bl -tag -width CDROM_BLK_1024 561.It Dv CDROM_BLK_512 562512 bytes 563.It Dv CDROM_BLK_1024 5641024 bytes 565.It Dv CDROM_BLK_2048 5662048 bytes 567.It Dv CDROM_BLK_2056 5682056 bytes 569.It Dv CDROM_BLK_2336 5702336 bytes 571.It Dv CDROM_BLK_2340 5722340 bytes 573.It Dv CDROM_BLK_2352 5742352 bytes 575.It Dv CDROM_BLK_2368 5762368 bytes 577.It Dv CDROM_BLK_2448 5782448 bytes 579.It Dv CDROM_BLK_2646 5802646 bytes 581.It Dv CDROM_BLK_2647 5822647 bytes 583.El 584.It Dv CDROMGDRVSPEED 585This 586.Xr ioctl 2 587command returns the current 588.Sy CD-ROM 589drive speed. 590The third argument of the 591.Xr ioctl 2 592call is a pointer to an integer. 593.It Dv CDROMSDRVSPEED 594This 595.Xr ioctl 2 596command requests the 597.Sy CD-ROM 598drive to change the current drive speed to the requested drive speed. 599This speed setting is only applicable when reading data areas. 600The third argument of the 601.Xr ioctl 2 602is an integer which contains the requested drive speed. 603To set the 604.Sy CD-ROM 605drive to the proper speed, the following values are appropriate: 606.Bl -tag -width CDROM_MAXIMUM_SPEED 607.It Dv CDROM_NORMAL_SPEED 608150k/second 609.It Dv CDROM_DOUBLE_SPEED 610300k/second 611.It Dv CDROM_QUAD_SPEED 612600k/second 613.It Dv CDROM_MAXIMUM_SPEED 614300k/second (2x drive) 615.Pp 616600k/second (4x drive) 617.El 618.Pp 619Note that these numbers are only accurate when reading 2048 byte blocks. 620The 621.Sy CD-ROM 622drive will automatically switch to normal speed when playing audio 623tracks and will switch back to the speed setting when accessing data. 624.El 625.Sh ARCHITECTURE 626All 627.Sh INTERFACE STABILITY 628Uncommitted 629.Sh SEE ALSO 630.Xr ioctl 2 , 631.Xr read 2 , 632.Xr attributes 7 633.Rs 634.%Q N. V. Phillips 635.%Q Sony Corporation 636.%B System Description Compact Disc Digital Audio 637.%O ("Red Book") 638.Re 639.Rs 640.%Q N. V. Phillips 641.%Q Sony Corporation 642.%B System Description of Compact Disc Read Only Memory 643.%O ("Yellow Book") 644.Re 645.Rs 646.%Q N. V. Phillips 647.%Q Microsoft 648.%Q Sony Corporation 649.%B System Description CD-ROM XA 650.%D 1991 651.Re 652.Rs 653.%T Volume and File Structure of CD-ROM for Information Interchange 654.%N ISO 9660:1988(E) 655.Re 656.Rs 657.%T SCSI-2 Standard 658.%N document X3T9.2/86-109 659.Re 660.Rs 661.%T SCSI Multimedia Commands, Version 2 (MMC-2) 662.Re 663.Sh NOTES 664The 665.Dv CDROMCDDA , 666.Dv CDROMCDXA , 667.Dv CDROMSUBCODE , 668.Dv CDROMGDRVSPEED , 669.Dv CDROMSDRVSPEED , 670and some of the block sizes in 671.Dv CDROMSBLKMODE 672are designed for new Sun-supported 673.Sy CD-ROM 674drives and might not work on some of the older 675.Sy CD-ROM 676drives. 677.Pp 678.Dv CDROMCDDA , 679.Dv CDROMCDXA , 680and 681.Dv CDROMSUBCODE 682will return error if the transfer length exceeds valid limits as determined appropriate. 683Example: for MMC-2 drives, length can not exceed 3 bytes (i\&.e\&. 0xffffff). 684The same restriction is enforced for older, pre-MMC-2 drives, as no limit was 685published for these older drives (and 3 bytes is reasonable for all media). 686Note that enforcing this limit does not imply that values passed in below this 687limit will actually be applicable for each and every piece of media. 688.Pp 689The interface to this device is preliminary and subject to change in future 690releases. 691Programs should be written in a modular fashion so that future 692changes can be easily incorporated. 693