MATCD(4)     FreeBSD Kernel Interfaces Manual (i386 Architecture)     MATCD(4)

NNAAMMEE
     mmaattccdd - Matsushita (Panasonic) Compact Disc drive driver

SSYYNNOOPPSSIISS
     ddeevviiccee mmaattccdd

     In _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s:
     hhiinntt..mmaattccdd.._[_0_-_3_]..aatt==""iissaa""
     hhiinntt..mmaattccdd.._[_0_-_3_]..ppoorrtt==""_a_d_d_r_e_s_s""

DDEESSCCRRIIPPTTIIOONN
     The mmaattccdd driver controls the CR-562 and CR-563 Compact Disc drives made
     by Matsushita-Kotobuki Electronics Industries, or Matsushita for short.
     These drives were sold under the Panasonic (which is a trade name for
     Matsushita), Creative Labs (omniCD) and Reveal names, and were also
     included in computers that were made by Tandy, GRiD, Victor, AST, Packard
     Bell and many other brands.

     The drives are compatible with the major the Compact Disc standards,
     including CD-DA (Red Book - Digital Audio on pressed media), CD-WO
     (Orange Book Part II - Write-Once media), CD-ROM (Yellow Book - Data
     Storage), and the Kodak Photo-CD system.  The drives have some support
     related to CD-ROM XA and CD-I (Green Book) audio and data requirements.

     These drives connect to the PC ISA bus through a simple (but proprietary)
     host interface.  The host interface has been manufactured as a stand-
     alone adapter card, or included on a sound card or other multi-function
     adapter card.  The mmaattccdd driver supports up to four host interfaces with
     up to four drives on each interface.  CD-DA (digital audio) activity may
     occur on all drives simultaneously.

     The drive hardware supports a "bus disconnect" system similar to that
     found in SCSI, and this allows simultaneous data read operations to be in
     progress on multiple drives on the same host interface, but the driver
     currently limits read operations to one active drive per host interface
     at a time.  Despite this, all four drives on a given host interface are
     able deliver data at their full rated transfer rate for sequential blocks
     simultaneously, thanks to a modest read-ahead buffer in each drive.

DDRRIIVVEERR IINNSSTTAALLLLAATTIIOONN
     The mmaattccdd driver can be directly linked into the FreeBSD kernel, or exist
     as a loadable FreeBSD kernel module.  The kernel module can be loaded or
     unloaded at any time using the kkllddllooaadd(8)/kklldduunnllooaadd(8) commands.

     For most configurations, the mmaattccdd driver should be used as a loadable
     kernel module and need not be linked into the kernel.  However, if you
     are attempting to do an install from a CD-ROM/CD-WO disc that is initi-
     ated from a non-FreeBSD operating system or you have a BIOS boot capabil-
     ity for this type of Compact Disc drive, having the driver already in the
     kernel can simplify the installation process.

     if you determine that you need to have the mmaattccdd driver linked into the
     kernel, it is necessary to add an entry to the kernel configuration file
     and generate a new kernel.  The FreeBSD kernel source tree comes with the
     file _/_u_s_r_/_s_r_c_/_s_y_s_/_i_3_8_6_/_c_o_n_f_/_G_E_N_E_R_I_C.  You should make a copy of this file
     and give the copy the name of your system, such as "MYSYSTEM".  You can
     then edit the new file to include devices you want the system to include
     in the basic kernel and delete the device entries for drivers that you
     don't want included.  Eliminating drivers for hardware that you don't
     have can reduce the size of the finished kernel.

     To include the mmaattccdd driver to the configuration file, you will need to
     add this entry:

           device  matcd

     and after making any other adjustments, save the file.

     Then generate a new kernel by using the ccoonnffiigg(8) command and follow all
     of the instructions that are displayed.  If the kernel completely builds,
     use the "make install" command and then reboot the system for that new
     kernel to become operational.

