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