| blob | 19113b78f28da3ecf51afbf6ec2341cf1c73ec72 |
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 September 2, 2003
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 */
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 */
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 .Pp
374 The
375 .Nm
376 driver attempts to automatically determine whether the drive it is talking
377 to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations.
378 Many
379 .Tn SCSI
380 drives only support 6 byte commands, and
381 .Tn ATAPI
382 drives only support 10 byte commands.
383 The
384 .Nm
385 driver first attempts to determine whether the protocol in use typically
386 supports 6 byte commands by issuing a CAM Path Inquiry CCB.
387 It will then default to 6 byte or 10 byte commands as appropriate.
388 After that, the
389 .Nm
390 driver defaults to using 6 byte commands (assuming the protocol the drive
391 speaks claims to support 6 byte commands), until one fails with a
392 .Tn SCSI
393 ILLEGAL REQUEST error.
394 Then it tries the 10 byte version of the command to
395 see if that works instead.
396 Users can change the default via per-drive
397 sysctl variables and loader tunables.
398 The variable names are the same in
399 both instances:
400 .Pp
401 .Va kern.cam.cd.%d.minimum_cmd_size
402 .Pp
403 Where
404 .Dq %d
405 is the unit number of the drive in question.
406 Valid minimum command sizes
407 are 6 and 10.
408 Any value above 6 will be rounded to 10, and any value below
409 6 will be rounded to 6.
410 .Sh CHANGER OPERATION
411 This driver has built-in support for LUN-based CD changers.
412 A LUN-based CD
413 changer is a drive that can hold two or more CDs, but only has one CD
414 player mechanism.
415 Each CD in the drive shows up as a separate logical unit
416 on the
417 .Tn SCSI
418 bus.
419 The
420 .Nm
421 driver automatically recognizes LUN-based changers, and routes commands for
422 changers through an internal scheduler.
423 The scheduler prevents changer
424 "thrashing", which is caused by sending commands to different LUNs in the
425 changer at the same time.
426 .Pp
427 The scheduler honors minimum and maximum time
428 quanta that the driver will spend on a particular LUN.
429 The minimum time
430 is the guaranteed minimum amount of time that the driver will spend on a
431 given LUN, even if there is no outstanding I/O for that LUN.
432 The maximum
433 time is the maximum amount of time the changer will spend on a LUN if there
434 is outstanding I/O for another LUN.
435 If there is no outstanding I/O for
436 another LUN, the driver will allow indefinite access to a given LUN.
437 .Pp
438 The minimum and maximum time quanta are configurable via kernel options and
439 also via sysctl and kernel tunable variables.
440 The kernel options are:
441 .Pp
442 .Bl -item -compact
443 .It
444 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
445 .It
446 .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"""
447 .El
448 .Pp
449 The sysctl/kernel tunable variables are:
450 .Pp
451 .Bl -item -compact
452 .It
453 .Va kern.cam.cd.changer.min_busy_seconds
454 .It
455 .Va kern.cam.cd.changer.max_busy_seconds
456 .El
457 .Pp
458 It is suggested that the user try experimenting with the minimum and
459 maximum timeouts via the sysctl variables to arrive at the proper values
460 for your changer.
461 Once you have settled on the proper timeouts for your
462 changer, you can then put them in your kernel config file.
463 .Pp
464 If your system does have a LUN-based changer, you may notice that the
465 probe messages for the various LUNs of the changer will continue to appear
466 while the boot process is going on.
467 This is normal, and is caused by the
468 changer scheduling code.
469 .Sh FILES
470 .Bl -tag -width /dev/cd[0-9][a-h] -compact
471 .It Pa /dev/cd[0-9][a-h]
472 raw mode
473 .Tn CD-ROM
474 devices
475 .El
476 .Sh DIAGNOSTICS
477 None.
478 .Sh SEE ALSO
479 .Xr da 4 ,
480 .Xr scsi 4 ,
481 .Xr disklabel 5 ,
482 .Xr disklabel 8 ,
483 .Xr cd 9
484 .Sh HISTORY
485 This
486 .Nm
487 driver is based upon the
488 .Nm
489 driver written by Julian Elischer, which appeared in
490 .Bx 386 0.1 .
491 The
492 CAM version of the
493 .Nm
494 driver was written by Kenneth Merry and first appeared in
495 .Fx 3.0 .
496 .Sh BUGS
497 The names of the structures used for the third argument to
498 .Fn ioctl
499 were poorly chosen, and a number of spelling errors have survived in
500 the names of the
501 .Fn ioctl
502 commands.
503 .Pp
504 There is no mechanism currently to set different minimum and maximum
505 timeouts for different CD changers; the timeout values set by the kernel
506 options or the sysctl variables apply to all LUN-based CD changers in the
507 system.
508 It is possible to implement such support, but the sysctl
509 implementation at least would be rather inelegant, because of the current
510 inability of the sysctl code to handle the addition of nodes after compile
511 time.
512 Thus, it would take one dynamically sized sysctl variable and a
513 userland utility to get/set the timeout values.
514 Implementation of separate
515 timeouts for different CD devices in the kernel config file would likely
516 require modification of
517 .Xr config 8
518 to support the two timeouts when hardwiring
519 .Nm
520 devices.