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