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
39 driver provides support for a
42 (Compact Disc-Read Only Memory) drive.
43 In an attempt to look like a regular disk, the
45 driver synthesizes a partition table, with one partition covering the entire
47 It is possible to modify this partition table using
49 but it will only last until the
52 In general the interfaces are similar to those described by
59 adapter is probed during boot, the
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
68 the first device found will be attached as
75 it is possible to specify what cd unit a device should
76 come on line as; refer to
78 for details on kernel configuration.
82 may be used to read the synthesized
84 structure, which will contain correct figures for the size of the
86 should that information be required.
87 .Sh KERNEL CONFIGURATION
90 devices may be attached to the system regardless of system
91 configuration as all resources are dynamically allocated.
102 .In sys/disklabel.h .
103 .Bl -tag -width CDIOCREADSUBCHANNEL
106 .Pq Li "struct disklabel"
107 Read or write the in-core copy of the disklabel for the
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
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
139 .Pq Li "struct ioc_play_msf"
140 Start audio playback given a `minutes-seconds-frames' address and
142 The structure is defined as follows:
143 .Bd -literal -offset indent
154 .It Dv CDIOCREADSUBCHANNEL
155 .Pq Li "struct ioc_read_subchannel"
156 Read information from the subchannel at the location specified by this
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
164 #define CD_SUBQ_DATA 0
165 #define CD_CURRENT_POSITION 1
166 #define CD_MEDIA_CATALOG 2
167 #define CD_TRACK_INFO 3
170 struct cd_sub_channel_info *data;
173 .It Dv CDIOREADTOCHEADER
174 .Pq Li "struct ioc_toc_header"
175 Return summary information about the table of contents for the mounted
177 The information is returned into the following structure:
178 .Bd -literal -offset indent
179 struct ioc_toc_header {
181 u_char starting_track;
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;
195 struct cd_toc_entry *data;
198 The requested data is written into an area of size
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
209 /* one for each channel */
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
221 /* one for each channel */
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.
230 Mute output without changing the volume settings.
233 Attach both output channels to the left (right) source channel.
236 Turn on (off) debugging for the appropriate device.
239 Pause (resume) audio play, without resetting the location of the read-head.
244 Tell the drive to spin-up (-down) the
248 Tell the drive to allow (prevent) manual ejection of the
251 Not all drives support this feature.
256 Tell the drive to close its door and load the media.
257 Not all drives support this feature.
262 is changed in a drive controlled by the
264 driver, then the act of changing the media will invalidate the
265 disklabel and information held within the kernel.
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.
275 The audio code in the
279 standard audio commands.
282 manufacturers have not followed the standard, there are many
284 drives for which audio will not work.
285 Some work is planned to support
286 some of the more common `broken'
288 drives; however, this is not yet under way.
290 The following variables are available as both
296 .It kern.cam.cd.retry_count
298 This variable determines how many times the
300 driver will retry a READ or WRITE command.
301 This does not affect the number of retries used during probe time or for
305 This value currently defaults to 4.
306 .It kern.cam.cd.%d.minimum_cmd_size
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.
314 drives only support 6 byte commands, and
316 drives only support 10 byte commands.
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.
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
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.
334 is the unit number of the drive in question.
335 Valid minimum command sizes
337 Any value above 6 will be rounded to 10, and any value below
338 6 will be rounded to 6.
341 .Bl -tag -width /dev/cd[0-9][a-h] -compact
342 .It Pa /dev/cd[0-9][a-h]
357 driver is based upon the
359 driver written by Julian Elischer, which appeared in
364 driver was written by Kenneth Merry and first appeared in
367 The names of the structures used for the third argument to
369 were poorly chosen, and a number of spelling errors have survived in