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