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