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 April 8, 2022 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.Sh DESCRIPTION 37The 38.Nm 39driver provides support for a 40.Tn SCSI 41.Tn CD-ROM 42(Compact Disc-Read Only Memory) drive. 43In an attempt to look like a regular disk, the 44.Nm 45driver synthesizes a partition table, with one partition covering the entire 46.Tn CD-ROM . 47It is possible to modify this partition table using 48.Xr disklabel 8 , 49but it will only last until the 50.Tn CD-ROM 51is unmounted. 52In general the interfaces are similar to those described by 53.Xr ada 4 54and 55.Xr da 4 . 56.Pp 57As the 58.Tn SCSI 59adapter is probed during boot, the 60.Tn SCSI 61bus is scanned for devices. 62Any devices found which answer as CDROM 63(type 5) or WORM (type 4) type 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.Sh KERNEL CONFIGURATION 88Any number of 89.Tn CD-ROM 90devices may be attached to the system regardless of system 91configuration as all resources are dynamically allocated. 92.Sh IOCTLS 93The following 94.Xr ioctl 2 95calls which apply to 96.Tn SCSI 97.Tn CD-ROM 98drives are defined 99in the header files 100.In sys/cdio.h 101and 102.In sys/disklabel.h . 103.Bl -tag -width CDIOCREADSUBCHANNEL 104.It Dv CDIOCPLAYTRACKS 105.Pq Li "struct ioc_play_track" 106Start audio playback given a track address and length. 107The structure is defined as follows: 108.Bd -literal -offset indent 109struct ioc_play_track 110{ 111 u_char start_track; 112 u_char start_index; 113 u_char end_track; 114 u_char end_index; 115}; 116.Ed 117.It Dv CDIOCPLAYBLOCKS 118.Pq Li "struct ioc_play_blocks" 119Start audio playback given a block address and length. 120The structure is defined as follows: 121.Bd -literal -offset indent 122struct ioc_play_blocks 123{ 124 int blk; 125 int len; 126}; 127.Ed 128.It Dv CDIOCPLAYMSF 129.Pq Li "struct ioc_play_msf" 130Start audio playback given a `minutes-seconds-frames' address and 131length. 132The structure is defined as follows: 133.Bd -literal -offset indent 134struct ioc_play_msf 135{ 136 u_char start_m; 137 u_char start_s; 138 u_char start_f; 139 u_char end_m; 140 u_char end_s; 141 u_char end_f; 142}; 143.Ed 144.It Dv CDIOCREADSUBCHANNEL 145.Pq Li "struct ioc_read_subchannel" 146Read information from the subchannel at the location specified by this 147structure: 148.Bd -literal -offset indent 149struct ioc_read_subchannel { 150 u_char address_format; 151#define CD_LBA_FORMAT 1 152#define CD_MSF_FORMAT 2 153 u_char data_format; 154#define CD_SUBQ_DATA 0 155#define CD_CURRENT_POSITION 1 156#define CD_MEDIA_CATALOG 2 157#define CD_TRACK_INFO 3 158 u_char track; 159 int data_len; 160 struct cd_sub_channel_info *data; 161}; 162.Ed 163.It Dv CDIOREADTOCHEADER 164.Pq Li "struct ioc_toc_header" 165Return summary information about the table of contents for the mounted 166.Tn CD-ROM . 167The information is returned into the following structure: 168.Bd -literal -offset indent 169struct ioc_toc_header { 170 u_short len; 171 u_char starting_track; 172 u_char ending_track; 173}; 174.Ed 175.It Dv CDIOREADTOCENTRYS 176.Pq Li "struct ioc_read_toc_entry" 177Return information from the table of contents entries mentioned. 178.Pq Yes, this command name is misspelled. 179The argument structure is defined as follows: 180.Bd -literal -offset indent 181struct ioc_read_toc_entry { 182 u_char address_format; 183 u_char starting_track; 184 u_short data_len; 185 struct cd_toc_entry *data; 186}; 187.Ed 188The requested data is written into an area of size 189.Li data_len 190and pointed to by 191.Li data . 192.It Dv CDIOCSETPATCH 193.Pq Li "struct ioc_patch" 194Attach various audio channels to various output channels. 195The argument structure is defined thusly: 196.Bd -literal -offset indent 197struct ioc_patch { 198 u_char patch[4]; 199 /* one for each channel */ 200}; 201.Ed 202.It Dv CDIOCGETVOL 203.It Dv CDIOCSETVOL 204.Pq Li "struct ioc_vol" 205Get (set) information about the volume settings of the output channels. 206The argument structure is as follows: 207.Bd -literal -offset indent 208struct ioc_vol 209{ 210 u_char vol[4]; 211 /* one for each channel */ 212}; 213.Ed 214.It Dv CDIOCSETMONO 215Patch all output channels to all source channels. 216.It Dv CDIOCSETSTEREO 217Patch left source channel to the left output channel and the right 218source channel to the right output channel. 219.It Dv CDIOCSETMUTE 220Mute output without changing the volume settings. 221.It Dv CDIOCSETLEFT 222.It Dv CDIOCSETRIGHT 223Attach both output channels to the left (right) source channel. 224.It Dv CDIOCSETDEBUG 225.It Dv CDIOCCLRDEBUG 226Turn on (off) debugging for the appropriate device. 227.It Dv CDIOCPAUSE 228.It Dv CDIOCRESUME 229Pause (resume) audio play, without resetting the location of the read-head. 230.It Dv CDIOCRESET 231Reset the drive. 232.It Dv CDIOCSTART 233.It Dv CDIOCSTOP 234Tell the drive to spin-up (-down) the 235.Tn CD-ROM . 236.It Dv CDIOCALLOW 237.It Dv CDIOCPREVENT 238Tell the drive to allow (prevent) manual ejection of the 239.Tn CD-ROM 240disc. 241Not all drives support this feature. 242.It Dv CDIOCEJECT 243Eject the 244.Tn CD-ROM . 245.It Dv CDIOCCLOSE 246Tell the drive to close its door and load the media. 247Not all drives support this feature. 248.El 249.Sh NOTES 250When a 251.Tn CD-ROM 252is changed in a drive controlled by the 253.Nm 254driver, then the act of changing the media will invalidate the 255disklabel and information held within the kernel. 256To stop corruption, 257all accesses to the device will be discarded until there are no more 258open file descriptors referencing the device. 259During this period, all 260new open attempts will be rejected. 261When no more open file descriptors 262reference the device, the first next open will load a new set of 263parameters (including disklabel) for the drive. 264.Pp 265The audio code in the 266.Nm 267driver only support 268.Tn SCSI-2 269standard audio commands. 270As many 271.Tn CD-ROM 272manufacturers have not followed the standard, there are many 273.Tn CD-ROM 274drives for which audio will not work. 275Some work is planned to support 276some of the more common `broken' 277.Tn CD-ROM 278drives; however, this is not yet under way. 279.Sh SYSCTL VARIABLES 280The following variables are available as both 281.Xr sysctl 8 282variables and 283.Xr loader 8 284tunables: 285.Bl -tag -width 12 286.It kern.cam.cd.retry_count 287.Pp 288This variable determines how many times the 289.Nm 290driver will retry a READ or WRITE command. 291This does not affect the number of retries used during probe time or for 292the 293.Nm 294driver dump routine. 295This value currently defaults to 4. 296.It kern.cam.cd.%d.minimum_cmd_size 297.Pp 298The 299.Nm 300driver attempts to automatically determine whether the drive it is talking 301to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations. 302Many 303.Tn SCSI 304drives only support 6 byte commands, and 305.Tn ATAPI 306drives only support 10 byte commands. 307The 308.Nm 309driver first attempts to determine whether the protocol in use typically 310supports 6 byte commands by issuing a CAM Path Inquiry CCB. 311It will then default to 6 byte or 10 byte commands as appropriate. 312After that, the 313.Nm 314driver defaults to using 6 byte commands (assuming the protocol the drive 315speaks claims to support 6 byte commands), until one fails with a 316.Tn SCSI 317ILLEGAL REQUEST error. 318Then it tries the 10 byte version of the command to 319see if that works instead. 320Users can change the default via per-drive 321sysctl variables and loader tunables. 322Where 323.Dq %d 324is the unit number of the drive in question. 325Valid minimum command sizes 326are 6 and 10. 327Any value above 6 will be rounded to 10, and any value below 3286 will be rounded to 6. 329.El 330.Sh FILES 331.Bl -tag -width /dev/cd[0-9][a-h] -compact 332.It Pa /dev/cd[0-9][a-h] 333raw mode 334.Tn CD-ROM 335devices 336.El 337.Sh DIAGNOSTICS 338None. 339.Sh SEE ALSO 340.Xr cam 4 , 341.Xr da 4 , 342.Xr cd9660 5 , 343.Xr disklabel 8 , 344.Xr cd 9 345.Sh HISTORY 346This 347.Nm 348driver is based upon the 349.Nm 350driver written by Julian Elischer, which appeared in 351.Bx 386 0.1 . 352The 353CAM version of the 354.Nm 355driver was written by Kenneth Merry and first appeared in 356.Fx 3.0 . 357.Sh BUGS 358The names of the structures used for the third argument to 359.Fn ioctl 360were poorly chosen, and a number of spelling errors have survived in 361the names of the 362.Fn ioctl 363commands. 364