Update to reflect the reality of the header files.

Make more effective use of -mdoc.

1 files changed, 320 insertions, 121 deletions

diff --git a/share/man/man4/cd.4 b/share/man/man4/cd.4
index 63fb60e..9984e03 100644
--- a/share/man/man4/cd.4
+++ b/share/man/man4/cd.4
@@ -1,61 +1,45 @@
-.Dd August 27, 1993
+.Dd January 16, 1996
 .Dt CD 4
 .Os FreeBSD
 .Sh NAME
 .Nm cd
-.Nd scsi cdrom driver
+.Nd SCSI CD-ROM driver
 .Sh SYNOPSIS
-.Nm device cd
-.Nm device cd1 target 4 lun 0
+.Cd device cd
+.Cd device cd1 at scbus0 target 4 lun 0
 .Sh DESCRIPTION
 The
-.Xr cd
+.Nm 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 
+.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
-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.
+.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 
-or 
+and
 .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 
+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
-.Em cd0
-and the next, 
-.Em cd1
+.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
@@ -63,121 +47,336 @@ come on line as; refer to
 for details on kernel configuration.
 .Pp
 The system utility
-.Xr disklabel 1
+.Xr disklabel 8
 may be used to read the synthesized
-.Xr disklabel 5
-structure, which will contain correct figures for the size of the cdrom
+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 cdroms may be attached to the system regardless of system
+Any number of
+.Tn CD-ROM
+devices 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
+calls which apply to
+.Tn SCSI
+.Tn CD-ROM
+drives are defined
 in the header files
-.Em sys/cdio.h.
+.Aq Pa sys/cdio.h
 and
-.Em sys/disklabel.h
-
-.Bl -tag -width CDIOCPLAYAUDIO____
-
+.Aq Pa sys/disklabel.h .
+.Pp
+.Bl -tag -width CDIOCREADSUBCHANNEL -compact
 .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	
+.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 CDIOCSETMUTE	
+
+.It Dv 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	
+
+.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 CDIOCSTART	
-Tell the drive to spin-up the cdrom.
-.It CDIOCSTOP	
-Tell the drive to spin-down the cdrom.
-.It CDIOCEJECT	
-Eject the cdrom.
+
+.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 fourth (raw/whole disk) partiton. (e.g. rcd0d)
+driver, if used against the `whole disk' partiton (i.e. 
+.Pa /dev/rcd0c ) .
 .Sh NOTES
-When a cdrom is changed in a drive controlled by the
+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
+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
+parameters (including disklabel) for the drive.
+.Pp
+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.
-
+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 scsi disks
+block mode
+.Tn CD-ROM
+devices
 .It Pa /dev/rcd[0-9][a-h]
-raw scsi disks
+raw mode
+.Tn CD-ROM
+devices
 .El
 .Sh DIAGNOSTICS
 None.
 .Sh SEE ALSO
-.Xr disklabel 1
+.Xr disklabel 1 ,
+.Xr scsi 4 ,
+.Xr sd 4 ,
 .Xr disklabel 5
-.Xr wd 4
-.Xr sd 4
+.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