DDRRIIVVEERR CCOONNFFIIGGUURRAATTIIOONN
     Regardless of whether the mmaattccdd driver is linked into the kernel or is
     used as a loadable kernel module, the number of host interfaces that the
     driver will expect (or search for) is dictated by the number of entries
     present in the file _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s.  For example, in order to support
     two host interfaces, you would include entries like:

           hint.matcd.0.at="isa"
           hint.matcd.0.port="0x230"

           hint.matcd.1.at="isa"
           hint.matcd.1.port="0x260"

     Each set of entries designates a different mmaattccdd host interface, and
     where the I/O ports on that host interface adapter are located.

     (If you only want a single entry, include only the hhiinntt..mmaattccdd..00 items,
     while add hhiinntt..mmaattccdd..22 and hhiinntt..mmaattccdd..33 as needed to support three or
     four host interfaces.)

     Note that the two hhiinntt..mmaattccdd..00 entries in the _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s file are
     all that you need to support up to four drives on a single host inter-
     face.

     If the _a_d_d_r_e_s_s parameter of a hhiinntt..mmaattccdd.._n.port="_a_d_d_r_e_s_s" entry in
     _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s file is set to "--11", the mmaattccdd driver searches for the
     host interface adapters by using a table of known I/O ports on Creative
     host adapters contained in the driver itself (see
     _/_u_s_r_/_s_r_c_/_s_y_s_/_d_e_v_/_m_a_t_c_d_/_o_p_t_i_o_n_s_._h).

     Although the multiple port scan allows the mmaattccdd driver to work with many
     different types of host adapters without adjustments, using this mecha-
     nism has the potential to cause problems when your system has other
     devices that are located at the I/O ports that the driver will check for
     potential mmaattccdd host interfaces.  The automatic search also significantly
     increases the amount of time it takes to boot or to load the kernel mod-
     ule.

     If you are having problems with the mmaattccdd driver interfering with other
     adapters while it is probing for hardware, or you don't like the addi-
     tional amount of time it takes for the entire search of I/O ports to com-
     plete, you can solve this by explicitly specifying where all the mmaattccdd
     host interfaces are located.

     Traditionally, Creative Labs SoundBlaster cards have the Matsushita Com-
     pact Disc drive host interface located at I/O port 0x230, which is always
     0x10 above where the first I/O port for the audio section of the card
     (0x220).

     If you have determined exactly where the Matsushita I/O ports start on
     your system, specify the port by setting the hhiinntt..mmaattccdd.._n.port="_a_d_d_r_e_s_s"
     entry at the kernel boot prompt, or by editing the entry in the
     _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s file.

     If you make a change to the _/_b_o_o_t_/_d_e_v_i_c_e_._h_i_n_t_s configuration file while
     the system is running, it is currently necessary to reboot the system
     before the updated values take effect.

SSUUPPPPOORRTTEEDD HHAARRDDWWAARREE
     At this time, there are only two known drive models that work with the
     mmaattccdd driver:
           Matsushita CR-562-x
           Matsushita CR-563-x
     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 head-
     phone jack (seen on some Tandy computers), but this drive also works with
     mmaattccdd.  On drives that lack a front headphone jack, audio from discs can
     still be obtained at line level via a connector on the rear of the drive.

     The Matsushita CR-522-x and CR-523-x Compact Disc drives are not usable
     with mmaattccdd.  The CR-522 and CR-523 models can also be identified from the
     front as they both require a CD-caddy.

     Later versions of Matsushita and "Creative" Compact Disc drives use a
     basic IDE interface, so these other drives must use an IDE driver, such
     as aattaa(4).

     The TEAC CD-55 4X Compact Disc drive also uses the same Creative/Pana-
     sonic electrical interface, but the TEAC drive is not command set compat-
     ible with the Matsushita CR-56x drives.  The TEAC drive cannot be used
     with mmaattccdd.

     The most common source of host interface adapters for the Panasonic
     drives was 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 mmaattccdd
     driver:
           Creative  Sound Blaster Pro (SBPRO) (CT1330A)
           Creative  Sound Blaster 16 (CT1730)
           Creative  Sound Blaster 16 - cost-reduced (CT1740)
           Creative  OmniCD upgrade kit adapter card - stand-alone CD (CT1810)
           Creative  Sound Blaster 16 - 2-layer, cost-reduced  (CT2230)
           Creative  Sound Blaster 16 (Vibra16) - 2-layer, single-chip
                     (CT2260)
           Creative  Sound Blaster 16 Value (SB16) - 2-layer, cost-reduced
                     (CT2770)
           Creative  PhoneBlaster SB16 + Sierra 14.4K Voice/FAX/Data/Speaker-
                     phone modem combo (CT3100)
           Reveal    (SC400)

     Caution: Some of these sound boards can be optionally manufactured to not
     include the Panasonic/Creative interface connector and electronics, so
     check the board visually to verify that the "Creative" or "Panasonic"
     drive connector is actually there before buying the card 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 released many versions of compatible adapters.

     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, at least initially.

