A new man page for the matcd driver.

Submitted by:   Frank Durda IV <uhclem%nemesis@fw.ast.com>

1 files changed, 370 insertions, 0 deletions

diff --git a/share/man/man4/man4.i386/matcd.4 b/share/man/man4/man4.i386/matcd.4
new file mode 100644
index 0000000..0edbba7
--- /dev/null
+++ b/share/man/man4/man4.i386/matcd.4
@@ -0,0 +1,370 @@
+.\"Matsushita(Panasonic) / Creative CD-ROM Driver	(matcd)
+.\"Authored by Frank Durda IV
+.\"
+.\"Program and Documentation are Copyright 1994, 1995  Frank Durda IV.
+.\"All rights reserved.  
+.\" "FDIV" is a trademark of Frank Durda IV.
+.\"
+.\"
+.\"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 positioned at the very beginning of this file without
+.\"    modification, all copyright strings, all related programming
+.\"    codes that display the copyright strings, this list of
+.\"    conditions and the following disclaimer.
+.\"2.  Redistributions in binary form must contain all copyright strings
+.\"    and related programming code that display the copyright strings.
+.\"3.  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.
+.\"4.  All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgement:
+.\"	"The Matsushita/Panasonic CD-ROM driver  was developed
+.\"	 by Frank Durda IV for use with "FreeBSD" and similar
+.\"	 operating systems."
+.\"    "Similar operating systems" includes mainly non-profit oriented
+.\"    systems for research and education, including but not restricted
+.\"    to "NetBSD", "386BSD", and "Mach" (by CMU).  The wording of the
+.\"    acknowledgement (in electronic form or printed text) may not be
+.\"    changed without permission from the author.
+.\"5.  Absolutely no warranty of function, fitness or purpose is made
+.\"    by the author Frank Durda IV.
+.\"6.  Neither the name of the author nor the name "FreeBSD" may
+.\"    be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"    (The author can be reached at   bsdmail@nemesis.lonestar.org)
+.\"7.  The product containing this software must meet all of these
+.\"    conditions even if it is unsupported, not a complete system
+.\"    and/or does not contain compiled code.
+.\"8.  These conditions will be in force for the full life of the
+.\"    copyright.  
+.\"9.  If all the above conditions are met, modifications to other
+.\"    parts of this file may be freely made, although any person
+.\"    or persons making changes do not receive the right to add their
+.\"    name or names to the copyright strings and notices in this
+.\"    software.  Persons making changes are encouraged to insert edit
+.\"    history in matcd.c and to put your name and details of the
+.\"    change there.  
+.\"10. You must have prior written permission from the author to
+.\"    deviate from these terms.
+.\"
+.\"Vendors who produce product(s) containing this code are encouraged 
+.\"(but not required) to provide copies of the finished product(s) to
+.\"the author and to correspond with the author about development
+.\"activity relating to this code.   Donations of development hardware
+.\"and/or software are also welcome.  (This is one of the faster ways
+.\"to get a driver developed for a device.)
+.\"
+.\" 	THIS SOFTWARE IS PROVIDED BY THE DEVELOPER(S) ``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 DEVELOPER(S) 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.
+.\"
+.\"--------------------------------------------------------------------------
+.\"Dedicated to:	My family and Max, my Golden Retriever
+.\"-----No changes are allowed above this line-------------------------------
+.\"
+.\"	Please note any documentation updates here including your name
+.\"	and the date.
+.\"
+.Dd April 5th, 1995
+.Dt MATCD 4 i386
+.\"Synchronized to Version 1(16) of matcd.c
+.Os FreeBSD 2.1
+.Sh NAME
+.Nm matcd
+.Nd Matsushita (Panasonic) CD-ROM driver
+.Sh SYNOPSIS
+.sp
+.Cd "controller matcd[0-4] at isa? port [?| addr]"
+.br
+.Cd "/dev/[r]matcd[0-15][a|c]
+.br
+.Cd "/dev/[r]matcdl[0-15][a|c]
+.sp
+.Sh DESCRIPTION
+The
+.Nm matcd
+driver controls the CR-562-x and CR-563-x CD-ROM drives made by
+Matsushita-Kotobuki Electronics Industries, or Matsushita for short.
+These CD-ROM drives have been sold under the Panasonic (which is a trade
+name for Matsushita), Creative Labs (omniCD) and Reveal names, and have
+been included in computers made by Tandy, AST, Packard Bell and many others.
+
+These drives connect to the PC ISA bus through a proprietary host interface.
+This interface can exist as a stand-alone ISA card, or can be included on
+a sound card.  
+
+.Sh DRIVER CONFIGURATION
+The
+.Nm matcd
+driver supports up to four host interfaces with up to four drives on each
+interface.  Audio activity may occur on all drives simultaneously.  Data
+read operations are limited to one drive per host interface at any instant.
+
+To support multiple host interfaces, it is necessary to modify the
+entries in the kernel configuration file.  Normally your system comes
+with the file \fI/usr/src/sys/i386/conf/GENERIC\fR.  You should make
+a copy of this file and give it the name of your system. 
+You can then edit the new file to include devices you want the system
+to support and delete the device entries that you don't want.
+
+In this file, you will find an entry like:
+
+	controller matcd0 at isa? port ?
+
+To support two host interfaces, change the file so it reads:
+
+	controller matcd0 at isa? port ?
+.br
+	controller matcd1 at isa? port ?
+.br
+
+(If you want to support up to three or four host interfaces, add
+additional entries).
+.if n .bp
+.if t .sp
+Note that the kernel configuration does not need to be modified to support
+up to four drives on a single host interface.  It is also not necessary to 
+have four drives on a single interface before adding a second interface.
+
+By default,
+.Nm matcd
+searches for the CD-ROM host interface adapters by using a table of known I/O
+ports (see \fIoptions.h\fR).  Although this
+is very flexible, it can cause problems when your system has other devices
+that are located at the I/O ports that 
+.Nm matcd 
+is checking for CD-ROM host interfaces.  In addition, checking multiple
+locations can cause the boot process to take longer than it could.
+.if t .bp
+.if n .sp
+If you are having these problems, you can solve them by explicitly specifying
+where the CD-ROM host interfaces are located.  For example, by default most
+SoundBlaster cards have the Matsushita CD-ROM host interface
+located at I/O port 0x230.  If this is the case for your system, you could
+change the entry in the kernel configuration file to specify that address
+like this:
+
+	controller  matcd0  at  isa?  port  0x230
+
+With this change, the
+.Nm matcd
+driver will only look at I/O port 0x230 for the first CD-ROM host interface
+and will not disturb any other I/O ports.
+
+Once you have adjusted the kernel configuration file, it is necessary
+to configure and recompile the kernel, install it and reboot for the
+changes to take effect.
+.Sh SUPPORTED HARDWARE
+At this time, there are only two known drive models that work with the
+.Nm matcd
+driver:
+.Bl -tag -width CR-123-X -compact -offset indent
+.br
+.It Matsushita CR-562-x
+.br
+.It Matsushita CR-563-x
+.br
+.El
+Most resellers leave these original markings on the drives since the label
+also has the FCC, VDE, CSA and RU certification marks.  
+
+Both of these drive models have motorized trays.  There is also a custom
+version of these drives that does not have the volume control or headphone
+jack (seen on some Tandy computers), but this drive also works with
+.Nm matcd.
+
+The Matsushita CR-523-x CD-ROM drive is not usable with 
+.Nm matcd.
+The CR-523 can also be identified from the front as it requires a CD-caddy.
+Drives with IDE interfaces must use an IDE driver.
+
+There is a new TEAC 4X CD-ROM drive on the market that supposedly uses the
+Creative/Panasonic interface.  It is not known if the TEAC drive is
+command-set-compatible with the Matsushita drive so it may not work with
+this driver.
+.if t .sp
+.if n .bp
+The most common source of host interface adapters for these drives are in
+products from Creative Labs, including SoundBlaster sound cards.   There
+are numerous models of SoundBlaster sound cards, and most of the newer cards
+provide the appropriate interface, sometimes labeled as the
+"Creative/Panasonic" interface.
+
+The following host interface adapters are known to work with the
+.Nm matcd
+driver:
+.Bl -tag -width LONGNAME -compact -offset indent
+.It Creative
+Sound Blaster Pro (SBPRO) (CT1330A)
+.It Creative 
+Sound Blaster 16 (CT1730)
+.It Creative
+Sound Blaster 16 - cost-reduced (CT1740)
+.It Creative
+OmniCD upgrade kit adapter card - stand-alone CD (CT1810)
+.It Creative
+Sound Blaster 16 - 2-layer, cost-reduced  (CT2230)
+.It Creative
+Sound Blaster 16 Value (SB16) - 2-layer, cost-reduced (CT2770)
+.It Creative
+PhoneBlaster SB16 + Sierra 14.4K Voice/FAX/Data/Speakerphone modem combo (CT3100)
+.El
+
+Caution: Some of these sound boards can be optionally manufactured to not
+include the Panasonic/Creative interface, so check the board before buying
+solely based on model number.
+
+This is by no means a complete list as Creative Labs and other vendors
+that produce sound cards with an identical Creative/Panasonic drive
+interface release new versions of their adapters all the time.
+.br
+.if t .bp
+.if n .sp
+.Sh SUPPORTED OPERATIONS
+The
+.Nm matcd
+driver supports block and character access.  Partition "a" returns
+2048-byte User Data blocks from data CDs.  Partition "c" returns the full
+2352-byte Frames from any type of CD, including audio CDs.  (Partition
+"c" cannot be "mounted" with cd9660 or other filesystem emulators.)
+No other partitions are supported.
+
+The 
+.Nm matcdl
+devices work the same as the normal
+.Nm matcd
+devices except that the drive trays are locked and
+remain locked until all of the devs on that drive are closed.
+.if n .bp
+.if t .sp
+.Nm Matcd 
+accepts the numerous 
+.Fn ioctl
+commands, including disk and functions related to CD-ROM  audio and tray
+control features.  The commands are:
+.sp
+.Bl -tag -width CDIOCREADSUBCHANNELXXX -compact -offset indent
+.It DIOCGDINFO
+get disklabel.
+.It DIOCGDPART
+get partition.
+.It DIOCWDINFO
+set update disk.
+.It DIOCSDINFO
+set disklabel.
+.It CDIOCREADSUBCHANNEL
+get sub-channel information on current status of disc playing.
+.It CDIOCREADTOCHEADER
+reads table of contents summary.
+.It CDIOCREADTOCENTRYS
+reads length and other track information.
+.It CDIOCPLAYTRACKS
+plays audio starting at a track/index and stopping at a track/index.
+.It CDIOCPLAYMSF
+plays audio starting at a particular time offset.
+.It CDIOCPAUSE
+pauses a playing disc.
+.It CDIOCRESUME
+resumes playing a previously paused disc.  Ignored if the drive is
+already playing.
+.It CDIOCSTOP
+stops playing a disc.
+.It CDIOCEJECT
+opens the disc tray.
+.It CDIOCCLOSE
+closes the disc tray.
+.It CDIOCGETVOL
+returns the current volume settings of the drive.
+.It CDIOCSETVOL
+sets the volume settings of the drive.
+.It CDIOCSETSTEREO
+causes the left channel audio to be sent to the left channel output and the
+right channel audio is sent to the right channel output.  This is the
+default state.
+.It CDIOCSETMUTE
+causes the audio output to be turned off.  The drive continues to read
+the audio on the disc and that audio is discarded until the audio is
+turned back on.
+.It CDIOCSETLEFT
+causes the left channel audio to be sent to the left and right channel outputs.
+.It CDIOCSETRIGHT
+causes the right channel audio to be sent to the left and right channel
+outputs.
+.It CDIOCSETPATCH
+causes the audio to be routed as specified in the provided bit maps.
+.It CDIOCSETPITCH
+changes the playback speed of the audio to increase or decrease
+(as in Karaoke).
+.It CDIOCCAPABILITY
+report the capabilities of the drive and driver.
+.El
+.Pp
+The
+.Fn ioctl
+commands defined above are the only ones that the
+.Nm matcd
+driver supports. 
+.bp
+.Sh FILES
+.Bl -tag -width /dev/(r)matcd0a_/dev/(r)matcdl0a -compact
+.It Pa /dev/[r]matcd0a /dev/[r]matcdl0a
+is used to access 2048-byte blocks of data on a CD-ROM disc
+that is recorded in the Mode 1 Form 1 format.  
+.It Pa /dev/[r]matcd0c /dev/[r]matcdl0c
+is used to access 2352-byte frames on a CD-ROM disc
+recorded in any format.
+.It Pa /usr/src/sys/i386/isa/matcd/*
+Source code and compilation options for 
+.Nm matcd.
+.El
+
+The file \fIoptions.h\fR contains all of the compilation options.
+By default, the driver is configured to run on the current version of
+FreeBSD.  
+.Sh NOTES
+.Pp
+The Creative/Panasonic interface does not use interrupts or DMA
+although the drives themselves are capable of using both.
+
+If the disc tray is opened while one or more partitions are open, further
+I/O to all partitions on the drive will be rejected until all partitions
+are closed.
+
+There must be a drive on each host interface that is addressed as
+physical drive 0.  If this isn't the case, the driver will be unable
+to find the host interface or any of the connected drives.
+
+Drives on a second host interface start are considered logical
+drives 4-7, 8-11 on the third interface and 12-15 on the fourth.
+
+The first drive on the second host interface is logical drive 4 regardless
+of how many drives are present on the first host interface.
+
+Host interfaces are numbered in the order they are declared in the
+kernel configuration file, or in the order they are found if the kernel
+configuration file uses "?" for the port address.  Host interface
+numbers are always contiguous.
+.Sh SEE ALSO
+.Pa /usr/include/sys/cdio.h
+.Sh AUTHOR
+The driver and documentation was written by Frank Durda IV.
+.br
+Program and Documentation are Copyright 1994, 1995, 
+All rights reserved.  
+.Sh HISTORY
+The
+.Nm matcd
+driver appeared in FreeBSD Release 2.1.
+