1.\" $NetBSD: cd.4,v 1.16 2001/09/12 18:19:16 wiz 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 31.Sh NAME 32.Nm cd 33.Nd SCSI and ATAPI CD-ROM driver 34.Sh SYNOPSIS 35.Cd "cd* at scsibus? target ? lun ?" 36.Cd "cd1 at scsibus0 target 4 lun 0" 37.Cd "cd* at atapibus? drive ? flags 0x0000" 38.Sh DESCRIPTION 39The 40.Nm cd 41driver provides support for a Small Computer Systems Interface 42.Pq Tn SCSI 43bus and Advanced Technology Attachment Packet Interface 44.Pq Tn ATAPI 45Compact Disc-Read Only Memory 46.Pq Tn CD-ROM 47drive. 48In an attempt to look like a regular disk, the 49.Nm 50driver synthesizes a partition table, with one partition covering the entire 51.Tn CD-ROM . 52It is possible to modify this partition table using 53.Xr disklabel 8 , 54but it will only last until the 55.Tn CD-ROM 56is unmounted. 57In general the interfaces are similar to those described by 58.Xr wd 4 59and 60.Xr sd 4 . 61.Pp 62As the 63.Tn SCSI 64adapter is probed during boot, the 65.Tn SCSI 66bus is scanned for devices. 67Any devices found which answer as `Read-only' 68type devices will be `attached' to the 69.Nm 70driver. 71.Pp 72For the use of flags with ATAPI devices, see 73.Xr wd 4 . 74.Pp 75The system utility 76.Xr disklabel 8 77may be used to read the synthesized 78disk label 79structure, which will contain correct figures for the size of the 80.Tn CD-ROM 81should that information be required. 82.Sh KERNEL CONFIGURATION 83Any number of 84.Tn CD-ROM 85devices may be attached to the system regardless of system 86configuration as all resources are dynamically allocated. 87.Sh IOCTLS 88The following 89.Xr ioctl 2 90calls which apply to 91.Tn SCSI 92.Tn CD-ROM 93drives are defined 94in the header files 95.Aq Pa sys/cdio.h 96and 97.Aq Pa sys/disklabel.h . 98.Pp 99.Bl -tag -width CDIOCREADSUBCHANNEL 100.It Dv DIOCGDINFO 101.It Dv DIOCSDINFO 102.Pq Li "struct disklabel" 103Read or write the in-core copy of the disklabel for the 104drive. 105The disklabel is initialized with information 106read from the 107.Tn SCSI 108inquiry commands, and should be the same as 109the information printed at boot. 110This structure is defined in 111.Xr disklabel 5 . 112.\".It Dv CDIOCCAPABILITY 113.\".Pq Li "struct ioc_capability" 114.\"Retrieve information from the drive on what features it supports. 115.\"The information is returned in the following structure: 116.\".Bd -literal -offset indent 117.\"struct ioc_capability { 118.\" u_long play_function; 119.\"#define CDDOPLAYTRK 0x00000001 120.\" /* Can play tracks/index */ 121.\"#define CDDOPLAYMSF 0x00000002 122.\" /* Can play msf to msf */ 123.\"#define CDDOPLAYBLOCKS 0x00000004 124.\" /* Can play range of blocks */ 125.\"#define CDDOPAUSE 0x00000100 126.\" /* Output can be paused */ 127.\"#define CDDORESUME 0x00000200 128.\" /* Output can be resumed */ 129.\"#define CDDORESET 0x00000400 130.\" /* Drive can be completely reset */ 131.\"#define CDDOSTART 0x00000800 132.\" /* Audio can be started */ 133.\"#define CDDOSTOP 0x00001000 134.\" /* Audio can be stopped */ 135.\"#define CDDOPITCH 0x00002000 136.\" /* Audio pitch can be changed */ 137.\" 138.\" u_long routing_function; 139.\"#define CDREADVOLUME 0x00000001 140.\" /* Volume settings can be read */ 141.\"#define CDSETVOLUME 0x00000002 142.\" /* Volume settings can be set */ 143.\"#define CDSETMONO 0x00000100 144.\" /* Output can be set to mono */ 145.\"#define CDSETSTEREO 0x00000200 146.\" /* Output can be set to stereo (def) */ 147.\"#define CDSETLEFT 0x00000400 148.\" /* Output can be set to left only */ 149.\"#define CDSETRIGHT 0x00000800 150.\" /* Output can be set to right only */ 151.\"#define CDSETMUTE 0x00001000 152.\" /* Output can be muted */ 153.\"#define CDSETPATCH 0x00008000 154.\" /* Direct routing control allowed */ 155.\" 156.\" u_long special_function; 157.\"#define CDDOEJECT 0x00000001 158.\" /* The tray can be opened */ 159.\"#define CDDOCLOSE 0x00000002 160.\" /* The tray can be closed */ 161.\"#define CDDOLOCK 0x00000004 162.\" /* The tray can be locked */ 163.\"#define CDREADHEADER 0x00000100 164.\" /* Can read Table of Contents */ 165.\"#define CDREADENTRIES 0x00000200 166.\" /* Can read TOC Entries */ 167.\"#define CDREADSUBQ 0x00000200 168.\" /* Can read Subchannel info */ 169.\"#define CDREADRW 0x00000400 170.\" /* Can read subcodes R-W */ 171.\"#define CDHASDEBUG 0x00004000 172.\" /* The tray has dynamic debugging */ 173.\"}; 174.\".Ed 175.It Dv CDIOCPLAYTRACKS 176.Pq Li "struct ioc_play_track" 177Start audio playback given a track address and length. 178The structure is defined as follows: 179.Bd -literal -offset indent 180struct ioc_play_track 181{ 182 u_char start_track; 183 u_char start_index; 184 u_char end_track; 185 u_char end_index; 186}; 187.Ed 188.It Dv CDIOCPLAYBLOCKS 189.Pq Li "struct ioc_play_blocks" 190Start audio playback given a block address and length. 191The structure is defined as follows: 192.Bd -literal -offset indent 193struct ioc_play_blocks 194{ 195 int blk; 196 int len; 197}; 198.Ed 199.It Dv CDIOCPLAYMSF 200.Pq Li "struct ioc_play_msf" 201Start audio playback given a `minutes-seconds-frames' address and length. 202The structure is defined as follows: 203.Bd -literal -offset indent 204struct ioc_play_msf 205{ 206 u_char start_m; 207 u_char start_s; 208 u_char start_f; 209 u_char end_m; 210 u_char end_s; 211 u_char end_f; 212}; 213.Ed 214.It Dv CDIOCREADSUBCHANNEL 215.Pq Li "struct ioc_read_subchannel" 216Read information from the subchannel at the location specified by this 217structure: 218.Bd -literal -offset indent 219struct ioc_read_subchannel { 220 u_char address_format; 221#define CD_LBA_FORMAT 1 222#define CD_MSF_FORMAT 2 223 u_char data_format; 224#define CD_SUBQ_DATA 0 225#define CD_CURRENT_POSITION 1 226#define CD_MEDIA_CATALOG 2 227#define CD_TRACK_INFO 3 228 u_char track; 229 int data_len; 230 struct cd_sub_channel_info *data; 231}; 232.Ed 233.It Dv CDIOREADTOCHEADER 234.Pq Li "struct ioc_toc_header" 235Return summary information about the table of contents for the mounted 236.Tn CD-ROM . 237The information is returned into the following structure: 238.Bd -literal -offset indent 239struct ioc_toc_header { 240 u_short len; 241 u_char starting_track; 242 u_char ending_track; 243}; 244.Ed 245.It Dv CDIOREADTOCENTRYS 246.Pq Li "struct ioc_read_toc_entry" 247Return information from the table of contents entries mentioned. 248(Yes, this command name is misspelled). 249The argument structure is defined as follows: 250.Bd -literal -offset indent 251struct ioc_read_toc_entry { 252 u_char address_format; 253 u_char starting_track; 254 u_short data_len; 255 struct cd_toc_entry *data; 256}; 257.Ed 258The requested data is written into an area of size 259.Li data_len 260and pointed to by 261.Li data . 262.It Dv CDIOCSETPATCH 263.Pq Li "struct ioc_patch" 264Attach various audio channels to various output channels. 265The argument structure is defined thusly: 266.Bd -literal -offset indent 267struct ioc_patch { 268 u_char patch[4]; 269 /* one for each channel */ 270}; 271.Ed 272.It Dv CDIOCGETVOL 273.It Dv CDIOCSETVOL 274.Pq Li "struct ioc_vol" 275Get (set) information about the volume settings of the output channels. 276The argument structure is as follows: 277.Bd -literal -offset indent 278struct ioc_vol 279{ 280 u_char vol[4]; 281 /* one for each channel */ 282}; 283.Ed 284.It Dv CDIOCSETMONO 285Patch all output channels to all source channels. 286.It Dv CDIOCSETSTEREO 287Patch left source channel to the left output channel and the right 288source channel to the right output channel. 289.It Dv CDIOCSETMUTE 290Mute output without changing the volume settings. 291.It Dv CDIOCSETLEFT 292.It Dv CDIOCSETRIGHT 293Attach both output channels to the left (right) source channel. 294.It Dv CDIOCSETDEBUG 295.It Dv CDIOCCLRDEBUG 296Turn on (off) debugging for the appropriate device. 297.It Dv CDIOCPAUSE 298.It Dv CDIOCRESUME 299Pause (resume) audio play, without resetting the location of the read-head. 300.It Dv CDIOCRESET 301Reset the drive. 302.It Dv CDIOCSTART 303.It Dv CDIOCSTOP 304Tell the drive to spin-up (-down) the 305.Tn CD-ROM . 306.It Dv CDIOCALLOW 307.It Dv CDIOCPREVENT 308Tell the drive to allow (prevent) manual ejection of the 309.Tn CD-ROM 310disc. 311Not all drives support this feature. 312.It Dv CDIOCEJECT 313Eject the 314.Tn CD-ROM . 315.It Dv CDIOCLOADUNLOAD 316Cause the ATAPI changer to load or unload discs. 317.It Dv CDIOCCLOSE 318Tell the drive to close its door and load the media. 319Not all drives support this feature. 320.\" 321.\".It Dv CDIOCPITCH 322.\".Pq Li "struct ioc_pitch" 323.\"For drives that support it, this command instructs the drive to play 324.\"the audio at a faster or slower rate than normal. 325.\"Values of 326.\".Li speed 327.\"between -32767 and -1 result in slower playback; a zero value 328.\"indicates normal speed; and values from 1 to 32767 give faster playback. 329.\"Drives with less than 16 bits of resolution will silently 330.\"ignore less-significant bits. 331.\"The structure is defined thusly: 332.\".Bd -literal -offset indent 333.\"struct ioc_pitch 334.\"{ 335.\" short speed; 336.\"}; 337.\".Ed 338.El 339.Pp 340In addition the general 341.Xr scsi 4 342ioctls may be used with the 343.Nm 344driver, if used against the `whole disk' partition (i.e. 345.Pa /dev/rcd0d 346for the bebox and i386 port, 347.Pa /dev/rcd0c 348for all other ports). 349.Sh NOTES 350When a 351.Tn CD-ROM 352is changed in a drive controlled by the 353.Nm 354driver, then the act of changing the media will invalidate the 355disklabel and information held within the kernel. 356To stop corruption, all accesses to the device will be discarded 357until there are no more open file descriptors referencing the device. 358During this period, all new open attempts will be rejected. 359When no more open file descriptors reference the device, the first 360next open will load a new set of parameters (including disklabel) 361for the drive. 362.Pp 363The audio code in the 364.Nm 365driver only support 366.Tn SCSI-2 367standard audio commands. 368Because many 369.Tn CD-ROM 370manufacturers have not followed the standard, there are many 371.Tn CD-ROM 372drives for which audio will not work. 373Some work is planned to support some of the more common `broken' 374.Tn CD-ROM 375drives; however, this is not yet under way. 376.Sh FILES 377.Bl -tag -width /dev/rcd[0-9][a-h] -compact 378.It Pa /dev/cd[0-9][a-h] 379block mode 380.Tn CD-ROM 381devices 382.It Pa /dev/rcd[0-9][a-h] 383raw mode 384.Tn CD-ROM 385devices 386.El 387.Sh DIAGNOSTICS 388None. 389.Sh SEE ALSO 390.Xr intro 4 , 391.Xr scsi 4 , 392.Xr sd 4 , 393.Xr wd 4 , 394.Xr disklabel 5 , 395.Xr disklabel 8 396.Sh HISTORY 397The 398.Nm 399driver appeared in 400.Tn 386BSD 0.1 Ns . 401.Sh BUGS 402The names of the structures used for the third argument to 403.Fn ioctl 404were poorly chosen, and a number of spelling errors have survived in 405the names of the 406.Fn ioctl 407commands. 408