freebsd-dev/share/man/man4/cd.4

.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.