425 lines
11 KiB
Groff
425 lines
11 KiB
Groff
.\" $NetBSD: cd.4,v 1.11 1999/03/16 01:19:15 garbled Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.Dd January 16, 1996
|
|
.Dt CD 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cd
|
|
.Nd SCSI and ATAPI CD-ROM driver
|
|
.Sh SYNOPSIS
|
|
.Cd "cd* at scsibus? target ? lun ?"
|
|
.Cd "cd1 at scsibus0 target 4 lun 0"
|
|
.Cd "cd* at atapibus? drive ? flags 0x0000"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm cd
|
|
driver provides support for a Small Computer Systems Interface
|
|
.Pq Tn SCSI
|
|
bus and Advanced Technology Attachment Packet Interface
|
|
.Pq Tn ATAPI
|
|
Compact Disc-Read Only Memory
|
|
.Pq Tn CD-ROM
|
|
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 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.
|
|
.Pp
|
|
For the use of flags with ATAPI devices, see
|
|
.Xr wd 4 .
|
|
.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
|
|
.Tn 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.
|
|
(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 CDIOCLOADUNLOAD
|
|
Cause the ATAPI changer to load or unload discs.
|
|
|
|
.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' partition (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 intro 4 ,
|
|
.Xr scsi 4 ,
|
|
.Xr sd 4 ,
|
|
.Xr disklabel 5 ,
|
|
.Xr disklabel 8
|
|
.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
|
|
The
|
|
.Nm
|
|
driver appeared in
|
|
.Tn 386BSD 0.1 Ns .
|