share/man/man4/cd.4

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