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 January 8, 2009
  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 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
  37 .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver provides support for a
  42 .Tn SCSI
  43 .Tn CD-ROM
  44 (Compact Disc-Read Only Memory) drive.
  45 In an attempt to look like a regular disk, the
  46 .Nm
  47 driver synthesizes a partition table, with one partition covering the entire
  48 .Tn CD-ROM .
  49 It is possible to modify this partition table using
  50 .Xr disklabel 8 ,
  51 but it will only last until the
  52 .Tn CD-ROM
  53 is unmounted.
  54 In general the interfaces are similar to those described by
  55 .Xr ad 4
  56 and
  57 .Xr da 4 .
  58 .Pp
  59 As the
  60 .Tn SCSI
  61 adapter is probed during boot, the
  62 .Tn SCSI
  63 bus is scanned for devices.
  64 Any devices found which answer as CDROM
  65 (type 5) or WORM (type 4) type devices will be `attached' to the
  66 .Nm
  67 driver.
  68 Prior to
  69 .Fx 2.1 ,
  70 the first device found will be attached as
  71 .Li cd0
  72 the next,
  73 .Li cd1 ,
  74 etc.
  75 Beginning in
  76 .Fx 2.1
  77 it is possible to specify what cd unit a device should
  78 come on line as; refer to
  79 .Xr scsi 4
  80 for details on kernel configuration.
  81 .Pp
  82 The system utility
  83 .Xr disklabel 8
  84 may be used to read the synthesized
  85 disk label
  86 structure, which will contain correct figures for the size of the
  87 .Tn CD-ROM
  88 should that information be required.
  89 .Sh KERNEL CONFIGURATION
  90 Any number of
  91 .Tn CD-ROM
  92 devices may be attached to the system regardless of system
  93 configuration as all resources are dynamically allocated.
  94 .Sh IOCTLS
  95 The following
  96 .Xr ioctl 2
  97 calls which apply to
  98 .Tn SCSI
  99 .Tn CD-ROM
 100 drives are defined
 101 in the header files
 102 .In sys/cdio.h
 103 and
 104 .In sys/disklabel.h .
 105 .Pp
 106 .Bl -tag -width CDIOCREADSUBCHANNEL
 107 .It Dv DIOCGDINFO
 108 .It Dv DIOCSDINFO
 109 .Pq Li "struct disklabel"
 110 Read or write the in-core copy of the disklabel for the
 111 drive.
 112 The disklabel is initialized with information
 113 read from the scsi inquiry commands, and should be the same as
 114 the information printed at boot.
 115 This structure is defined in
 116 .Xr disklabel 5 .
 117 .It Dv CDIOCCAPABILITY
 118 .Pq Li "struct ioc_capability"
 119 Retrieve information from the drive on what features it supports.
 120 The information is returned in the following structure:
 121 .Bd -literal -offset indent
 122 struct ioc_capability {
 123         u_long  play_function;
 124 #define CDDOPLAYTRK     0x00000001
 125         /* Can play tracks/index */
 126 #define CDDOPLAYMSF     0x00000002
 127         /* Can play msf to msf */
 128 #define CDDOPLAYBLOCKS  0x00000004
 129         /* Can play range of blocks */
 130 #define CDDOPAUSE       0x00000100
 131         /* Output can be paused */
 132 #define CDDORESUME      0x00000200
 133         /* Output can be resumed */
 134 #define CDDORESET       0x00000400
 135         /* Drive can be completely reset */
 136 #define CDDOSTART       0x00000800
 137         /* Audio can be started */
 138 #define CDDOSTOP        0x00001000
 139         /* Audio can be stopped */
 140 #define CDDOPITCH       0x00002000
 141         /* Audio pitch can be changed */
 142
 143         u_long  routing_function;
 144 #define CDREADVOLUME    0x00000001
 145         /* Volume settings can be read */
 146 #define CDSETVOLUME     0x00000002
 147         /* Volume settings can be set */
 148 #define CDSETMONO       0x00000100
 149         /* Output can be set to mono */
 150 #define CDSETSTEREO     0x00000200
 151         /* Output can be set to stereo (def) */
 152 #define CDSETLEFT       0x00000400
 153         /* Output can be set to left only */
 154 #define CDSETRIGHT      0x00000800
 155         /* Output can be set to right only */
 156 #define CDSETMUTE       0x00001000
 157         /* Output can be muted */
 158 #define CDSETPATCH      0x00008000
 159         /* Direct routing control allowed */
 160
 161         u_long  special_function;
 162 #define CDDOEJECT       0x00000001
 163         /* The tray can be opened */
 164 #define CDDOCLOSE       0x00000002
 165         /* The tray can be closed */
 166 #define CDDOLOCK        0x00000004
 167         /* The tray can be locked */
 168 #define CDREADHEADER    0x00000100
 169         /* Can read Table of Contents */
 170 #define CDREADENTRIES   0x00000200
 171         /* Can read TOC Entries */
 172 #define CDREADSUBQ      0x00000200
 173         /* Can read Subchannel info */
 174 #define CDREADRW        0x00000400
 175         /* Can read subcodes R-W */
 176 #define CDHASDEBUG      0x00004000
 177         /* The tray has dynamic debugging */
 178 };
 179 .Ed
 180 .It Dv CDIOCPLAYTRACKS
 181 .Pq Li "struct ioc_play_track"
 182 Start audio playback given a track address and length.
 183 The structure is defined as follows:
 184 .Bd -literal -offset indent
 185 struct ioc_play_track
 186 {
 187         u_char  start_track;
 188         u_char  start_index;
 189         u_char  end_track;
 190         u_char  end_index;
 191 };
 192 .Ed
 193 .It Dv CDIOCPLAYBLOCKS
 194 .Pq Li "struct ioc_play_blocks"
 195 Start audio playback given a block address and length.
 196 The structure is defined as follows:
 197 .Bd -literal -offset indent
 198 struct ioc_play_blocks
 199 {
 200         int     blk;
 201         int     len;
 202 };
 203 .Ed
 204 .It Dv CDIOCPLAYMSF
 205 .Pq Li "struct ioc_play_msf"
 206 Start audio playback given a `minutes-seconds-frames' address and
 207 length.
 208 The structure is defined as follows:
 209 .Bd -literal -offset indent
 210 struct ioc_play_msf
 211 {
 212         u_char  start_m;
 213         u_char  start_s;
 214         u_char  start_f;
 215         u_char  end_m;
 216         u_char  end_s;
 217         u_char  end_f;
 218 };
 219 .Ed
 220 .It Dv CDIOCREADSUBCHANNEL
 221 .Pq Li "struct ioc_read_subchannel"
 222 Read information from the subchannel at the location specified by this
 223 structure:
 224 .Bd -literal -offset indent
 225 struct ioc_read_subchannel {
 226         u_char address_format;
 227 #define CD_LBA_FORMAT   1
 228 #define CD_MSF_FORMAT   2
 229         u_char data_format;
 230 #define CD_SUBQ_DATA            0
 231 #define CD_CURRENT_POSITION     1
 232 #define CD_MEDIA_CATALOG        2
 233 #define CD_TRACK_INFO           3
 234         u_char track;
 235         int     data_len;
 236         struct  cd_sub_channel_info *data;
 237 };
 238 .Ed
 239 .It Dv CDIOREADTOCHEADER
 240 .Pq Li "struct ioc_toc_header"
 241 Return summary information about the table of contents for the mounted
 242 .Tn CD-ROM .
 243 The information is returned into the following structure:
 244 .Bd -literal -offset indent
 245 struct ioc_toc_header {
 246         u_short len;
 247         u_char  starting_track;
 248         u_char  ending_track;
 249 };
 250 .Ed
 251 .It Dv CDIOREADTOCENTRYS
 252 .Pq Li "struct ioc_read_toc_entry"
 253 Return information from the table of contents entries mentioned.
 254 .Pq Yes, this command name is misspelled.
 255 The argument structure is defined as follows:
 256 .Bd -literal -offset indent
 257 struct ioc_read_toc_entry {
 258         u_char  address_format;
 259         u_char  starting_track;
 260         u_short data_len;
 261         struct  cd_toc_entry *data;
 262 };
 263 .Ed
 264 The requested data is written into an area of size
 265 .Li data_len
 266 and pointed to by
 267 .Li data .
 268 .It Dv CDIOCSETPATCH
 269 .Pq Li "struct ioc_patch"
 270 Attach various audio channels to various output channels.
 271 The argument structure is defined thusly:
 272 .Bd -literal -offset indent
 273 struct ioc_patch {
 274         u_char  patch[4];
 275         /* one for each channel */
 276 };
 277 .Ed
 278 .It Dv CDIOCGETVOL
 279 .It Dv CDIOCSETVOL
 280 .Pq Li "struct ioc_vol"
 281 Get (set) information about the volume settings of the output channels.
 282 The argument structure is as follows:
 283 .Bd -literal -offset indent
 284 struct  ioc_vol
 285 {
 286         u_char  vol[4];
 287         /* one for each channel */
 288 };
 289 .Ed
 290 .It Dv CDIOCSETMONO
 291 Patch all output channels to all source channels.
 292 .It Dv CDIOCSETSTEREO
 293 Patch left source channel to the left output channel and the right
 294 source channel to the right output channel.
 295 .It Dv CDIOCSETMUTE
 296 Mute output without changing the volume settings.
 297 .It Dv CDIOCSETLEFT
 298 .It Dv CDIOCSETRIGHT
 299 Attach both output channels to the left (right) source channel.
 300 .It Dv CDIOCSETDEBUG
 301 .It Dv CDIOCCLRDEBUG
 302 Turn on (off) debugging for the appropriate device.
 303 .It Dv CDIOCPAUSE
 304 .It Dv CDIOCRESUME
 305 Pause (resume) audio play, without resetting the location of the read-head.
 306 .It Dv CDIOCRESET
 307 Reset the drive.
 308 .It Dv CDIOCSTART
 309 .It Dv CDIOCSTOP
 310 Tell the drive to spin-up (-down) the
 311 .Tn CD-ROM .
 312 .It Dv CDIOCALLOW
 313 .It Dv CDIOCPREVENT
 314 Tell the drive to allow (prevent) manual ejection of the
 315 .Tn CD-ROM
 316 disc.
 317 Not all drives support this feature.
 318 .It Dv CDIOCEJECT
 319 Eject the
 320 .Tn CD-ROM .
 321 .It Dv CDIOCCLOSE
 322 Tell the drive to close its door and load the media.
 323 Not all drives support this feature.
 324 .It Dv CDIOCPITCH
 325 .Pq Li "struct ioc_pitch"
 326 For drives that support it, this command instructs the drive to play
 327 the audio at a faster or slower rate than normal.
 328 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.
 333 Drives with less than 16 bits of resolution will silently
 334 ignore less-significant bits.
 335 The structure is defined thusly:
 336 .Bd -literal -offset indent
 337 struct  ioc_pitch
 338 {
 339         short   speed;
 340 };
 341 .Ed
 342 .El
 343 .Sh NOTES
 344 When a
 345 .Tn CD-ROM
 346 is changed in a drive controlled by the
 347 .Nm
 348 driver, then the act of changing the media will invalidate the
 349 disklabel and information held within the kernel.
 350 To stop corruption,
 351 all accesses to the device will be discarded until there are no more
 352 open file descriptors referencing the device.
 353 During this period, all
 354 new open attempts will be rejected.
 355 When no more open file descriptors
 356 reference the device, the first next open will load a new set of
 357 parameters (including disklabel) for the drive.
 358 .Pp
 359 The audio code in the
 360 .Nm
 361 driver only support
 362 .Tn SCSI-2
 363 standard audio commands.
 364 As many
 365 .Tn CD-ROM
 366 manufacturers have not followed the standard, there are many
 367 .Tn CD-ROM
 368 drives for which audio will not work.
 369 Some work is planned to support
 370 some of the more common `broken'
 371 .Tn CD-ROM
 372 drives; however, this is not yet under way.
 373 .Sh CHANGER OPERATION
 374 This driver has built-in support for LUN-based CD changers.
 375 A LUN-based CD
 376 changer is a drive that can hold two or more CDs, but only has one CD
 377 player mechanism.
 378 Each CD in the drive shows up as a separate logical unit
 379 on the
 380 .Tn SCSI
 381 bus.
 382 The
 383 .Nm
 384 driver automatically recognizes LUN-based changers, and routes commands for
 385 changers through an internal scheduler.
 386 The scheduler prevents changer
 387 "thrashing", which is caused by sending commands to different LUNs in the
 388 changer at the same time.
 389 .Pp
 390 The scheduler honors minimum and maximum time
 391 quanta that the driver will spend on a particular LUN.
 392 The minimum time
 393 is the guaranteed minimum amount of time that the driver will spend on a
 394 given LUN, even if there is no outstanding I/O for that LUN.
 395 The maximum
 396 time is the maximum amount of time the changer will spend on a LUN if there
 397 is outstanding I/O for another LUN.
 398 If there is no outstanding I/O for
 399 another LUN, the driver will allow indefinite access to a given LUN.
 400 .Pp
 401 The minimum and maximum time quanta are configurable via kernel options and
 402 also via sysctl and kernel tunable variables.
 403 The kernel options are:
 404 .Pp
 405 .Bl -item -compact
 406 .It
 407 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
 408 .It
 409 .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"""
 410 .El
 411 .Pp
 412 The sysctl/kernel tunable variables are:
 413 .Pp
 414 .Bl -item -compact
 415 .It
 416 .Va kern.cam.cd.changer.min_busy_seconds
 417 .It
 418 .Va kern.cam.cd.changer.max_busy_seconds
 419 .El
 420 .Pp
 421 It is suggested that the user try experimenting with the minimum and
 422 maximum timeouts via the sysctl variables to arrive at the proper values
 423 for your changer.
 424 Once you have settled on the proper timeouts for your
 425 changer, you can then put them in your kernel config file.
 426 .Pp
 427 If your system does have a LUN-based changer, you may notice that the
 428 probe messages for the various LUNs of the changer will continue to appear
 429 while the boot process is going on.
 430 This is normal, and is caused by the
 431 changer scheduling code.
 432 .Sh SYSCTL VARIABLES
 433 The following variables are available as both
 434 .Xr sysctl 8
 435 variables and
 436 .Xr loader 8
 437 tunables:
 438 .Bl -tag -width 12
 439 .It kern.cam.cd.retry_count
 440 .Pp
 441 This variable determines how many times the
 442 .Nm
 443 driver will retry a READ or WRITE command.
 444 This does not affect the number of retries used during probe time or for
 445 the
 446 .Nm
 447 driver dump routine.
 448 This value currently defaults to 4.
 449 .It kern.cam.cd.%d.minimum_cmd_size
 450 .Pp
 451 The
 452 .Nm
 453 driver attempts to automatically determine whether the drive it is talking
 454 to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations.
 455 Many
 456 .Tn SCSI
 457 drives only support 6 byte commands, and
 458 .Tn ATAPI
 459 drives only support 10 byte commands.
 460 The
 461 .Nm
 462 driver first attempts to determine whether the protocol in use typically
 463 supports 6 byte commands by issuing a CAM Path Inquiry CCB.
 464 It will then default to 6 byte or 10 byte commands as appropriate.
 465 After that, the
 466 .Nm
 467 driver defaults to using 6 byte commands (assuming the protocol the drive
 468 speaks claims to support 6 byte commands), until one fails with a
 469 .Tn SCSI
 470 ILLEGAL REQUEST error.
 471 Then it tries the 10 byte version of the command to
 472 see if that works instead.
 473 Users can change the default via per-drive
 474 sysctl variables and loader tunables.
 475 Where
 476 .Dq %d
 477 is the unit number of the drive in question.
 478 Valid minimum command sizes
 479 are 6 and 10.
 480 Any value above 6 will be rounded to 10, and any value below
 481 6 will be rounded to 6.
 482 .It kern.cam.cd.changer.min_busy_seconds
 483 .It kern.cam.cd.changer.max_busy_seconds
 484 .Pp
 485 Tune how long individual LUNs are 'locked' for I/O operations to
 486 optimize changer operation.
 487 See CHANGER OPERATION section for information on how to use these items.
 488 .El
 489 .Sh FILES
 490 .Bl -tag -width /dev/cd[0-9][a-h] -compact
 491 .It Pa /dev/cd[0-9][a-h]
 492 raw mode
 493 .Tn CD-ROM
 494 devices
 495 .El
 496 .Sh DIAGNOSTICS
 497 None.
 498 .Sh SEE ALSO
 499 .Xr cam 4 ,
 500 .Xr da 4 ,
 501 .Xr disklabel 5 ,
 502 .Xr disklabel 8 ,
 503 .Xr cd 9
 504 .Sh HISTORY
 505 This
 506 .Nm
 507 driver is based upon the
 508 .Nm
 509 driver written by Julian Elischer, which appeared in
 510 .Bx 386 0.1 .
 511 The
 512 CAM version of the
 513 .Nm
 514 driver was written by Kenneth Merry and first appeared in
 515 .Fx 3.0 .
 516 .Sh BUGS
 517 The names of the structures used for the third argument to
 518 .Fn ioctl
 519 were poorly chosen, and a number of spelling errors have survived in
 520 the names of the
 521 .Fn ioctl
 522 commands.
 523 .Pp
 524 There is no mechanism currently to set different minimum and maximum
 525 timeouts for different CD changers; the timeout values set by the kernel
 526 options or the sysctl variables apply to all LUN-based CD changers in the
 527 system.
 528 It is possible to implement such support, but the sysctl
 529 implementation at least would be rather inelegant, because of the current
 530 inability of the sysctl code to handle the addition of nodes after compile
 531 time.
 532 Thus, it would take one dynamically sized sysctl variable and a
 533 userland utility to get/set the timeout values.
 534 Implementation of separate
 535 timeouts for different CD devices in the kernel config file would likely
 536 require modification of
 537 .Xr config 8
 538 to support the two timeouts when hardwiring
 539 .Nm
 540 devices.