384 lines
9.3 KiB
Groff
384 lines
9.3 KiB
Groff
.Dd January 16, 1996
|
|
.Dt CD 4
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm cd
|
|
.Nd SCSI CD-ROM driver
|
|
.Sh SYNOPSIS
|
|
.Cd device cd
|
|
.Cd device cd1 at scbus0 target 4 lun 0
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm cd
|
|
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 synthesises 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 wd 4
|
|
and
|
|
.Xr sd 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 `Read-only'
|
|
type devices will be `attached' to the
|
|
.Nm
|
|
driver.
|
|
In FreeBSD releases prior to 2.1, the first found will be attached as
|
|
.Li cd0
|
|
the next,
|
|
.Li cd1 ,
|
|
etc.
|
|
Beginning in 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.
|
|
.Pp
|
|
.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
|
|
.Aq Pa sys/cdio.h
|
|
and
|
|
.Aq Pa sys/disklabel.h .
|
|
.Pp
|
|
.Bl -tag -width CDIOCREADSUBCHANNEL -compact
|
|
.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 countrol 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. (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
|
|
.Pp
|
|
In addition the general
|
|
.Xr scsi 4
|
|
ioctls may be used with the
|
|
.Nm
|
|
driver, if used against the `whole disk' partiton (i.e.
|
|
.Pa /dev/rcd0c ) .
|
|
.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. Because 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 FILES
|
|
.Bl -tag -width /dev/rcd[0-9][a-h] -compact
|
|
.It Pa /dev/cd[0-9][a-h]
|
|
block mode
|
|
.Tn CD-ROM
|
|
devices
|
|
.It Pa /dev/rcd[0-9][a-h]
|
|
raw mode
|
|
.Tn CD-ROM
|
|
devices
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
None.
|
|
.Sh SEE ALSO
|
|
.Xr disklabel 1 ,
|
|
.Xr scsi 4 ,
|
|
.Xr sd 4 ,
|
|
.Xr disklabel 5
|
|
.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.
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
driver appeared in 386BSD 0.1.
|