HardenedBSD/share/man/man4/man4.i386/matcd.4

.\"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.
.\"<2>	Text brought in sync with changes made in versions 1(17) - 1(21)
.\"	Frank Durda IV	4-Jul-95
.\"<3>	Text brought in sync with changes made in versions 1(22) - 1(25)
.\"	Frank Durda IV  24-Sep-95
.\"
.Dd September 24th, 1995
.Dt MATCD 4 i386
.\"Synchronized to Version 1(25) of matcd.c
.Os FreeBSD 2.0.5
.Sh NAME
.Nm matcd
.Nd Matsushita (Panasonic) CD-ROM driver
.Sh SYNOPSIS
.Pp
.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]
.Pp
.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  ?  bio

To support two host interfaces, change the file so it reads:

	controller  matcd0  at  isa?  port  ?  bio
.br
	controller  matcd1  at  isa?  port  ?  bio
.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 on Creative host adapters (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.  (This is 0x10 above the I/O port for the
audio section of the card.)  If this is the case for your system, you could
change where the kernel looks for the hardware by using the -c option at
the kernel boot prompt.  This will load the kernel and then give you the
opportunity to change settings for any of the devices included the kernel.
For example, to change the I/O port for
.Nm matcd
adapter zero to 0x340, you would type

	config> port matcd0c 0x340

If you recompile the kernel, you can change the entry in the kernel
configuration file to specify a specific address by changing an entry
like this:

	controller  matcd0  at  isa?  port  0x230  bio

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-522-x and CR-523-x CD-ROM drive is not usable with 
.Nm matcd.
The CR-522 and CR-523 can also be identified from the front as it
requires a CD-caddy.

Drives with IDE interfaces must use an IDE driver.

The TEAC CD-55 4X CD-ROM drive also uses the Creative/Panasonic interface
but the TEAC drive is \fInot\fR compatible with the Matsushita CR-56x drives.  
The TEAC drive cannot be used with 
.Nm matcd.
.if t .sp
.if n .bp
The most common source of host interface adapters for the Panasonic drives
are found 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 (Vibra16) - 2-layer, single-chip (CT2260)
.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)
.It Reveal
(SC400)
.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.

In addition to Creative Labs adapters, adapters that are compatible with
Media Vision, IBM and Lasermate adapters are also supported.   However,
these adapters use a wide range of I/O port addresses, so the driver
must be reconfigured to locate these adapters.   

It is important to understand that some manufacturers have a different
host interface implementation.  If you have a board that won't communicate
with the drives under MS-DOS using the genuine Creative Labs drivers, then
.Nm matcd
may not work with that host adapter.
.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 numerous 
.Fn ioctl
commands, including disk and functions related to CD-ROM audio and tray
control features.  The commands are:
.Pp
.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 CDIOCPREVENT
blocks further attempts to open the drive door until all devices close
or a CDIOCALLOW ioctl is issued.
.It CDIOCALLOW
unlocks the drive door if it was locked.  This ioctl is rejected if
any locking devices are open.
.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
.Fx 2.0.5 .

509253