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.\" $FreeBSD$ 27.\" 28.Dd October 10, 1998 29.Dt CD 4 30.Os 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 unit 0 37.Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" 38.Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"" 39.Sh DESCRIPTION 40The 41.Nm 42driver provides support for a 43.Tn SCSI 44.Tn CD-ROM 45(Compact Disc-Read Only Memory) drive. 46In an attempt to look like a regular disk, the 47.Nm 48driver synthesizes a partition table, with one partition covering the entire 49.Tn CD-ROM . 50It is possible to modify this partition table using 51.Xr disklabel 8 , 52but it will only last until the 53.Tn CD-ROM 54is unmounted. 55In general the interfaces are similar to those described by 56.Xr ad 4 57and 58.Xr da 4 . 59.Pp 60As the 61.Tn SCSI 62adapter is probed during boot, the 63.Tn SCSI 64bus is scanned for devices. 65Any devices found which answer as CDROM 66(type 5) or WORM (type 4) type devices will be `attached' to the 67.Nm 68driver. 69Prior to 70.Fx 2.1 , 71the first device found will be attached as 72.Li cd0 73the next, 74.Li cd1 , 75etc. 76Beginning in 77.Fx 2.1 78it is possible to specify what cd unit a device should 79come on line as; refer to 80.Xr scsi 4 81for details on kernel configuration. 82.Pp 83The system utility 84.Xr disklabel 8 85may be used to read the synthesized 86disk label 87structure, which will contain correct figures for the size of the 88.Tn CD-ROM 89should that information be required. 90.Sh KERNEL CONFIGURATION 91Any number of 92.Tn CD-ROM 93devices may be attached to the system regardless of system 94configuration as all resources are dynamically allocated. 95.Sh IOCTLS 96The following 97.Xr ioctl 2 98calls which apply to 99.Tn SCSI 100.Tn CD-ROM 101drives are defined 102in the header files 103.Aq Pa sys/cdio.h 104and 105.Aq Pa sys/disklabel.h . 106.Pp 107.Bl -tag -width CDIOCREADSUBCHANNEL 108.It Dv DIOCGDINFO 109.It Dv DIOCSDINFO 110.Pq Li "struct disklabel" 111Read or write the in-core copy of the disklabel for the 112drive. The disklabel is initialized with information 113read from the scsi inquiry commands, and should be the same as 114the information printed at boot. This structure is defined in 115.Xr disklabel 5 . 116.It Dv CDIOCCAPABILITY 117.Pq Li "struct ioc_capability" 118Retrieve information from the drive on what features it supports. The 119information is returned in the following structure: 120.Bd -literal -offset indent 121struct ioc_capability { 122 u_long play_function; 123#define CDDOPLAYTRK 0x00000001 124 /* Can play tracks/index */ 125#define CDDOPLAYMSF 0x00000002 126 /* Can play msf to msf */ 127#define CDDOPLAYBLOCKS 0x00000004 128 /* Can play range of blocks */ 129#define CDDOPAUSE 0x00000100 130 /* Output can be paused */ 131#define CDDORESUME 0x00000200 132 /* Output can be resumed */ 133#define CDDORESET 0x00000400 134 /* Drive can be completely reset */ 135#define CDDOSTART 0x00000800 136 /* Audio can be started */ 137#define CDDOSTOP 0x00001000 138 /* Audio can be stopped */ 139#define CDDOPITCH 0x00002000 140 /* Audio pitch can be changed */ 141 142 u_long routing_function; 143#define CDREADVOLUME 0x00000001 144 /* Volume settings can be read */ 145#define CDSETVOLUME 0x00000002 146 /* Volume settings can be set */ 147#define CDSETMONO 0x00000100 148 /* Output can be set to mono */ 149#define CDSETSTEREO 0x00000200 150 /* Output can be set to stereo (def) */ 151#define CDSETLEFT 0x00000400 152 /* Output can be set to left only */ 153#define CDSETRIGHT 0x00000800 154 /* Output can be set to right only */ 155#define CDSETMUTE 0x00001000 156 /* Output can be muted */ 157#define CDSETPATCH 0x00008000 158 /* Direct routing control allowed */ 159 160 u_long special_function; 161#define CDDOEJECT 0x00000001 162 /* The tray can be opened */ 163#define CDDOCLOSE 0x00000002 164 /* The tray can be closed */ 165#define CDDOLOCK 0x00000004 166 /* The tray can be locked */ 167#define CDREADHEADER 0x00000100 168 /* Can read Table of Contents */ 169#define CDREADENTRIES 0x00000200 170 /* Can read TOC Entries */ 171#define CDREADSUBQ 0x00000200 172 /* Can read Subchannel info */ 173#define CDREADRW 0x00000400 174 /* Can read subcodes R-W */ 175#define CDHASDEBUG 0x00004000 176 /* The tray has dynamic debugging */ 177}; 178.Ed 179.It Dv CDIOCPLAYTRACKS 180.Pq Li "struct ioc_play_track" 181Start audio playback given a track address and length. The structure 182is defined as follows: 183.Bd -literal -offset indent 184struct ioc_play_track 185{ 186 u_char start_track; 187 u_char start_index; 188 u_char end_track; 189 u_char end_index; 190}; 191.Ed 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.It Dv CDIOCPLAYMSF 204.Pq Li "struct ioc_play_msf" 205Start audio playback given a `minutes-seconds-frames' address and 206length. The structure is defined as follows: 207.Bd -literal -offset indent 208struct ioc_play_msf 209{ 210 u_char start_m; 211 u_char start_s; 212 u_char start_f; 213 u_char end_m; 214 u_char end_s; 215 u_char end_f; 216}; 217.Ed 218.It Dv CDIOCREADSUBCHANNEL 219.Pq Li "struct ioc_read_subchannel" 220Read information from the subchannel at the location specified by this 221structure: 222.Bd -literal -offset indent 223struct ioc_read_subchannel { 224 u_char address_format; 225#define CD_LBA_FORMAT 1 226#define CD_MSF_FORMAT 2 227 u_char data_format; 228#define CD_SUBQ_DATA 0 229#define CD_CURRENT_POSITION 1 230#define CD_MEDIA_CATALOG 2 231#define CD_TRACK_INFO 3 232 u_char track; 233 int data_len; 234 struct cd_sub_channel_info *data; 235}; 236.Ed 237.It Dv CDIOREADTOCHEADER 238.Pq Li "struct ioc_toc_header" 239Return summary information about the table of contents for the mounted 240.Tn CD-ROM . 241The information is returned into the following structure: 242.Bd -literal -offset indent 243struct ioc_toc_header { 244 u_short len; 245 u_char starting_track; 246 u_char ending_track; 247}; 248.Ed 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.It Dv CDIOCSETPATCH 266.Pq Li "struct ioc_patch" 267Attach various audio channels to various output channels. The 268argument structure is defined thusly: 269.Bd -literal -offset indent 270struct ioc_patch { 271 u_char patch[4]; 272 /* one for each channel */ 273}; 274.Ed 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.It Dv CDIOCSETMONO 288Patch all output channels to all source channels. 289.It Dv CDIOCSETSTEREO 290Patch left source channel to the left output channel and the right 291source channel to the right output channel. 292.It Dv CDIOCSETMUTE 293Mute output without changing the volume settings. 294.It Dv CDIOCSETLEFT 295.It Dv CDIOCSETRIGHT 296Attach both output channels to the left (right) source channel. 297.It Dv CDIOCSETDEBUG 298.It Dv CDIOCCLRDEBUG 299Turn on (off) debugging for the appropriate device. 300.It Dv CDIOCPAUSE 301.It Dv CDIOCRESUME 302Pause (resume) audio play, without resetting the location of the read-head. 303.It Dv CDIOCRESET 304Reset the drive. 305.It Dv CDIOCSTART 306.It Dv CDIOCSTOP 307Tell the drive to spin-up (-down) the 308.Tn CD-ROM . 309.It Dv CDIOCALLOW 310.It Dv CDIOCPREVENT 311Tell the drive to allow (prevent) manual ejection of the 312.Tn CD-ROM 313disc. Not all drives support this feature. 314.It Dv CDIOCEJECT 315Eject the 316.Tn CD-ROM . 317.It Dv CDIOCCLOSE 318Tell the drive to close its door and load the media. Not all drives 319support this feature. 320.It Dv CDIOCPITCH 321.Pq Li "struct ioc_pitch" 322For drives that support it, this command instructs the drive to play 323the audio at a faster or slower rate than normal. Values of 324.Li speed 325between -32767 and -1 result in slower playback; a zero value 326indicates normal speed; and values from 1 to 32767 give faster 327playback. Drives with less than 16 bits of resolution will silently 328ignore less-significant bits. The structure is defined thusly: 329.Bd -literal -offset indent 330struct ioc_pitch 331{ 332 short speed; 333}; 334.Ed 335.El 336.Sh NOTES 337When a 338.Tn CD-ROM 339is changed in a drive controlled by the 340.Nm 341driver, then the act of changing the media will invalidate the 342disklabel and information held within the kernel. To stop corruption, 343all accesses to the device will be discarded until there are no more 344open file descriptors referencing the device. During this period, all 345new open attempts will be rejected. When no more open file descriptors 346reference the device, the first next open will load a new set of 347parameters (including disklabel) for the drive. 348.Pp 349The audio code in the 350.Nm 351driver only support 352.Tn SCSI-2 353standard audio commands. 354Because many 355.Tn CD-ROM 356manufacturers have not followed the standard, there are many 357.Tn CD-ROM 358drives for which audio will not work. 359Some work is planned to support 360some of the more common `broken' 361.Tn CD-ROM 362drives; however, this is not yet under way. 363.Sh CHANGER OPERATION 364This driver has built-in support for LUN-based CD changers. A LUN-based CD 365changer is a drive that can hold two or more CDs, but only has one CD 366player mechanism. Each CD in the drive shows up as a separate logical unit 367on the 368.Tn SCSI 369bus. The 370.Nm 371driver automatically recognizes LUN-based changers, and routes commands for 372changers through an internal scheduler. The scheduler prevents changer 373"thrashing", which is caused by sending commands to different LUNs in the 374changer at the same time. 375.Pp 376The scheduler honors minimum and maximum time 377quanta that the driver will spend on a particular LUN. The minimum time 378is the guaranteed minimum amount of time that the driver will spend on a 379given LUN, even if there is no oustanding I/O for that LUN. The maximum 380time is the maximum amount of time the changer will spend on a LUN if there 381is oustdanding I/O for another LUN. If there is no outstanding I/O for 382another LUN, the driver will allow indefinite access to a given LUN. 383.Pp 384The minimum and maximum time quanta are configurable via kernel options and 385also via sysctl variables. The kernel options are: 386.Pp 387.Bl -item -compact 388.It 389.Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" 390.It 391.Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""" 392.El 393.Pp 394The sysctl variables are: 395.Pp 396.Bl -item -compact 397.It 398.Va kern.cam.cd.changer.min_busy_seconds 399.It 400.Va kern.cam.cd.changer.max_busy_seconds 401.El 402.Pp 403It is suggested that the user try experimenting with the minimum and 404maximum timeouts via the sysctl variables to arrive at the proper values 405for your changer. Once you have settled on the proper timeouts for your 406changer, you can then put them in your kernel config file. 407.Pp 408If your system does have a LUN-based changer, you may notice that the 409probe messages for the various LUNs of the changer will continue to appear 410while the boot process is going on. This is normal, and is caused by the 411changer scheduling code. 412.Sh FILES 413.Bl -tag -width /dev/cd[0-9][a-h] -compact 414.It Pa /dev/cd[0-9][a-h] 415raw mode 416.Tn CD-ROM 417devices 418.El 419.Sh DIAGNOSTICS 420None. 421.Sh SEE ALSO 422.Xr da 4 , 423.Xr scsi 4 , 424.Xr disklabel 5 , 425.Xr disklabel 8 , 426.Xr cd 9 427.Sh BUGS 428The names of the structures used for the third argument to 429.Fn ioctl 430were poorly chosen, and a number of spelling errors have survived in 431the names of the 432.Fn ioctl 433commands. 434.Pp 435There is no mechanism currently to set different minimum and maximum 436timeouts for different CD changers; the timeout values set by the kernel 437options or the sysctl variables apply to all LUN-based CD changers in the 438system. It is possible to implement such support, but the sysctl 439impelmentation at least would be rather inelegant, because of the current 440inability of the sysctl code to handle the addition of nodes after compile 441time. Thus, it would take one dynamically sized sysctl variable and a 442userland utility to get/set the timeout values. Implementation of separate 443timeouts for different CD devices in the kernel config file would likely 444require modification of 445.Xr config 8 446to support the two timeouts when hardwiring 447.Nm 448devices. 449.Sh HISTORY 450This 451.Nm 452driver is based upon the 453.Nm 454driver written by Julian Elischer, which appeared in 455.Bx 386 0.1 . 456The 457CAM version of the 458.Nm 459driver was written by Kenneth Merry and first appeared in 460.Fx 3.0 . 461