cd(4)

NAME

cd - SCSI CD-ROM driver

SYNOPSIS

device cd
options "CHANGER_MIN_BUSY_SECONDS=3"
options "CHANGER_MAX_BUSY_SECONDS=11"

DESCRIPTION

The cd driver provides support for a SCSI CD-ROM (Compact
Disc-Read Only Memory) drive. In an attempt to look like a regular disk,
the cd driver synthesizes a partition table, with one partition covering
the entire CD-ROM. It is possible to modify this partition table using disklabel(8), but it will only last until the CD-ROM is un
mounted. In general the interfaces are similar to those described by
ad(4) and da(4).
As the SCSI adapter is probed during boot, the 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 cd driver. Prior
to FreeBSD 2.1, the first device found will be attached as cd0
the next, cd1, etc. Beginning in FreeBSD 2.1 it is possible to speci
fy what cd unit a device should come on line as; refer to scsi(4) for
details on kernel configuration.
The system utility disklabel(8) may be used to read the syn
thesized disk label structure, which will contain correct figures for the
size of the CD-ROM should that information be required.

KERNEL CONFIGURATION

Any number of CD-ROM devices may be attached to the system
regardless of system configuration as all resources are dynamically allo
cated.

IOCTLS

The following ioctl(2) calls which apply to SCSI CD-ROM
drives are
defined in the header files #include <sys/cdio.h> and
DIOCGDINFO
DIOCSDINFO (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 de; fined in
disklabel(5).
CDIOCCAPABILITY (struct ioc_capability) Retrieve infor
mation from: the drive on what features it supports.; The information is returned in the following; structure:

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 complete

ly 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 Con

tents */

#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 */

};
CDIOCPLAYTRACKS (struct ioc_play_track) Start audio
playback given a: track address and length. The struc; ture is defined
as follows:

struct ioc_play_track
{
u_char start_track;
u_char start_index;
u_char end_track;
u_char end_index;

};
CDIOCPLAYBLOCKS (struct ioc_play_blocks) Start audio
playback given: a block address and length. The struc; ture is
defined as follows:

