xref: /freebsd/share/man/man4/cd.4 (revision 2460bdf04b0eb93f70841c7063e443fdf5f31adb)

.Dd August 27, 1993
.Dt CD 4
.Os FreeBSD
.Sh NAME
.Nm cd
.Nd scsi cdrom driver
.Sh SYNOPSIS
.Nm device cd
.Nm device cd1 target 4 lun 0
.Sh DESCRIPTION
The
.Xr cd
driver provides support for a
.Em scsi
cdrom. It allows the cdrom
to be divided up into a set of pseudo devices called
.Em partitions.
In an attempt to look like regular disks the
.Nm
driver synthesises a partition table, with one partition covering the entire
cdrom. A user might (for some amazing reason) add another partition to the
cdrom by using disklabel, but it will last only until the cdrom is unmounted.
A Partition can have both a
.Em raw
interface
and a
.Em Block mode
interface.
In general the interfaces are similar to those described by
.Xr wd 4
or
.Xr sd 4 .

.Pp
Where the
.Xr wd 4
device has a fairly low level interface to the system,
.Em SCSI
devices have a much higher level interface and talk to the system via
a
.Em SCSI Adapter
and a
.Em Scsi Adapter driver
e.g.
.Xr AHA1542 .
A scsi adapter must also be separatly configured into the system
before a scsi cdrom can be configured.
.Pp
As the scsi adapter is probed during boot, the
.Em SCSI
bus is scanned for devices. Any devices found which answer as 'Readonly'
type devices will be 'attached' to the
.Nm
driver.
In FreeBSD releases prior to 2.1, the first found will be attached as
.Em cd0
and the next,
.Em 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 1
may be used to read the synthesized
.Xr disklabel 5
structure, which will contain correct figures for the size of the cdrom
should that information be required.
.Pp
.Sh KERNEL CONFIGURATION
Any number of cdroms may be attached to the system regardless of system
configuration as all resources are dynamically allocated.

.Pp
.Sh IOCTLS
The following
.Xr ioctl 2
calls apply to scsi cdroms
in the header files
.Em sys/cdio.h.
and
.Em sys/disklabel.h

.Bl -tag -width CDIOCPLAYAUDIO____

.It Dv DIOCGDINFO
Read, from the kernel, the in-core copy of the disklabel for the
drive. This will be a ficticious disklabel it will contain information
read from the scsi inquiry commands, and should be the same as
the information printed at boot.
.It Dv DIOCSDINFO
Give the driver a new disklabel to use. The driver will NOT try write the new
disklabel to the disk. (ok?)
.It CDIOCPLAYTRACKS
Start Audio playback given a track address and length.
.It CDIOCPLAYBLOCKS
Start Audio playback given a block address and length.
.It CDIOCPLAYMSF
Start Audio playback given a 'Minutes/ seconds/ frames' address and length.
.It CDIOCREADSUBCHANNEL
Read information from the subchannel at the location specified.
.It CDIOREADTOCHEADER
Return summary information about the table of contents for the mounted cdrom.
.It CDIOREADTOCENTRYS
Return information from the table of contents entries mentionned.
.It CDIOCSETPATCH
Attach various audio channels to various output channels.
.It CDIOCGETVOL
Get information about the volume settings of the output channels.
.It CDIOCSETVOL
Change the volume settings of the output channels.
.It CDIOCSETMONO
Patch all out[put channels to all source channels.
.It CDIOCSETSTERIO
Patch left source channel to the left output channel and the right
source channel to the right output channel.
.It CDIOCSETMUTE
Mute output without changing the volume settings.
.It CDIOCSETLEFT
Attach both output channels to the left source channel.
.It CDIOCSETRIGHT
Attach both output channels to the right source channel.
.It CDIOCSETDEBUG
Turn on debugging for the appropriate device.
.It CDIOCCLRDEBUG
Turn off debugging for the appropriate device.
.It CDIOCPAUSE
Pause audio play, do not reset the location of the read-head.
.It CDIOCRESUME
Resume audio play, Start at the location of the pause.
.It CDIOCRESET
Reset the drive.
.It CDIOCSTART
Tell the drive to spin-up the cdrom.
.It CDIOCSTOP
Tell the drive to spin-down the cdrom.
.It CDIOCEJECT
Eject the cdrom.
.El
.Pp
In addition the general
.Xr scsi 4
ioctls may be used with the
.Nm
driver, if used against the fourth (raw/whole disk) partiton. (e.g. rcd0d)
.Sh NOTES
When a cdrom 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
figures (including disklabel) for the drive.

The Audio code in the
.Nm
driver only support SCSI2 standard audio commands. As there are many cdrom
manufacturers who have not followed the standard well, there are many
cdroms for which audio will not work. Some work is planned to support
some of the more common 'broken' cdrom 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 scsi disks
.It Pa /dev/rcd[0-9][a-h]
raw scsi disks
.El
.Sh DIAGNOSTICS
None.
.Sh SEE ALSO
.Xr disklabel 1
.Xr disklabel 5
.Xr wd 4
.Xr sd 4
.Sh HISTORY
This
.Nm
driver appeared in 386BSD 0.1.