1cdio(7I) Ioctl Requests cdio(7I)
2
6 cdio - CD-ROM control operations
7
9 #include <sys/cdio.h>
10
13 The set of ioctl(2) commands described below are used to perform audio
14 and CD-ROM specific operations. Basic to these cdio ioctl requests are
15 the definitions in <sys/cdio.h>.
16 Several CD-ROM specific commands can report addresses either in LBA
19 (Logical Block Address) format or in MSF (Minute, Second, Frame) for‐
20 mat. The READ HEADER, READ SUBCHANNEL, and READ TABLE OF CONTENTS com‐
21 mands have this feature.
22 LBA format represents the logical block address for the CD-ROM absolute
25 address field or for the offset from the beginning of the current track
26 expressed as a number of logical blocks in a CD-ROM track relative
27 address field. MSF format represents the physical address written on
28 CD-ROM discs, expressed as a sector count relative to either the begin‐
29 ning of the medium or the beginning of the current track.
30
32 The following I/O controls do not have any additional data passed into
33 or received from them.
34 CDROMSTART This ioctl() spins up the disc and seeks to the last
36 address requested.
37 CDROMSTOP This ioctl() spins down the disc.
40 CDROMPAUSE This ioctl() pauses the current audio play operation.
43 CDROMRESUME This ioctl() resumes the paused audio play operation.
46 CDROMEJECT This ioctl() ejects the caddy with the disc.
49 CDROMCLOSETRAY This ioctl() closes the caddy with the disc.
52 The following I/O controls require a pointer to the structure for that
56 ioctl(), with data being passed into the ioctl().
57 CDROMPLAYMSF This ioctl() command requests the drive to output
59 the audio signals at the specified starting address
60 and continue the audio play until the specified end‐
61 ing address is detected. The address is in MSF for‐
62 mat. The third argument of this ioctl() call is a
63 pointer to the type struct cdrom_msf.
64 /*
66 * definition of play audio msf structure
67 */
68 struct cdrom_msf {
69 unsigned char cdmsf_min0; /* starting minute*/
70 unsigned char cdmsf_sec0; /* starting second*/
71 unsigned char cdmsf_frame0; /*starting frame*/
72 unsigned char cdmsf_min1; /* ending minute */
73 unsigned char cdmsf_sec1; /* ending second */
74 unsigned char cdmsf_frame1; /* ending frame */
75 };
76 The CDROMREADTOCENTRY ioctl request may be used to
78 obtain the start time for a track. An approximation
79 of the finish time can be obtained by using the
80 CDROMREADTOCENTRY ioctl request to retrieve the
81 start time of the track following the current track.
82 The leadout track is the next consecutive track
84 after the last audio track. Hence, the start time
85 of the leadout track may be used as the effective
86 finish time of the last audio track.
87 CDROMPLAYTRKIND This ioctl() command is similar to CDROMPLAYMSF.
90 The starting and ending address is in track/index
91 format. The third argument of the ioctl() call is a
92 pointer to the type struct cdrom_ti.
93 /*
95 * definition of play audio track/index structure
96 */
97 struct cdrom_ti {
98 unsigned char cdti_trk0; /* starting track*/
99 unsigned char cdti_ind0; /* starting index*/
100 unsigned char cdti_trk1; /* ending track */
101 unsigned char cdti_ind1; /* ending index */
102 };
103 CDROMVOLCTRL This ioctl() command controls the audio output
107 level. The SCSI command allows the control of up to
108 four channels. The current implementation of the
109 supported CD-ROM drive only uses channel 0 and chan‐
110 nel 1. The valid values of volume control are
111 between 0x00 and 0xFF, with a value of 0xFF indicat‐
112 ing maximum volume. The third argument of the
113 ioctl() call is a pointer to struct cdrom_volctrl
114 which contains the output volume values.
115 /*
117 * definition of audio volume control structure
118 */
119 struct cdrom_volctrl {
120 unsigned char channel0;
121 unsigned char channel1;
122 unsigned char channel2;
123 unsigned char channel3;
124 };
125 The following I/O controls take a pointer that will have data returned
130 to the user program from the CD-ROM driver.
131 CDROMREADTOCHDR This ioctl() command returns the header of the
133 table of contents (TOC). The header consists of
134 the starting tracking number and the ending track
135 number of the disc. These two numbers are returned
136 through a pointer of struct cdrom_tochdr. While
137 the disc can start at any number, all tracks
138 between the first and last tracks are in contigu‐
139 ous ascending order.
140 /*
142 * definition of read toc header structure
143 */
144 struct cdrom_tochdr {
145 unsigned char cdth_trk0; /* starting track*/
146 unsigned char cdth_trk1; /* ending track*/
147 };
148 CDROMREADTOCENTRY This ioctl() command returns the information of a
152 specified track. The third argument of the func‐
153 tion call is a pointer to the type struct
154 cdrom_tocentry. The caller needs to supply the
155 track number and the address format. This command
156 will return a 4-bit adr field, a 4-bit ctrl
157 field, the starting address in MSF format or LBA
158 format, and the data mode if the track is a data
159 track. The ctrl field specifies whether the track
160 is data or audio.
161 /*
163 * definition of read toc entry structure
164 */
165 struct cdrom_tocentry {
166 unsigned char cdte_track;
167 unsigned char cdte_adr :4;
168 unsigned char cdte_ctrl :4;
169 unsigned char cdte_format;
170 union {
171 struct {
172 unsigned char minute;
173 unsigned char second;
174 unsigned char frame;
175 } msf;
176 int lba;
177 } cdte_addr;
178 unsigned char cdte_datamode;
179 };
180 To get the information from the leadout track, the
182 following value is appropriate for the cdte_track
183 field:
184 CDROM_LEADOUT Leadout track
186 To get the information from the data track, the
188 following value is appropriate for the cdte_ctrl
189 field:
190 CDROM_DATA_TRACK Data track
192 The following values are appropriate for the
194 cdte_format field:
195 CDROM_LBA LBA format
197 CDROM_MSF MSF format
200 CDROMSUBCHNL This ioctl() command reads the Q sub-channel data
204 of the current block. The subchannel data includes
205 track number, index number, absolute CD-ROM
206 address, track relative CD-ROM address, control
207 data and audio status. All information is returned
208 through a pointer to struct cdrom_subchnl. The
209 caller needs to supply the address format for the
210 returned address.
211 struct cdrom_subchnl {
213 unsigned char cdsc_format;
214 unsigned char cdsc_audiostatus;
215 unsigned char cdsc_adr: 4;
216 unsigned char cdsc_ctrl: 4;
217 unsigned char cdsc_trk;
218 unsigned char cdsc_ind;
219 union {
220 struct {
221 unsigned char minute;
222 unsigned char second;
223 unsigned char frame;
224 } msf;
225 int lba;
226 } cdsc_absaddr;
227 union {
228 struct {
229 unsigned char minute;
230 unsigned char second;
231 unsigned char frame;
232 } msf;
233 int lba;
234 } cdsc_reladdr;
235 };
236 The following values are valid for the audio sta‐
238 tus field returned from READ SUBCHANNEL command:
239 CDROM_AUDIO_INVALID Audio status not sup‐
241 ported.
242 CDROM_AUDIO_PLAY Audio play operation in
245 progress.
246 CDROM_AUDIO_PAUSED Audio play operation
249 paused.
250 CDROM_AUDIO_COMPLETED Audio play successfully
253 completed.
254 CDROM_AUDIO_ERROR Audio play stopped due to
257 error.
258 CDROM_AUDIO_NO_STATUS No current audio status
261 to return.
262 CDROMREADOFFSET This ioctl() command returns the absolute CD-ROM
266 address of the first track in the last session of
267 a Multi-Session CD-ROM. The third argument of the
268 ioctl() call is a pointer to an int.
269 CDROMCDDA This ioctl() command returns the CD-DA data or the
272 subcode data. The third argument of the ioctl()
273 call is a pointer to the type struct cdrom_cdda.
274 In addition to allocating memory and supplying its
275 address, the caller needs to supply the starting
276 address of the data, the transfer length in terms
277 of the number of blocks to be transferred, and the
278 subcode options. The caller also needs to issue
279 the CDROMREADTOCENTRY ioctl() to find out which
280 tracks contain CD-DA data before issuing this
281 ioctl().
282 /*
284 * Definition of CD-DA structure
285 */
286 struct cdrom_cdda {
287 unsigned int cdda_addr;
288 unsigned int cdda_length;
289 caddr_t cdda_data;
290 unsigned char cdda_subcode;
291 };
292 cdda_addr signifies the starting logical block
294 address.
295 cdda_length signifies the transfer length in
297 blocks. The length of the block depends on the
298 cdda_subcode selection, which is explained below.
299 To get the subcode information related to CD-DA
301 data, the following values are appropriate for the
302 cdda_subcode field:
303 CDROM_DA_NO_SUBCODE CD-DA data with no sub‐
305 code.
306 CDROM_DA_SUBQ CD-DA data with sub Q
309 code.
310 CDROM_DA_ALL_SUBCODE CD-DA data with all sub‐
313 code.
314 CDROM_DA_SUBCODE_ONLY All subcode only.
317 To allocate the memory related to CD-DA and/or
319 subcode data, the following values are appropriate
320 for each data block transferred:
321 CD-DA data with no subcode
323 2352 bytes
325 CD-DA data with sub Q code
328 2368 bytes
330 CD-DA data with all subcode
333 2448 bytes
335 All subcode only
338 96 bytes
340 CDROMCDXA This ioctl() command returns the CD-ROM XA (CD-ROM
344 Extended Architecture) data according to CD-ROM
345 XA format. The third argument of the ioctl() call
346 is a pointer to the type struct cdrom_cdxa. In
347 addition to allocating memory and supplying its
348 address, the caller needs to supply the starting
349 address of the data, the transfer length in terms
350 of number of blocks, and the format. The caller
351 also needs to issue the CDROMREADTOCENTRY ioctl()
352 to find out which tracks contain CD-ROM XA data
353 before issuing this ioctl().
354 /*
356 * Definition of CD-ROM XA structure
357 */
358 struct cdrom_cdxa {
359 unsigned int cdxa_addr;
360 unsigned int cdxa_length;
361 caddr_t cdxa_data;
362 unsigned char cdxa_format;
363 };
364 To get the proper CD-ROM XA data, the following
366 values are appropriate for the cdxa_format field:
367 CDROM_XA_DATA CD-ROM XA data only
369 CDROM_XA_SECTOR_DATA CD-ROM XA all sector data
372 CDROM_XA_DATA_W_ERROR CD-ROM XA data with error
375 flags data
376 To allocate the memory related to CD-ROM XA for‐
378 mat, the following values are appropriate for each
379 data block transferred:
380 CD-ROM XA data only
382 2048 bytes
384 CD-ROM XA all sector data
387 2352 bytes
389 CD-ROM XA data with error flags data
392 2646 bytes
394 CDROMSUBCODE This ioctl() command returns raw subcode data
398 (subcodes P ~ W are described in the "Red Book,"
399 see SEE ALSO) to the initiator while the target is
400 playing audio. The third argument of the ioctl()
401 call is a pointer to the type struct cdrom_sub‐
402 code. The caller needs to supply the transfer
403 length in terms of number of blocks and allocate
404 memory for subcode data. The memory allocated
405 should be a multiple of 96 bytes depending on the
406 transfer length.
407 /*
409 * Definition of subcode structure
410 */
411 struct cdrom_subcode {
412 unsigned int cdsc_length;
413 caddr_t cdsc_addr;
414 };
415 The next group of I/O controls get and set various CD-ROM drive parame‐
420 ters.
421 CDROMGBLKMODE This ioctl() command returns the current block size
423 used by the CD-ROM drive. The third argument of the
424 ioctl() call is a pointer to an integer.
425 CDROMSBLKMODE This ioctl() command requests the CD-ROM drive to
428 change from the current block size to the requested
429 block size. The third argument of the ioctl() call is
430 an integer which contains the requested block size.
431 This ioctl() command operates in exclusive-use mode
433 only. The caller must ensure that no other processes
434 can operate on the same CD-ROM device before issuing
435 this ioctl(). read(2) behavior subsequent to this
436 ioctl() remains the same: the caller is still con‐
437 strained to read the raw device on block boundaries
438 and in block multiples.
439 To set the proper block size, the following values
441 are appropriate:
442 CDROM_BLK_512 512 bytes
444 CDROM_BLK_1024 1024 bytes
447 CDROM_BLK_2048 2048 bytes
450 CDROM_BLK_2056 2056 bytes
453 CDROM_BLK_2336 2336 bytes
456 CDROM_BLK_2340 2340 bytes
459 CDROM_BLK_2352 2352 bytes
462 CDROM_BLK_2368 2368 bytes
465 CDROM_BLK_2448 2448 bytes
468 CDROM_BLK_2646 2646 bytes
471 CDROM_BLK_2647 2647 bytes
474 CDROMGDRVSPEED This ioctl() command returns the current CD-ROM drive
478 speed. The third argument of the ioctl() call is a
479 pointer to an integer.
480 CDROMSDRVSPEED This ioctl() command requests the CD-ROM drive to
483 change the current drive speed to the requested drive
484 speed. This speed setting is only applicable when
485 reading data areas. The third argument of the
486 ioctl() is an integer which contains the requested
487 drive speed.
488 To set the CD-ROM drive to the proper speed, the
490 following values are appropriate:
491 CDROM_NORMAL_SPEED 150k/second
493 CDROM_DOUBLE_SPEED 300k/second
496 CDROM_QUAD_SPEED 600k/second
499 CDROM_MAXIMUM_SPEED 300k/second (2x drive)
502 600k/second (4x drive)
503 Note that these numbers are only accurate when read‐
505 ing 2048 byte blocks. The CD-ROM drive will automat‐
506 ically switch to normal speed when playing audio
507 tracks and will switch back to the speed setting
508 when accessing data.
509
512 ioctl(2), read(2)
513 N. V. Phillips and Sony Corporation, System Description Compact Disc
516 Digital Audio, ("Red Book").
517 N. V. Phillips and Sony Corporation, System Description of Compact Disc
520 Read Only Memory, ("Yellow Book").
521 N. V. Phillips, Microsoft, and Sony Corporation, System Description CD-
524 ROM XA, 1991.
525 Volume and File Structure of CD-ROM for Information Interchange, ISO
528 9660:1988(E).
529 SCSI-2 Standard, document X3T9.2/86-109
532 SCSI Multimedia Commands, Version 2 (MMC-2)
535
537 The CDROMCDDA, CDROMCDXA, CDROMSUBCODE, CDROMGDRVSPEED, CDROMS‐
538 DRVSPEED, and some of the block sizes in CDROMSBLKMODE are designed
539 for new Sun-supported CD-ROM drives and might not work on some of the
540 older CD-ROM drives.
541 CDROMCDDA, CDROMCDXA and CDROMSUBCODE will return error if the transfer
544 length exceeds valid limits as determined appropriate. Example: for
545 MMC-2 drives, length can not exceed 3 bytes (i.e. 0xffffff). The same
546 restriction is enforced for older, pre-MMC-2 drives, as no limit was
547 published for these older drives (and 3 bytes is reasonable for all
548 media). Note that enforcing this limit does not imply that values
549 passed in below this limit will actually be applicable for each and
550 every piece of media.
551 The interface to this device is preliminary and subject to change in
554 future releases. Programs should be written in a modular fashion so
555 that future changes can be easily incorporated.
556SunOS 5.11 4 Oct 2001 cdio(7I)