2 .\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
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.
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
33 .Nd SCSI CD-ROM driver
36 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
37 .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"""
41 driver provides support for a
44 (Compact Disc-Read Only Memory) drive.
45 In an attempt to look like a regular disk, the
47 driver synthesizes a partition table, with one partition covering the entire
49 It is possible to modify this partition table using
51 but it will only last until the
54 In general the interfaces are similar to those described by
61 adapter is probed during boot, the
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
70 the first device found will be attached as
77 it is possible to specify what cd unit a device should
78 come on line as; refer to
80 for details on kernel configuration.
84 may be used to read the synthesized
86 structure, which will contain correct figures for the size of the
88 should that information be required.
89 .Sh KERNEL CONFIGURATION
92 devices may be attached to the system regardless of system
93 configuration as all resources are dynamically allocated.
104 .In sys/disklabel.h .
105 .Bl -tag -width CDIOCREADSUBCHANNEL
108 .Pq Li "struct disklabel"
109 Read or write the in-core copy of the disklabel for the
111 The disklabel is initialized with information
112 read from the scsi inquiry commands, and should be the same as
113 the information printed at boot.
114 This structure is defined in the header file
115 .In sys/disklabel.h .
116 .It Dv CDIOCPLAYTRACKS
117 .Pq Li "struct ioc_play_track"
118 Start audio playback given a track address and length.
119 The structure is defined as follows:
120 .Bd -literal -offset indent
121 struct ioc_play_track
129 .It Dv CDIOCPLAYBLOCKS
130 .Pq Li "struct ioc_play_blocks"
131 Start audio playback given a block address and length.
132 The structure is defined as follows:
133 .Bd -literal -offset indent
134 struct ioc_play_blocks
141 .Pq Li "struct ioc_play_msf"
142 Start audio playback given a `minutes-seconds-frames' address and
144 The structure is defined as follows:
145 .Bd -literal -offset indent
156 .It Dv CDIOCREADSUBCHANNEL
157 .Pq Li "struct ioc_read_subchannel"
158 Read information from the subchannel at the location specified by this
160 .Bd -literal -offset indent
161 struct ioc_read_subchannel {
162 u_char address_format;
163 #define CD_LBA_FORMAT 1
164 #define CD_MSF_FORMAT 2
166 #define CD_SUBQ_DATA 0
167 #define CD_CURRENT_POSITION 1
168 #define CD_MEDIA_CATALOG 2
169 #define CD_TRACK_INFO 3
172 struct cd_sub_channel_info *data;
175 .It Dv CDIOREADTOCHEADER
176 .Pq Li "struct ioc_toc_header"
177 Return summary information about the table of contents for the mounted
179 The information is returned into the following structure:
180 .Bd -literal -offset indent
181 struct ioc_toc_header {
183 u_char starting_track;
187 .It Dv CDIOREADTOCENTRYS
188 .Pq Li "struct ioc_read_toc_entry"
189 Return information from the table of contents entries mentioned.
190 .Pq Yes, this command name is misspelled.
191 The argument structure is defined as follows:
192 .Bd -literal -offset indent
193 struct ioc_read_toc_entry {
194 u_char address_format;
195 u_char starting_track;
197 struct cd_toc_entry *data;
200 The requested data is written into an area of size
205 .Pq Li "struct ioc_patch"
206 Attach various audio channels to various output channels.
207 The argument structure is defined thusly:
208 .Bd -literal -offset indent
211 /* one for each channel */
216 .Pq Li "struct ioc_vol"
217 Get (set) information about the volume settings of the output channels.
218 The argument structure is as follows:
219 .Bd -literal -offset indent
223 /* one for each channel */
227 Patch all output channels to all source channels.
228 .It Dv CDIOCSETSTEREO
229 Patch left source channel to the left output channel and the right
230 source channel to the right output channel.
232 Mute output without changing the volume settings.
235 Attach both output channels to the left (right) source channel.
238 Turn on (off) debugging for the appropriate device.
241 Pause (resume) audio play, without resetting the location of the read-head.
246 Tell the drive to spin-up (-down) the
250 Tell the drive to allow (prevent) manual ejection of the
253 Not all drives support this feature.
258 Tell the drive to close its door and load the media.
259 Not all drives support this feature.
264 is changed in a drive controlled by the
266 driver, then the act of changing the media will invalidate the
267 disklabel and information held within the kernel.
269 all accesses to the device will be discarded until there are no more
270 open file descriptors referencing the device.
271 During this period, all
272 new open attempts will be rejected.
273 When no more open file descriptors
274 reference the device, the first next open will load a new set of
275 parameters (including disklabel) for the drive.
277 The audio code in the
281 standard audio commands.
284 manufacturers have not followed the standard, there are many
286 drives for which audio will not work.
287 Some work is planned to support
288 some of the more common `broken'
290 drives; however, this is not yet under way.
291 .Sh CHANGER OPERATION
292 This driver has built-in support for LUN-based CD changers.
294 changer is a drive that can hold two or more CDs, but only has one CD
296 Each CD in the drive shows up as a separate logical unit
302 driver automatically recognizes LUN-based changers, and routes commands for
303 changers through an internal scheduler.
304 The scheduler prevents changer
305 "thrashing", which is caused by sending commands to different LUNs in the
306 changer at the same time.
308 The scheduler honors minimum and maximum time
309 quanta that the driver will spend on a particular LUN.
311 is the guaranteed minimum amount of time that the driver will spend on a
312 given LUN, even if there is no outstanding I/O for that LUN.
314 time is the maximum amount of time the changer will spend on a LUN if there
315 is outstanding I/O for another LUN.
316 If there is no outstanding I/O for
317 another LUN, the driver will allow indefinite access to a given LUN.
319 The minimum and maximum time quanta are configurable via kernel options and
320 also via sysctl and kernel tunable variables.
321 The kernel options are:
325 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
327 .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"""
330 The sysctl/kernel tunable variables are:
334 .Va kern.cam.cd.changer.min_busy_seconds
336 .Va kern.cam.cd.changer.max_busy_seconds
339 It is suggested that the user try experimenting with the minimum and
340 maximum timeouts via the sysctl variables to arrive at the proper values
342 Once you have settled on the proper timeouts for your
343 changer, you can then put them in your kernel config file.
345 If your system does have a LUN-based changer, you may notice that the
346 probe messages for the various LUNs of the changer will continue to appear
347 while the boot process is going on.
348 This is normal, and is caused by the
349 changer scheduling code.
351 The following variables are available as both
357 .It kern.cam.cd.retry_count
359 This variable determines how many times the
361 driver will retry a READ or WRITE command.
362 This does not affect the number of retries used during probe time or for
366 This value currently defaults to 4.
367 .It kern.cam.cd.%d.minimum_cmd_size
371 driver attempts to automatically determine whether the drive it is talking
372 to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations.
375 drives only support 6 byte commands, and
377 drives only support 10 byte commands.
380 driver first attempts to determine whether the protocol in use typically
381 supports 6 byte commands by issuing a CAM Path Inquiry CCB.
382 It will then default to 6 byte or 10 byte commands as appropriate.
385 driver defaults to using 6 byte commands (assuming the protocol the drive
386 speaks claims to support 6 byte commands), until one fails with a
388 ILLEGAL REQUEST error.
389 Then it tries the 10 byte version of the command to
390 see if that works instead.
391 Users can change the default via per-drive
392 sysctl variables and loader tunables.
395 is the unit number of the drive in question.
396 Valid minimum command sizes
398 Any value above 6 will be rounded to 10, and any value below
399 6 will be rounded to 6.
400 .It kern.cam.cd.changer.min_busy_seconds
401 .It kern.cam.cd.changer.max_busy_seconds
403 Tune how long individual LUNs are 'locked' for I/O operations to
404 optimize changer operation.
405 See CHANGER OPERATION section for information on how to use these items.
408 .Bl -tag -width /dev/cd[0-9][a-h] -compact
409 .It Pa /dev/cd[0-9][a-h]
424 driver is based upon the
426 driver written by Julian Elischer, which appeared in
431 driver was written by Kenneth Merry and first appeared in
434 The names of the structures used for the third argument to
436 were poorly chosen, and a number of spelling errors have survived in
441 There is no mechanism currently to set different minimum and maximum
442 timeouts for different CD changers; the timeout values set by the kernel
443 options or the sysctl variables apply to all LUN-based CD changers in the
445 It is possible to implement such support, but the sysctl
446 implementation at least would be rather inelegant, because of the current
447 inability of the sysctl code to handle the addition of nodes after compile
449 Thus, it would take one dynamically sized sysctl variable and a
450 userland utility to get/set the timeout values.
451 Implementation of separate
452 timeouts for different CD devices in the kernel config file would likely
453 require modification of
455 to support the two timeouts when hardwiring