541 lines
15 KiB
Groff
541 lines
15 KiB
Groff
.\" Copyright (c) 1996
|
|
.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 8, 2009
|
|
.Dt CD 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cd
|
|
.Nd SCSI CD-ROM driver
|
|
.Sh SYNOPSIS
|
|
.Cd device cd
|
|
.Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
|
|
.Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for a
|
|
.Tn SCSI
|
|
.Tn CD-ROM
|
|
(Compact Disc-Read Only Memory) drive.
|
|
In an attempt to look like a regular disk, the
|
|
.Nm
|
|
driver synthesizes a partition table, with one partition covering the entire
|
|
.Tn CD-ROM .
|
|
It is possible to modify this partition table using
|
|
.Xr disklabel 8 ,
|
|
but it will only last until the
|
|
.Tn CD-ROM
|
|
is unmounted.
|
|
In general the interfaces are similar to those described by
|
|
.Xr ad 4
|
|
and
|
|
.Xr da 4 .
|
|
.Pp
|
|
As the
|
|
.Tn SCSI
|
|
adapter is probed during boot, the
|
|
.Tn SCSI
|
|
bus is scanned for devices.
|
|
Any devices found which answer as CDROM
|
|
(type 5) or WORM (type 4) type devices will be `attached' to the
|
|
.Nm
|
|
driver.
|
|
Prior to
|
|
.Fx 2.1 ,
|
|
the first device found will be attached as
|
|
.Li cd0
|
|
the next,
|
|
.Li cd1 ,
|
|
etc.
|
|
Beginning in
|
|
.Fx 2.1
|
|
it is possible to specify what cd unit a device should
|
|
come on line as; refer to
|
|
.Xr scsi 4
|
|
for details on kernel configuration.
|
|
.Pp
|
|
The system utility
|
|
.Xr disklabel 8
|
|
may be used to read the synthesized
|
|
disk label
|
|
structure, which will contain correct figures for the size of the
|
|
.Tn CD-ROM
|
|
should that information be required.
|
|
.Sh KERNEL CONFIGURATION
|
|
Any number of
|
|
.Tn CD-ROM
|
|
devices may be attached to the system regardless of system
|
|
configuration as all resources are dynamically allocated.
|
|
.Sh IOCTLS
|
|
The following
|
|
.Xr ioctl 2
|
|
calls which apply to
|
|
.Tn SCSI
|
|
.Tn CD-ROM
|
|
drives are defined
|
|
in the header files
|
|
.In sys/cdio.h
|
|
and
|
|
.In sys/disklabel.h .
|
|
.Pp
|
|
.Bl -tag -width CDIOCREADSUBCHANNEL
|
|
.It Dv DIOCGDINFO
|
|
.It Dv DIOCSDINFO
|
|
.Pq Li "struct disklabel"
|
|
Read or write the in-core copy of the disklabel for the
|
|
drive.
|
|
The disklabel is initialized with information
|
|
read from the scsi inquiry commands, and should be the same as
|
|
the information printed at boot.
|
|
This structure is defined in
|
|
.Xr disklabel 5 .
|
|
.It Dv CDIOCCAPABILITY
|
|
.Pq Li "struct ioc_capability"
|
|
Retrieve information from the drive on what features it supports.
|
|
The information is returned in the following structure:
|
|
.Bd -literal -offset indent
|
|
struct ioc_capability {
|
|
u_long play_function;
|
|
#define CDDOPLAYTRK 0x00000001
|
|
/* Can play tracks/index */
|
|
#define CDDOPLAYMSF 0x00000002
|
|
/* Can play msf to msf */
|
|
#define CDDOPLAYBLOCKS 0x00000004
|
|
/* Can play range of blocks */
|
|
#define CDDOPAUSE 0x00000100
|
|
/* Output can be paused */
|
|
#define CDDORESUME 0x00000200
|
|
/* Output can be resumed */
|
|
#define CDDORESET 0x00000400
|
|
/* Drive can be completely reset */
|
|
#define CDDOSTART 0x00000800
|
|
/* Audio can be started */
|
|
#define CDDOSTOP 0x00001000
|
|
/* Audio can be stopped */
|
|
#define CDDOPITCH 0x00002000
|
|
/* Audio pitch can be changed */
|
|
|
|
u_long routing_function;
|
|
#define CDREADVOLUME 0x00000001
|
|
/* Volume settings can be read */
|
|
#define CDSETVOLUME 0x00000002
|
|
/* Volume settings can be set */
|
|
#define CDSETMONO 0x00000100
|
|
/* Output can be set to mono */
|
|
#define CDSETSTEREO 0x00000200
|
|
/* Output can be set to stereo (def) */
|
|
#define CDSETLEFT 0x00000400
|
|
/* Output can be set to left only */
|
|
#define CDSETRIGHT 0x00000800
|
|
/* Output can be set to right only */
|
|
#define CDSETMUTE 0x00001000
|
|
/* Output can be muted */
|
|
#define CDSETPATCH 0x00008000
|
|
/* Direct routing control allowed */
|
|
|
|
u_long special_function;
|
|
#define CDDOEJECT 0x00000001
|
|
/* The tray can be opened */
|
|
#define CDDOCLOSE 0x00000002
|
|
/* The tray can be closed */
|
|
#define CDDOLOCK 0x00000004
|
|
/* The tray can be locked */
|
|
#define CDREADHEADER 0x00000100
|
|
/* Can read Table of Contents */
|
|
#define CDREADENTRIES 0x00000200
|
|
/* Can read TOC Entries */
|
|
#define CDREADSUBQ 0x00000200
|
|
/* Can read Subchannel info */
|
|
#define CDREADRW 0x00000400
|
|
/* Can read subcodes R-W */
|
|
#define CDHASDEBUG 0x00004000
|
|
/* The tray has dynamic debugging */
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCPLAYTRACKS
|
|
.Pq Li "struct ioc_play_track"
|
|
Start audio playback given a track address and length.
|
|
The structure is defined as follows:
|
|
.Bd -literal -offset indent
|
|
struct ioc_play_track
|
|
{
|
|
u_char start_track;
|
|
u_char start_index;
|
|
u_char end_track;
|
|
u_char end_index;
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCPLAYBLOCKS
|
|
.Pq Li "struct ioc_play_blocks"
|
|
Start audio playback given a block address and length.
|
|
The structure is defined as follows:
|
|
.Bd -literal -offset indent
|
|
struct ioc_play_blocks
|
|
{
|
|
int blk;
|
|
int len;
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCPLAYMSF
|
|
.Pq Li "struct ioc_play_msf"
|
|
Start audio playback given a `minutes-seconds-frames' address and
|
|
length.
|
|
The structure is defined as follows:
|
|
.Bd -literal -offset indent
|
|
struct ioc_play_msf
|
|
{
|
|
u_char start_m;
|
|
u_char start_s;
|
|
u_char start_f;
|
|
u_char end_m;
|
|
u_char end_s;
|
|
u_char end_f;
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCREADSUBCHANNEL
|
|
.Pq Li "struct ioc_read_subchannel"
|
|
Read information from the subchannel at the location specified by this
|
|
structure:
|
|
.Bd -literal -offset indent
|
|
struct ioc_read_subchannel {
|
|
u_char address_format;
|
|
#define CD_LBA_FORMAT 1
|
|
#define CD_MSF_FORMAT 2
|
|
u_char data_format;
|
|
#define CD_SUBQ_DATA 0
|
|
#define CD_CURRENT_POSITION 1
|
|
#define CD_MEDIA_CATALOG 2
|
|
#define CD_TRACK_INFO 3
|
|
u_char track;
|
|
int data_len;
|
|
struct cd_sub_channel_info *data;
|
|
};
|
|
.Ed
|
|
.It Dv CDIOREADTOCHEADER
|
|
.Pq Li "struct ioc_toc_header"
|
|
Return summary information about the table of contents for the mounted
|
|
.Tn CD-ROM .
|
|
The information is returned into the following structure:
|
|
.Bd -literal -offset indent
|
|
struct ioc_toc_header {
|
|
u_short len;
|
|
u_char starting_track;
|
|
u_char ending_track;
|
|
};
|
|
.Ed
|
|
.It Dv CDIOREADTOCENTRYS
|
|
.Pq Li "struct ioc_read_toc_entry"
|
|
Return information from the table of contents entries mentioned.
|
|
.Pq Yes, this command name is misspelled.
|
|
The argument structure is defined as follows:
|
|
.Bd -literal -offset indent
|
|
struct ioc_read_toc_entry {
|
|
u_char address_format;
|
|
u_char starting_track;
|
|
u_short data_len;
|
|
struct cd_toc_entry *data;
|
|
};
|
|
.Ed
|
|
The requested data is written into an area of size
|
|
.Li data_len
|
|
and pointed to by
|
|
.Li data .
|
|
.It Dv CDIOCSETPATCH
|
|
.Pq Li "struct ioc_patch"
|
|
Attach various audio channels to various output channels.
|
|
The argument structure is defined thusly:
|
|
.Bd -literal -offset indent
|
|
struct ioc_patch {
|
|
u_char patch[4];
|
|
/* one for each channel */
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCGETVOL
|
|
.It Dv CDIOCSETVOL
|
|
.Pq Li "struct ioc_vol"
|
|
Get (set) information about the volume settings of the output channels.
|
|
The argument structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct ioc_vol
|
|
{
|
|
u_char vol[4];
|
|
/* one for each channel */
|
|
};
|
|
.Ed
|
|
.It Dv CDIOCSETMONO
|
|
Patch all output channels to all source channels.
|
|
.It Dv CDIOCSETSTEREO
|
|
Patch left source channel to the left output channel and the right
|
|
source channel to the right output channel.
|
|
.It Dv CDIOCSETMUTE
|
|
Mute output without changing the volume settings.
|
|
.It Dv CDIOCSETLEFT
|
|
.It Dv CDIOCSETRIGHT
|
|
Attach both output channels to the left (right) source channel.
|
|
.It Dv CDIOCSETDEBUG
|
|
.It Dv CDIOCCLRDEBUG
|
|
Turn on (off) debugging for the appropriate device.
|
|
.It Dv CDIOCPAUSE
|
|
.It Dv CDIOCRESUME
|
|
Pause (resume) audio play, without resetting the location of the read-head.
|
|
.It Dv CDIOCRESET
|
|
Reset the drive.
|
|
.It Dv CDIOCSTART
|
|
.It Dv CDIOCSTOP
|
|
Tell the drive to spin-up (-down) the
|
|
.Tn CD-ROM .
|
|
.It Dv CDIOCALLOW
|
|
.It Dv CDIOCPREVENT
|
|
Tell the drive to allow (prevent) manual ejection of the
|
|
.Tn CD-ROM
|
|
disc.
|
|
Not all drives support this feature.
|
|
.It Dv CDIOCEJECT
|
|
Eject the
|
|
.Tn CD-ROM .
|
|
.It Dv CDIOCCLOSE
|
|
Tell the drive to close its door and load the media.
|
|
Not all drives support this feature.
|
|
.It Dv CDIOCPITCH
|
|
.Pq Li "struct ioc_pitch"
|
|
For drives that support it, this command instructs the drive to play
|
|
the audio at a faster or slower rate than normal.
|
|
Values of
|
|
.Li speed
|
|
between -32767 and -1 result in slower playback; a zero value
|
|
indicates normal speed; and values from 1 to 32767 give faster
|
|
playback.
|
|
Drives with less than 16 bits of resolution will silently
|
|
ignore less-significant bits.
|
|
The structure is defined thusly:
|
|
.Bd -literal -offset indent
|
|
struct ioc_pitch
|
|
{
|
|
short speed;
|
|
};
|
|
.Ed
|
|
.El
|
|
.Sh NOTES
|
|
When a
|
|
.Tn CD-ROM
|
|
is changed in a drive controlled by the
|
|
.Nm
|
|
driver, then the act of changing the media will invalidate the
|
|
disklabel and information held within the kernel.
|
|
To stop corruption,
|
|
all accesses to the device will be discarded until there are no more
|
|
open file descriptors referencing the device.
|
|
During this period, all
|
|
new open attempts will be rejected.
|
|
When no more open file descriptors
|
|
reference the device, the first next open will load a new set of
|
|
parameters (including disklabel) for the drive.
|
|
.Pp
|
|
The audio code in the
|
|
.Nm
|
|
driver only support
|
|
.Tn SCSI-2
|
|
standard audio commands.
|
|
As many
|
|
.Tn CD-ROM
|
|
manufacturers have not followed the standard, there are many
|
|
.Tn CD-ROM
|
|
drives for which audio will not work.
|
|
Some work is planned to support
|
|
some of the more common `broken'
|
|
.Tn CD-ROM
|
|
drives; however, this is not yet under way.
|
|
.Sh CHANGER OPERATION
|
|
This driver has built-in support for LUN-based CD changers.
|
|
A LUN-based CD
|
|
changer is a drive that can hold two or more CDs, but only has one CD
|
|
player mechanism.
|
|
Each CD in the drive shows up as a separate logical unit
|
|
on the
|
|
.Tn SCSI
|
|
bus.
|
|
The
|
|
.Nm
|
|
driver automatically recognizes LUN-based changers, and routes commands for
|
|
changers through an internal scheduler.
|
|
The scheduler prevents changer
|
|
"thrashing", which is caused by sending commands to different LUNs in the
|
|
changer at the same time.
|
|
.Pp
|
|
The scheduler honors minimum and maximum time
|
|
quanta that the driver will spend on a particular LUN.
|
|
The minimum time
|
|
is the guaranteed minimum amount of time that the driver will spend on a
|
|
given LUN, even if there is no outstanding I/O for that LUN.
|
|
The maximum
|
|
time is the maximum amount of time the changer will spend on a LUN if there
|
|
is outstanding I/O for another LUN.
|
|
If there is no outstanding I/O for
|
|
another LUN, the driver will allow indefinite access to a given LUN.
|
|
.Pp
|
|
The minimum and maximum time quanta are configurable via kernel options and
|
|
also via sysctl and kernel tunable variables.
|
|
The kernel options are:
|
|
.Pp
|
|
.Bl -item -compact
|
|
.It
|
|
.Cd "options ""CHANGER_MIN_BUSY_SECONDS=3"""
|
|
.It
|
|
.Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"""
|
|
.El
|
|
.Pp
|
|
The sysctl/kernel tunable variables are:
|
|
.Pp
|
|
.Bl -item -compact
|
|
.It
|
|
.Va kern.cam.cd.changer.min_busy_seconds
|
|
.It
|
|
.Va kern.cam.cd.changer.max_busy_seconds
|
|
.El
|
|
.Pp
|
|
It is suggested that the user try experimenting with the minimum and
|
|
maximum timeouts via the sysctl variables to arrive at the proper values
|
|
for your changer.
|
|
Once you have settled on the proper timeouts for your
|
|
changer, you can then put them in your kernel config file.
|
|
.Pp
|
|
If your system does have a LUN-based changer, you may notice that the
|
|
probe messages for the various LUNs of the changer will continue to appear
|
|
while the boot process is going on.
|
|
This is normal, and is caused by the
|
|
changer scheduling code.
|
|
.Sh SYSCTL VARIABLES
|
|
The following variables are available as both
|
|
.Xr sysctl 8
|
|
variables and
|
|
.Xr loader 8
|
|
tunables:
|
|
.Bl -tag -width 12
|
|
.It kern.cam.cd.retry_count
|
|
.Pp
|
|
This variable determines how many times the
|
|
.Nm
|
|
driver will retry a READ or WRITE command.
|
|
This does not affect the number of retries used during probe time or for
|
|
the
|
|
.Nm
|
|
driver dump routine.
|
|
This value currently defaults to 4.
|
|
.It kern.cam.cd.%d.minimum_cmd_size
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver attempts to automatically determine whether the drive it is talking
|
|
to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations.
|
|
Many
|
|
.Tn SCSI
|
|
drives only support 6 byte commands, and
|
|
.Tn ATAPI
|
|
drives only support 10 byte commands.
|
|
The
|
|
.Nm
|
|
driver first attempts to determine whether the protocol in use typically
|
|
supports 6 byte commands by issuing a CAM Path Inquiry CCB.
|
|
It will then default to 6 byte or 10 byte commands as appropriate.
|
|
After that, the
|
|
.Nm
|
|
driver defaults to using 6 byte commands (assuming the protocol the drive
|
|
speaks claims to support 6 byte commands), until one fails with a
|
|
.Tn SCSI
|
|
ILLEGAL REQUEST error.
|
|
Then it tries the 10 byte version of the command to
|
|
see if that works instead.
|
|
Users can change the default via per-drive
|
|
sysctl variables and loader tunables.
|
|
Where
|
|
.Dq %d
|
|
is the unit number of the drive in question.
|
|
Valid minimum command sizes
|
|
are 6 and 10.
|
|
Any value above 6 will be rounded to 10, and any value below
|
|
6 will be rounded to 6.
|
|
.It kern.cam.cd.changer.min_busy_seconds
|
|
.It kern.cam.cd.changer.max_busy_seconds
|
|
.Pp
|
|
Tune how long individual LUNs are 'locked' for I/O operations to
|
|
optimize changer operation.
|
|
See CHANGER OPERATION section for information on how to use these items.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/cd[0-9][a-h] -compact
|
|
.It Pa /dev/cd[0-9][a-h]
|
|
raw mode
|
|
.Tn CD-ROM
|
|
devices
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
None.
|
|
.Sh SEE ALSO
|
|
.Xr cam 4 ,
|
|
.Xr da 4 ,
|
|
.Xr disklabel 5 ,
|
|
.Xr disklabel 8 ,
|
|
.Xr cd 9
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
driver is based upon the
|
|
.Nm
|
|
driver written by Julian Elischer, which appeared in
|
|
.Bx 386 0.1 .
|
|
The
|
|
CAM version of the
|
|
.Nm
|
|
driver was written by Kenneth Merry and first appeared in
|
|
.Fx 3.0 .
|
|
.Sh BUGS
|
|
The names of the structures used for the third argument to
|
|
.Fn ioctl
|
|
were poorly chosen, and a number of spelling errors have survived in
|
|
the names of the
|
|
.Fn ioctl
|
|
commands.
|
|
.Pp
|
|
There is no mechanism currently to set different minimum and maximum
|
|
timeouts for different CD changers; the timeout values set by the kernel
|
|
options or the sysctl variables apply to all LUN-based CD changers in the
|
|
system.
|
|
It is possible to implement such support, but the sysctl
|
|
implementation at least would be rather inelegant, because of the current
|
|
inability of the sysctl code to handle the addition of nodes after compile
|
|
time.
|
|
Thus, it would take one dynamically sized sysctl variable and a
|
|
userland utility to get/set the timeout values.
|
|
Implementation of separate
|
|
timeouts for different CD devices in the kernel config file would likely
|
|
require modification of
|
|
.Xr config 8
|
|
to support the two timeouts when hardwiring
|
|
.Nm
|
|
devices.
|