SSUUPPPPOORRTTEEDD OOPPEERRAATTIIOONNSS
     The mmaattccdd 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 standard filesys-
     tem emulators.)  No other partitions are supported.

     The mmaattccddll devices work the same as the normal mmaattccdd devices except that
     the drive trays are locked and remain locked until all of the devs on
     that drive are closed.

     MMaattccdd accepts numerous iiooccttll() commands, including functions related to
     Compact Disc audio and drive tray control features.  The commands are:

           DIOCGDINFO              get disklabel.
           CDIOCREADSUBCHANNEL     report the current optical pick-up position
                                   and sub channel data.
           CDIOCREADTOCHEADER      reads table of contents summary from the
                                   disc.
           CDIOCREADTOCENTRYS      reads length/size and other control infor-
                                   mation for an individual track.
           CDIOCPLAYTRACKS         plays audio starting at a track/index and
                                   stopping at a track/index.
           CDIOCPLAYBLOCKS         plays audio starting at a block and stop-
                                   ping at a block.
           CDIOCPLAYMSF            plays audio starting at a particular time
                                   offset.
           CDIOCPAUSE              pauses a playing disc.
           CDIOCRESUME             resumes playing a previously paused disc.
                                   Ignored if the drive is already playing.
           CDIOCSTOP               stops playing a disc.
           CDIOCEJECT              opens the disc tray.
           CDIOCCLOSE              closes the disc tray.
           CDIOCPREVENT            blocks further attempts to open the drive
                                   door until all devices close or a CDIOCAL-
                                   LOW ioctl is issued.
           CDIOCALLOW              unlocks the drive door if it was locked.
                                   This ioctl is rejected if any locking
                                   devices are open, so it must be issued via
                                   a non-locking device.
           CDIOCGETVOL             returns the current volume settings of the
                                   drive.
           CDIOCSETVOL             sets the volume settings of the drive.
           CDIOCSETSTEREO          the left channel audio is sent to the left
                                   channel output and the right channel audio
                                   is sent to the right channel output.  This
                                   is the default state.  (Note that the drive
                                   does not have a documented "Mono" mode,
                                   where L combined with R audio from the disc
                                   is sent to both the left and right output
                                   channels.)
           CDIOCSETMUTE            the audio output is to be turned off.  The
                                   drive continues to read the audio on the
                                   disc and that audio is discarded until the
                                   audio routing is turned back on.
           CDIOCSETLEFT            the left channel audio is to be sent to the
                                   left and right channel outputs.  The right
                                   channel audio signal is discarded.
           CDIOCSETRIGHT           the right channel audio is to be sent to
                                   the left and right channel outputs.  The
                                   left channel audio signal is discarded.
           CDIOCSETPATCH           the audio is to be routed as specified in
                                   the provided bit maps.
           CDIOCSETPITCH           the playback speed of the audio is
                                   increased or decreased (for Karaoke "off-
                                   key" applications).  Speed can be adjusted
                                   +/-13%.
           CDIOCCAPABILITY         report the capabilities of the drive and
                                   driver.  Results are returned as shown in
                                   _/_u_s_r_/_i_n_c_l_u_d_e_/_s_y_s_/_c_d_i_o_._h.

     The iiooccttll() commands defined above are the only ones that the mmaattccdd
     driver supports.

FFIILLEESS
     /dev/matcd[0-15]a                 Used to access 2048-byte blocks of data
                                       on a Compact Disc that is recorded in
                                       the Mode 1 Form 1 format.
     /dev/matcd[0-15]la                Used to access 2048-byte blocks of data
                                       on a Compact Disc that is recorded in
                                       the Mode 1 Form 1 format and disables
                                       the disc eject controls.
     /dev/matcd[0-15]c                 Used to access 2352-byte frames on a
                                       Compact Disc recorded in any format.
     /dev/matcd[0-15]lc                Used to access 2352-byte frames on a
                                       Compact Disc recorded in any format and
                                       disables the disc eject controls.
     /boot/devices.hints               Specify the number of host interfaces
                                       and host adapter I/O port locations
                                       that mmaattccdd should examine.
     /usr/src/sys/dev/matcd/*          Source code for mmaattccdd.
     /usr/src/sys/dev/matcd/options.h  Contains all of the compilation options
                                       for mmaattccdd.

NNOOTTEESS
     The various Creative/Panasonic host interface adapters do not use inter-
     rupts or DMA although the drives themselves are equipped to allow both to
     be used.

     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.  This prevents a disc change from going undetected by higher
     levels of the operating system.

     There must be a drive on each host interface that is addressed as physi-
     cal drive 0.  (Jumpers on the back of the drive control this setting.)
     If there is no physical drive 0, the mmaattccdd driver will be unable to
     detect that host interface or any of the drives connected to that host
     interface.

     It is not necessary to have four drives attached to the first host inter-
     face before being able to activate a second host interface, but each
     interface must have at least one drive and it must be jumpered to be
     drive 0.

     Drives on a second host interface are considered logical drive numbers 4
     through 7, drives 8 through 11 are on the third interface and 12 through
     15 are on the fourth.  The first drive on the second host interface is
     always logical drive 4 regardless of how many drives are present on the
     first host interface.

     Host interfaces are numbered as specified in the _/_b_o_o_t_/_d_e_v_i_c_e_s_._h_i_n_t_s
     file.

SSEEEE AALLSSOO
     /usr/include/sys/cdio.h, kldload(8), kldunload(8)

AAUUTTHHOORRSS
     The driver and documentation was written by Frank Durda IV.

     Program and Documentation are Copyright 1994, 1995, 2002, 2003 All rights
     reserved.

HHIISSTTOORRYY
     The mmaattccdd driver originally appeared in FreeBSD 2.0.5.

FreeBSD 5.1                      May 10, 2003                      FreeBSD 5.1
