diff options
author | wollman <wollman@FreeBSD.org> | 1996-01-16 21:29:43 +0000 |
---|---|---|
committer | wollman <wollman@FreeBSD.org> | 1996-01-16 21:29:43 +0000 |
commit | 607a724a0bfd79a316f83b4d50bc26b07d8bd8da (patch) | |
tree | dffcbd9987e0728840b67541d2a0d79421018058 /share/man/man4/cd.4 | |
parent | b95047ce04962012e146d857f04e6a7158273ba3 (diff) | |
download | FreeBSD-src-607a724a0bfd79a316f83b4d50bc26b07d8bd8da.zip FreeBSD-src-607a724a0bfd79a316f83b4d50bc26b07d8bd8da.tar.gz |
Update to reflect the reality of the header files.
Make more effective use of -mdoc.
Diffstat (limited to 'share/man/man4/cd.4')
-rw-r--r-- | share/man/man4/cd.4 | 441 |
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 |