diff --git a/share/man/man4/man4.i386/matcd.4 b/share/man/man4/man4.i386/matcd.4 new file mode 100644 index 00000000000..0edbba7f25f --- /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. +