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