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: src/share/man/man4/cd.4,v 1.17.2.8 2003/06/03 14:32:09 hmp Exp $ 27.\" 28.Dd February 18, 2019 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 84.Cd target 85string is followed by the device's standard 86.Tn SCSI 87device ID number. 88The 89.Cd unit 90string is followed by the Logical Unit Number 91.Pq Tn LUN 92of the 93.Tn SCSI 94device's sub-device, if any, or zero. 95.Pp 96The system utility 97.Xr disklabel 8 98may be used to read the synthesized 99disk label 100structure, which will contain correct figures for the size of the 101.Tn CD-ROM 102should that information be required. 103.Sh KERNEL CONFIGURATION 104Any number of 105.Tn CD-ROM 106devices may be attached to the system regardless of system 107configuration as all resources are dynamically allocated. 108.Sh IOCTLS 109The following 110.Xr ioctl 2 111calls which apply to 112.Tn SCSI 113.Tn CD-ROM 114drives are defined 115in the header files 116.In sys/cdio.h 117and 118.In sys/disklabel.h . 119.Bl -tag -width ".Dv CDIOCREADSUBCHANNEL" 120.It Dv DIOCGDINFO 121.It Dv DIOCSDINFO 122.Pq Li "struct disklabel" 123Read or write the in-core copy of the disklabel for the 124drive. 125The disklabel is initialized with information 126read from the scsi inquiry commands, and should be the same as 127the information printed at boot. 128This structure is defined in 129.Xr disklabel 5 . 130.It Dv CDIOCPLAYTRACKS 131.Pq Li "struct ioc_play_track" 132Start audio playback given a track address and length. 133The structure is defined as follows: 134.Bd -literal -offset indent 135struct ioc_play_track 136{ 137 u_char start_track; 138 u_char start_index; 139 u_char end_track; 140 u_char end_index; 141}; 142.Ed 143.It Dv CDIOCPLAYBLOCKS 144.Pq Li "struct ioc_play_blocks" 145Start audio playback given a block address and length. 146The structure is defined as follows: 147.Bd -literal -offset indent 148struct ioc_play_blocks 149{ 150 int blk; 151 int len; 152}; 153.Ed 154.It Dv CDIOCPLAYMSF 155.Pq Li "struct ioc_play_msf" 156Start audio playback given a `minutes-seconds-frames' address and 157length. 158The structure is defined as follows: 159.Bd -literal -offset indent 160struct ioc_play_msf 161{ 162 u_char start_m; 163 u_char start_s; 164 u_char start_f; 165 u_char end_m; 166 u_char end_s; 167 u_char end_f; 168}; 169.Ed 170.It Dv CDIOCREADSUBCHANNEL 171.Pq Li "struct ioc_read_subchannel" 172Read information from the subchannel at the location specified by this 173structure: 174.Bd -literal -offset indent 175struct ioc_read_subchannel { 176 u_char address_format; 177#define CD_LBA_FORMAT 1 178#define CD_MSF_FORMAT 2 179 u_char data_format; 180#define CD_SUBQ_DATA 0 181#define CD_CURRENT_POSITION 1 182#define CD_MEDIA_CATALOG 2 183#define CD_TRACK_INFO 3 184 u_char track; 185 int data_len; 186 struct cd_sub_channel_info *data; 187}; 188.Ed 189.It Dv CDIOREADTOCHEADER 190.Pq Li "struct ioc_toc_header" 191Return summary information about the table of contents for the mounted 192.Tn CD-ROM . 193The information is returned into the following structure: 194.Bd -literal -offset indent 195struct ioc_toc_header { 196 u_short len; 197 u_char starting_track; 198 u_char ending_track; 199}; 200.Ed 201.It Dv CDIOREADTOCENTRYS 202.Pq Li "struct ioc_read_toc_entry" 203Return information from the table of contents entries mentioned. 204.Pq Yes, this command name is misspelled. 205The argument structure is defined as follows: 206.Bd -literal -offset indent 207struct ioc_read_toc_entry { 208 u_char address_format; 209 u_char starting_track; 210 u_short data_len; 211 struct cd_toc_entry *data; 212}; 213.Ed 214The requested data is written into an area of size 215.Li data_len 216and pointed to by 217.Li data . 218.It Dv CDIOCSETPATCH 219.Pq Li "struct ioc_patch" 220Attach various audio channels to various output channels. 221The argument structure is defined thusly: 222.Bd -literal -offset indent 223struct ioc_patch { 224 u_char patch[4]; 225 /* one for each channel */ 226}; 227.Ed 228.It Dv CDIOCGETVOL 229.It Dv CDIOCSETVOL 230.Pq Li "struct ioc_vol" 231Get (set) information about the volume settings of the output channels. 232The argument structure is as follows: 233.Bd -literal -offset indent 234struct ioc_vol 235{ 236 u_char vol[4]; 237 /* one for each channel */ 238}; 239.Ed 240.It Dv CDIOCSETMONO 241Patch all output channels to all source channels. 242.It Dv CDIOCSETSTEREO 243Patch left source channel to the left output channel and the right 244source channel to the right output channel. 245.It Dv CDIOCSETMUTE 246Mute output without changing the volume settings. 247.It Dv CDIOCSETLEFT 248.It Dv CDIOCSETRIGHT 249Attach both output channels to the left (right) source channel. 250.It Dv CDIOCSETDEBUG 251.It Dv CDIOCCLRDEBUG 252Turn on (off) debugging for the appropriate device. 253.It Dv CDIOCPAUSE 254.It Dv CDIOCRESUME 255Pause (resume) audio play, without resetting the location of the read-head. 256.It Dv CDIOCRESET 257Reset the drive. 258.It Dv CDIOCSTART 259.It Dv CDIOCSTOP 260Tell the drive to spin-up (-down) the 261.Tn CD-ROM . 262.It Dv CDIOCALLOW 263.It Dv CDIOCPREVENT 264Tell the drive to allow (prevent) manual ejection of the 265.Tn CD-ROM 266disc. Not all drives support this feature. 267.It Dv CDIOCEJECT 268Eject the 269.Tn CD-ROM . 270.It Dv CDIOCCLOSE 271Tell the drive to close its door and load the media. 272Not all drives support this feature. 273.El 274.Sh NOTES 275When a 276.Tn CD-ROM 277is changed in a drive controlled by the 278.Nm 279driver, then the act of changing the media will invalidate the 280disklabel and information held within the kernel. 281To stop corruption, 282all accesses to the device will be discarded until there are no more 283open file descriptors referencing the device. 284During this period, all 285new open attempts will be rejected. 286When no more open file descriptors 287reference the device, the first next open will load a new set of 288parameters (including disklabel) for the drive. 289.Pp 290The audio code in the 291.Nm 292driver only support 293.Tn SCSI-2 294standard audio commands. 295Because many 296.Tn CD-ROM 297manufacturers have not followed the standard, there are many 298.Tn CD-ROM 299drives for which audio will not work. 300Some work is planned to support 301some of the more common `broken' 302.Tn CD-ROM 303drives; however, this is not yet under way. 304.Sh CHANGER OPERATION 305This driver has built-in support for LUN-based CD changers. 306A LUN-based CD 307changer is a drive that can hold two or more CDs, but only has one CD 308player mechanism. 309Each CD in the drive shows up as a separate logical unit 310on the 311.Tn SCSI 312bus. The 313.Nm 314driver automatically recognizes LUN-based changers, and routes commands for 315changers through an internal scheduler. 316The scheduler prevents changer 317"thrashing", which is caused by sending commands to different LUNs in the 318changer at the same time. 319.Pp 320The scheduler honors minimum and maximum time 321quanta that the driver will spend on a particular LUN. 322The minimum time 323is the guaranteed minimum amount of time that the driver will spend on a 324given LUN, even if there is no outstanding I/O for that LUN. 325The maximum 326time is the maximum amount of time the changer will spend on a LUN if there 327is outstanding I/O for another LUN. 328If there is no outstanding I/O for 329another LUN, the driver will allow indefinite access to a given LUN. 330.Pp 331The minimum and maximum time quanta are configurable via kernel options and 332also via sysctl variables. 333The kernel options are: 334.Pp 335.Bl -item -compact 336.It 337.Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" 338.It 339.Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""" 340.El 341.Pp 342The sysctl variables are: 343.Pp 344.Bl -item -compact 345.It 346.Va kern.cam.cd.changer.min_busy_seconds 347.It 348.Va kern.cam.cd.changer.max_busy_seconds 349.El 350.Pp 351It is suggested that the user try experimenting with the minimum and 352maximum timeouts via the sysctl variables to arrive at the proper values 353for your changer. 354Once you have settled on the proper timeouts for your 355changer, you can then put them in your kernel config file. 356.Pp 357If your system does have a LUN-based changer, you may notice that the 358probe messages for the various LUNs of the changer will continue to appear 359while the boot process is going on. 360This is normal, and is caused by the 361changer scheduling code. 362.Sh FILES 363.Bl -tag -width /dev/cd[0-9][a-h] -compact 364.It Pa /dev/cd[0-9][a-h] 365raw mode 366.Tn CD-ROM 367devices 368.El 369.Sh DIAGNOSTICS 370None. 371.Sh SEE ALSO 372.Xr da 4 , 373.Xr scsi 4 , 374.Xr disklabel 5 , 375.Xr disklabel 8 , 376.Xr cd 9 377.Sh HISTORY 378This 379.Nm 380driver is based upon the 381.Nm 382driver written by Julian Elischer, which appeared in 383.Bx 386 0.1 . 384The 385CAM version of the 386.Nm 387driver was written by Kenneth Merry and first appeared in 388.Fx 3.0 . 389.Sh BUGS 390The names of the structures used for the third argument to 391.Fn ioctl 392were poorly chosen, and a number of spelling errors have survived in 393the names of the 394.Fn ioctl 395commands. 396.Pp 397There is no mechanism currently to set different minimum and maximum 398timeouts for different CD changers; the timeout values set by the kernel 399options or the sysctl variables apply to all LUN-based CD changers in the 400system. 401It is possible to implement such support, but the sysctl 402implementation at least would be rather inelegant, because of the current 403inability of the sysctl code to handle the addition of nodes after compile 404time. 405Thus, it would take one dynamically sized sysctl variable and a 406userland utility to get/set the timeout values. 407Implementation of separate 408timeouts for different CD devices in the kernel config file would likely 409require modification of 410.Xr config 8 411to support the two timeouts when hardwiring 412.Nm 413devices. 414