1.\" Copyright (c) 1996 2.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $Id: cd.4,v 1.10 1997/02/22 13:24:23 peter Exp $ 27.\" 28.Dd January 16, 1996 29.Dt CD 4 30.Os FreeBSD 31.Sh NAME 32.Nm cd 33.Nd SCSI CD-ROM driver 34.Sh SYNOPSIS 35.Cd device cd 36.Cd device cd1 at scbus0 target 4 lun 0 37.Sh DESCRIPTION 38The 39.Nm cd 40driver provides support for a 41.Tn SCSI 42.Tn CD-ROM 43(Compact Disc-Read Only Memory) drive. 44In an attempt to look like a regular disk, the 45.Nm 46driver synthesizes a partition table, with one partition covering the entire 47.Tn CD-ROM . 48It is possible to modify this partition table using 49.Xr disklabel 8 , 50but it will only last until the 51.Tn CD-ROM 52is unmounted. 53In general the interfaces are similar to those described by 54.Xr wd 4 55and 56.Xr sd 4 . 57.Pp 58As the 59.Tn SCSI 60adapter is probed during boot, the 61.Tn SCSI 62bus is scanned for devices. Any devices found which answer as `Read-only' 63type devices will be `attached' to the 64.Nm 65driver. 66Prior to 67.Fx 2.1 , 68the first device found will be attached as 69.Li cd0 70the next, 71.Li cd1 , 72etc. 73Beginning in 74.Fx 2.1 75it is possible to specify what cd unit a device should 76come on line as; refer to 77.Xr scsi 4 78for details on kernel configuration. 79.Pp 80The system utility 81.Xr disklabel 8 82may be used to read the synthesized 83disk label 84structure, which will contain correct figures for the size of the 85.Tn CD-ROM 86should that information be required. 87.Pp 88.Sh KERNEL CONFIGURATION 89Any number of 90.Tn CD-ROM 91devices may be attached to the system regardless of system 92configuration as all resources are dynamically allocated. 93.Sh IOCTLS 94The following 95.Xr ioctl 2 96calls which apply to 97.Tn SCSI 98.Tn CD-ROM 99drives are defined 100in the header files 101.Aq Pa sys/cdio.h 102and 103.Aq Pa sys/disklabel.h . 104.Pp 105.Bl -tag -width CDIOCREADSUBCHANNEL -compact 106.It Dv DIOCGDINFO 107.It Dv DIOCSDINFO 108.Pq Li "struct disklabel" 109Read or write the in-core copy of the disklabel for the 110drive. The disklabel is initialized with information 111read from the scsi inquiry commands, and should be the same as 112the information printed at boot. This structure is defined in 113.Xr disklabel 5 . 114 115.It Dv CDIOCCAPABILITY 116.Pq Li "struct ioc_capability" 117Retrieve information from the drive on what features it supports. The 118information is returned in the following structure: 119.Bd -literal -offset indent 120struct ioc_capability { 121 u_long play_function; 122#define CDDOPLAYTRK 0x00000001 123 /* Can play tracks/index */ 124#define CDDOPLAYMSF 0x00000002 125 /* Can play msf to msf */ 126#define CDDOPLAYBLOCKS 0x00000004 127 /* Can play range of blocks */ 128#define CDDOPAUSE 0x00000100 129 /* Output can be paused */ 130#define CDDORESUME 0x00000200 131 /* Output can be resumed */ 132#define CDDORESET 0x00000400 133 /* Drive can be completely reset */ 134#define CDDOSTART 0x00000800 135 /* Audio can be started */ 136#define CDDOSTOP 0x00001000 137 /* Audio can be stopped */ 138#define CDDOPITCH 0x00002000 139 /* Audio pitch can be changed */ 140 141 u_long routing_function; 142#define CDREADVOLUME 0x00000001 143 /* Volume settings can be read */ 144#define CDSETVOLUME 0x00000002 145 /* Volume settings can be set */ 146#define CDSETMONO 0x00000100 147 /* Output can be set to mono */ 148#define CDSETSTEREO 0x00000200 149 /* Output can be set to stereo (def) */ 150#define CDSETLEFT 0x00000400 151 /* Output can be set to left only */ 152#define CDSETRIGHT 0x00000800 153 /* Output can be set to right only */ 154#define CDSETMUTE 0x00001000 155 /* Output can be muted */ 156#define CDSETPATCH 0x00008000 157 /* Direct routing control allowed */ 158 159 u_long special_function; 160#define CDDOEJECT 0x00000001 161 /* The tray can be opened */ 162#define CDDOCLOSE 0x00000002 163 /* The tray can be closed */ 164#define CDDOLOCK 0x00000004 165 /* The tray can be locked */ 166#define CDREADHEADER 0x00000100 167 /* Can read Table of Contents */ 168#define CDREADENTRIES 0x00000200 169 /* Can read TOC Entries */ 170#define CDREADSUBQ 0x00000200 171 /* Can read Subchannel info */ 172#define CDREADRW 0x00000400 173 /* Can read subcodes R-W */ 174#define CDHASDEBUG 0x00004000 175 /* The tray has dynamic debugging */ 176}; 177.Ed 178.It Dv CDIOCPLAYTRACKS 179.Pq Li "struct ioc_play_track" 180Start audio playback given a track address and length. The structure 181is defined as follows: 182.Bd -literal -offset indent 183struct ioc_play_track 184{ 185 u_char start_track; 186 u_char start_index; 187 u_char end_track; 188 u_char end_index; 189}; 190.Ed 191 192.It Dv CDIOCPLAYBLOCKS 193.Pq Li "struct ioc_play_blocks" 194Start audio playback given a block address and length. The structure 195is defined as follows: 196.Bd -literal -offset indent 197struct ioc_play_blocks 198{ 199 int blk; 200 int len; 201}; 202.Ed 203 204.It Dv CDIOCPLAYMSF 205.Pq Li "struct ioc_play_msf" 206Start audio playback given a `minutes-seconds-frames' address and 207length. The structure is defined as follows: 208.Bd -literal -offset indent 209struct ioc_play_msf 210{ 211 u_char start_m; 212 u_char start_s; 213 u_char start_f; 214 u_char end_m; 215 u_char end_s; 216 u_char end_f; 217}; 218.Ed 219 220.It Dv CDIOCREADSUBCHANNEL 221.Pq Li "struct ioc_read_subchannel" 222Read information from the subchannel at the location specified by this 223structure: 224.Bd -literal -offset indent 225struct ioc_read_subchannel { 226 u_char address_format; 227#define CD_LBA_FORMAT 1 228#define CD_MSF_FORMAT 2 229 u_char data_format; 230#define CD_SUBQ_DATA 0 231#define CD_CURRENT_POSITION 1 232#define CD_MEDIA_CATALOG 2 233#define CD_TRACK_INFO 3 234 u_char track; 235 int data_len; 236 struct cd_sub_channel_info *data; 237}; 238.Ed 239 240.It Dv CDIOREADTOCHEADER 241.Pq Li "struct ioc_toc_header" 242Return summary information about the table of contents for the mounted 243.Tn CD-ROM . 244The information is returned into the following structure: 245.Bd -literal -offset indent 246struct ioc_toc_header { 247 u_short len; 248 u_char starting_track; 249 u_char ending_track; 250}; 251.Ed 252 253.It Dv CDIOREADTOCENTRYS 254.Pq Li "struct ioc_read_toc_entry" 255Return information from the table of contents entries mentioned. (Yes, this 256command name is misspelled.) The argument structure is defined as follows: 257.Bd -literal -offset indent 258struct ioc_read_toc_entry { 259 u_char address_format; 260 u_char starting_track; 261 u_short data_len; 262 struct cd_toc_entry *data; 263}; 264.Ed 265The requested data is written into an area of size 266.Li data_len 267and pointed to by 268.Li data . 269 270.It Dv CDIOCSETPATCH 271.Pq Li "struct ioc_patch" 272Attach various audio channels to various output channels. The 273argument structure is defined thusly: 274.Bd -literal -offset indent 275struct ioc_patch { 276 u_char patch[4]; 277 /* one for each channel */ 278}; 279.Ed 280 281.It Dv CDIOCGETVOL 282.It Dv CDIOCSETVOL 283.Pq Li "struct ioc_vol" 284Get (set) information about the volume settings of the output channels. The 285argument structure is as follows: 286.Bd -literal -offset indent 287struct ioc_vol 288{ 289 u_char vol[4]; 290 /* one for each channel */ 291}; 292.Ed 293 294.It Dv CDIOCSETMONO 295Patch all output channels to all source channels. 296 297.It Dv CDIOCSETSTEREO 298Patch left source channel to the left output channel and the right 299source channel to the right output channel. 300 301.It Dv CDIOCSETMUTE 302Mute output without changing the volume settings. 303 304.It Dv CDIOCSETLEFT 305.It Dv CDIOCSETRIGHT 306Attach both output channels to the left (right) source channel. 307 308.It Dv CDIOCSETDEBUG 309.It Dv CDIOCCLRDEBUG 310Turn on (off) debugging for the appropriate device. 311 312.It Dv CDIOCPAUSE 313.It Dv CDIOCRESUME 314Pause (resume) audio play, without resetting the location of the read-head. 315 316.It Dv CDIOCRESET 317Reset the drive. 318 319.It Dv CDIOCSTART 320.It Dv CDIOCSTOP 321Tell the drive to spin-up (-down) the 322.Tn CD-ROM . 323 324.It Dv CDIOCALLOW 325.It Dv CDIOCPREVENT 326Tell the drive to allow (prevent) manual ejection of the 327.Tn CD-ROM 328disc. Not all drives support this feature. 329 330.It Dv CDIOCEJECT 331Eject the 332.Tn CD-ROM . 333 334.It Dv CDIOCCLOSE 335Tell the drive to close its door and load the media. Not all drives 336support this feature. 337 338.It Dv CDIOCPITCH 339.Pq Li "struct ioc_pitch" 340For drives that support it, this command instructs the drive to play 341the audio at a faster or slower rate than normal. Values of 342.Li speed 343between -32767 and -1 result in slower playback; a zero value 344indicates normal speed; and values from 1 to 32767 give faster 345playback. Drives with less than 16 bits of resolution will silently 346ignore less-significant bits. The structure is defined thusly: 347.Bd -literal -offset indent 348struct ioc_pitch 349{ 350 short speed; 351}; 352.Ed 353.El 354.Pp 355In addition the general 356.Xr scsi 4 357ioctls may be used with the 358.Nm 359driver, if used against the `whole disk' partition (i.e. 360.Pa /dev/rcd0c ) . 361.Sh NOTES 362When a 363.Tn CD-ROM 364is changed in a drive controlled by the 365.Nm 366driver, then the act of changing the media will invalidate the 367disklabel and information held within the kernel. To stop corruption, 368all accesses to the device will be discarded until there are no more 369open file descriptors referencing the device. During this period, all 370new open attempts will be rejected. When no more open file descriptors 371reference the device, the first next open will load a new set of 372parameters (including disklabel) for the drive. 373.Pp 374The audio code in the 375.Nm 376driver only support 377.Tn SCSI-2 378standard audio commands. Because many 379.Tn CD-ROM 380manufacturers have not followed the standard, there are many 381.Tn CD-ROM 382drives for which audio will not work. Some work is planned to support 383some of the more common `broken' 384.Tn CD-ROM 385drives; however, this is not yet under way. 386.Sh FILES 387.Bl -tag -width /dev/rcd[0-9][a-h] -compact 388.It Pa /dev/cd[0-9][a-h] 389block mode 390.Tn CD-ROM 391devices 392.It Pa /dev/rcd[0-9][a-h] 393raw mode 394.Tn CD-ROM 395devices 396.El 397.Sh DIAGNOSTICS 398None. 399.Sh SEE ALSO 400.Xr scsi 4 , 401.Xr sd 4 , 402.Xr disklabel 5 , 403.Xr disklabel 8 , 404.Xr cd 9 405.Sh BUGS 406The names of the structures used for the third argument to 407.Fn ioctl 408were poorly chosen, and a number of spelling errors have survived in 409the names of the 410.Fn ioctl 411commands. 412.Sh HISTORY 413This 414.Nm 415driver appeared in 386BSD 0.1. 416