struct ioc_play_blocks
{
int blk;
int len;

};
CDIOCPLAYMSF (struct ioc_play_msf) Start audio play
back given a: `minutes-seconds-frames' address and; length. The
structure is defined as follows:

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;

};
CDIOCREADSUBCHANNEL (struct ioc_read_subchannel) Read in
formation from: the subchannel at the location speci; fied by this
structure:

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_chan

nel_info *data;

};
CDIOREADTOCHEADER (struct ioc_toc_header) Return summary
information: about the table of contents for the; mounted CD-ROM.
The information is returned into the; following
structure:

struct ioc_toc_header {
u_short len;
u_char starting_track;
u_char ending_track;

};
CDIOREADTOCENTRYS (struct ioc_read_toc_entry) Return in
formation from: the table of contents entries men; tioned. (Yes, this
command name is misspelled.) The argu; ment structure
is defined as follows:

struct ioc_read_toc_entry {
u_char address_format;
u_char starting_track;
u_short data_len;
struct cd_toc_entry *da

ta;

};; The requested data is written into an; area of size
data_len and pointed to by data.
CDIOCSETPATCH (struct ioc_patch) Attach various audio
channels to: various output channels. The argument; structure is
defined thusly:

struct ioc_patch {
u_char patch[4];
/* one for each channel

*/

};
CDIOCGETVOL
CDIOCSETVOL (struct ioc_vol) Get (set) information
about the: volume settings of the output channels.; The argument structure is as follows:

struct ioc_vol
{
u_char vol[4];
/* one for each channel

*/

};
CDIOCSETMONO Patch all output channels to all source
channels.
CDIOCSETSTEREO Patch left source channel to the left
output channel: and the right source channel to the; right output
channel.
CDIOCSETMUTE Mute output without changing the volume
settings.
CDIOCSETLEFT
CDIOCSETRIGHT Attach both output channels to the left
(right): source channel.
CDIOCSETDEBUG
CDIOCCLRDEBUG Turn on (off) debugging for the appro
priate device.
CDIOCPAUSE
CDIOCRESUME Pause (resume) audio play, without re
setting the: location of the read-head.
CDIOCRESET Reset the drive.
CDIOCSTART
CDIOCSTOP Tell the drive to spin-up (-down) the
CD-ROM.
CDIOCALLOW
CDIOCPREVENT Tell the drive to allow (prevent) manu
al ejection of: the CD-ROM disc. Not all drives sup; port this feature.
CDIOCEJECT Eject the CD-ROM.
CDIOCCLOSE Tell the drive to close its door and
load the media.: Not all drives support this feature.
CDIOCPITCH (struct ioc_pitch) For drives that sup
port it, this: command instructs the drive to play the; audio at a
faster or slower rate than normal.; Values of 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 silent; ly ignore
less-significant bits. The structure; is defined
thusly:

struct ioc_pitch
{
short speed;

};

NOTES

When a CD-ROM is changed in a drive controlled by the cd
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 descrip
tors 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.
The audio code in the cd driver only support SCSI-2 standard
audio commands. As many CD-ROM manufacturers have not followed the
standard, there are many CD-ROM drives for which audio will not work.
Some work is planned to support some of the more common `broken' CD-ROM
drives; however, this is not yet under way.
The cd driver attempts to automatically determine whether
the drive it is talking to supports 6 byte or 10 byte MODE SENSE/MODE SELECT
operations. Many SCSI drives only support 6 byte commands, and ATAPI
drives only support 10 byte commands. The cd driver first attempts to de
termine 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 cd driver defaults to using 6
byte commands (assuming the protocol the drive speaks claims to support 6
byte commands), until one fails with a SCSI ILLEGAL REQUEST error.
Then it tries the 10 byte version of the command to see if that works in
stead. Users can change the default via per-drive sysctl variables and
loader tunables. The variable names are the same in both instances:
kern.cam.cd.%d.minimum_cmd_size
Where ``%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.

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 on
ly has one CD player mechanism. Each CD in the drive shows up as a sepa
rate logical unit on the SCSI bus. The cd driver automatically recog
nizes LUN-based changers, and routes commands for changers through an inter
nal scheduler. The scheduler prevents changer "thrashing", which is caused
by sending commands to different LUNs in the changer at the same time.
The scheduler honors minimum and maximum time quanta that
the driver will spend on a particular LUN. The minimum time is the guaran
teed 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 an
other LUN, the driver will allow indefinite access to a given LUN.
The minimum and maximum time quanta are configurable via
kernel options and also via sysctl and kernel tunable variables. The ker
nel options are:
options "CHANGER_MIN_BUSY_SECONDS=3" options "CHANGER_MAX_BUSY_SECONDS=11"
The sysctl/kernel tunable variables are:
kern.cam.cd.changer.min_busy_seconds kern.cam.cd.changer.max_busy_seconds
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.
If your system does have a LUN-based changer, you may notice
that the probe messages for the various LUNs of the changer will con
tinue to appear while the boot process is going on. This is normal,
and is caused by the changer scheduling code.

FILES

/dev/cd[0-9][a-h] raw mode CD-ROM devices

DIAGNOSTICS

None.

HISTORY

This cd driver is based upon the cd driver written by Julian
Elischer, which appeared in 386BSD 0.1. The CAM version of the cd
driver was written by Kenneth Merry and first appeared in FreeBSD 3.0.

BUGS

The names of the structures used for the third argument to
ioctl() were
poorly chosen, and a number of spelling errors have survived
in the names
of the ioctl() commands.
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. Implemen
tation of separate timeouts for different CD devices in the kernel config
file would likely require modification of config(8) to support the two
timeouts when hardwiring cd devices.
BSD September 2, 2003

docs.sk

comprehensive documentation repository

In section

See also

cd(4)

NAME

SYNOPSIS

DESCRIPTION

KERNEL CONFIGURATION

IOCTLS

NOTES

CHANGER OPERATION

FILES

DIAGNOSTICS

SEE ALSO

HISTORY

BUGS