FreeBSD/Linux Kernel Cross Reference
sys/i386/isa/snd/

	Name	Size	Last modified (GMT)	Description
	Parent directory		2008-10-04 07:13:55
	CARDS	10485 bytes	1998-10-22 13:35:22
	README	11992 bytes	1998-10-22 13:35:22
	ad1848.c	48457 bytes	1998-11-14 13:09:09
	clones.c	7251 bytes	1997-11-23 07:03:11
	dmabuf.c	24035 bytes	1998-10-22 13:35:22
	mss.h	8480 bytes	1998-06-10 17:37:01
	sb_dsp.c	35926 bytes	1998-12-14 17:18:05
	sbcard.h	12706 bytes	1998-12-14 17:18:05
	sound.c	40640 bytes	1998-11-29 22:52:16
	sound.h	15247 bytes	1998-06-10 17:37:02

                 --- A new  FreeBSD audio driver ---
                 by Luigi Rizzo (luigi@iet.unipi.it)
     
     This is a new, completely rewritten, audio driver for FreeBSD.
     Only "soundcard.h" has remained largely similar to the original
     OSS/Voxware header file, mostly for compatibility with existing
     applications.
     
     This driver tries to cover those areas where the Voxware 3.0 driver
    is mostly lacking: full-duplex, audio applications, modern (mostly
    PnP) cards. For backward compatibility, the driver implements most
    of the Voxware ioctl() audio calls, so that many applications --
    even commercial ones -- will run unmodified with this driver.  On
    the other hand, at the moment this driver does not support /dev/midi
    and /dev/synth, or some ioctl() used in xquake. Do not expect
    /dev/synth to be supported anytime soon.
    
    I also have implemented a new software interface with an independent
    set of ioctl(), to support some functions which were not easy to
    express with the existing software interface (e.g. full duplex on
    the SB16). To make an effective use of the new functionalities you
    need to recompile applications by replacing the audio module(s).
    Such modified driver modules are present in the misc/ directory
    for several applications.
    
    This file gives quick information on how to install the driver.
    Most of these information are also in the manpage included here,
    which will become the 'official' reference in case of discrepancies.
    For more info you are invited to look at the doc/ directory where
    you can find more documentation (in Latex and Postscript) on the
    driver and how to extend it. The files in doc/ should give a good
    idea of what the driver is supposed to do and how, the Voxware
    documentation should be of some help, and the various driver modules
    in misc/ should also give some help.
    
    Also note that you might need the PnP code (pnp971020.tgz), which
    as of January 1998 has been incorporated in -current and -stable
    versions of FreeBSD.
    
    Updated versions of this code will available at the following URL:
    
            http://www.iet.unipi.it/~luigi/FreeBSD.html
    
    Please READ CAREFULLY this file (and possibly the LaTeX documentation)
    to build a working kernel. The configuration is DIFFERENT (and
    hopefully much simpler) from the original Voxware driver.  The
    relevant steps are indicated at "---INSTALLATION---".
    
    This code (and the associated patches) should work unmodified on
    2.2.5 and in general on 2.2.X versions of FreeBSD. Minor modifications
    will be necessary to make the code work on 2.1.X. The code assumes
    that, if you are using FreeBSD 3.0, your system uses poll(2) instead
    of select(2) -- this change happened around late 1997. The code which
    deals with this is mostly in sound.c, and conditioned by 
    
            #if __FreeBSD__ >= 3
    
    This archive includes:
    * the main files for the driver, in this directory, which must be
      moved to /sys/i386/isa/snd;
    * miscellaneous, but important, files in the "misc" subdirectory;
    * documentation, in the "doc" subdirectory;
    
    CARDS:
    
      The driver supports most clones of WSS, SB16 and SBPro cards.
      This includes those based on the Crystal CS423x, OPTI931, GUSPnP,
      Yamaha, SB16/32 (both plain ISA, PnP, and the various AWExx).
      Many PnP cards are directly recognised, for others you might need
      manual configuration. See the file "CARDS" for more details.
    
    APPLICATIONS:
    
      In general, most applications which use /dev/audio or /dev/dsp
      work unmodified or with a specially-supplied module.
    
      UNMODIFIED:
      - raplayer (Real Audio Player), rvplayer (linux version)
      - xboing
      - xanim
      - various mpeg players (mpg123, amp, ...);
    
      WITH SPECIAL DRIVER MODULE (supplied)
      - speak_freely, full duplex (requires removing the definition of
        HALF_DUPLEX in the Makefile);
      - the realaudio player (3.0, dynamically linked);
      - vat, full duplex (driver included);
      - nas, full duplex (driver included);
      - timidity, a software midi-to-pcm converter;
    
      NOT WORKING
      - xquake (we do not support mmapped buffers yet);
    
    
                        ---INSTALLATION---
    
    In order to use this driver, you need FreeBSD 2.2 or above (I have
    tested this code on 2.2.1 and 2.2.5, and have many reports of the
    driver working on various vintages of 3.0 ). The enclosed patch
   file refers to FreeBSD 2.2.5. Your mileage may vary -- e.g. both
   -stable and -current at the time of this writing (Jun.98) have
   included the modifications to isa.c .
   
   Installation requires the following steps:
   
   2.2.6 USERS:
     * replace the files in /sys/i386/isa/snd with the files in this
       directory.
   
   2.2.5 AND EARLIER VERSIONS:
     * install the PnP support files (pnp971020.tgz). This is optional,
       in case you don't you might need to do some simple modifications
       to the file because pnp.h might not exist.
   
     * unpack the content of this archive in /sys/i386/isa/snd/
   
     * if you are running a version of 2.2 earlies than 2.2.5-RELEASE,
       apply the patches in "patches.22x" to isa.c
   
     * patch the following system files using the patches in
       "patches.225" :
   
           /sys/i386/isa/isa.c
                   a couple of new functions have been added;
   
           /sys/i386/conf/files.i386
                   lines related to this audio driver have been added;
   
     * update file soundcard.h by copying the one in this directory into:
   
             /sys/i386/include/soundcard.h
             /usr/include/machine/soundcard.h
   
       The new file should be compatible with the old one, but has
       the definition of new ioctl() calls which are implemented by
       this driver.
   
   ALL VERSIONS:
     * add the following lines to your kernel configuration file:
   
         controller pnp0  # this is required for PnP support
   
         device     pcm0 at isa ? port? tty irq N drq D flags F vector pcmintr
   
       where
   
         N is the IRQ address used by the sound card,
         D is the primary DMA channel used by the sound card,
         F is used to specify a number of options, in particular:
           bit  2..0   secondary DMA channel;
           bit  4      set if the board uses two dma channels;
           bit 15..8   board type, overrides autodetection; leave it
                       zero if don't know what to put in (and you don't,
                       since this is unsupported at the moment...).
   
       The code will probe for common port addresses (0x220, 0x240
       for SB and clonse, 0x530 for WSS and clones), so you don't need
       to specify them if your system uses one of them. In case you
       do, note that for WSS cards the code assumes that the board
       occupies 8 IO addresses, the first four used to configure
       IRQ/DRQ, and the other four to access codec registers. Many
       boards (including all the ones I have) do not have registers
       to program IRQ and DRQ, so they really start at 0x534... yet
       I decided to use the old convention for historical reasons.
   
       You can use multiple sound cards, in which case you need more
       lines like
   
         device     pcm1 at isa ? port? tty irq N drq D flags F vector pcmintr
         device     pcm2 at isa ? port? tty irq N drq D flags F vector pcmintr
         ...
   
       EXAMPLES: a typical "device" line for the SB16 (full duplex) is
   
         device pcm0 at isa ? port? tty irq 5 drq 1 flags 0x15 vector pcmintr
   
       The driver will check at the default addresses (or the one you
       specify) which type of SoundBlaster you have (1.5, 2.0, 3.X
       aka SBPro, 4.X aka SB16) and use the correct commands. You
       _do_not_ need to specify different drivers (sb,sbpro,sbxvi) as
       it was the case (and a big source of confusion) in the previous
       sound driver.
   
       For a WSS-compatible codec (non PnP) working in full duplex using
       dma channels 1 and 3, you can specify:
   
         device pcm0 at isa ? port 0x530 tty irq 7 drq 1 flags 0x13 vector pcmintr
   
       (0x530 is a default if no port address is specified).  The
       "flags 0x13" specifies that you have a dual dma board with
       channel 3 as secondary DMA channel.
   
     * build the kernel using the following steps
   
           config MYKERNEL
           cd /sys/compile/MYKERNEL
           make depend
           make
   
     * PnP support:
   
       For PnP cards, only the line for "pcm0" is needed (the code
       will allocate entries for more cards if found), but IT MUST
       INCLUDE ALL FIELDS, including "vector pcmintr". You can use
       the following line:
   
         device pcm0 at isa ? port? tty irq 7 drq 1 vector pcmintr
   
       NOTE that:
         - the parameters for the PnP device(s) will be read from the
           configuration of the card(s); they are usually assigned by
           the bios, and there is no way (at the moment) to override
           them, so if you have a broken (or no) PnP bios your only
           chance is to patch the pnp attach code in the driver for your
           card (ad1848.c, sb_dsp.c, clones.c) and write there the
           parameters you want;
         - The driver will assign unit numbers to the PnP cards starting
           from the next free one (e.g. 1, 2, ...) same as it is done
           with PCI devices which are clones of ISA devices.
   
       The driver assumes a working PnP bios, which will assign correct
       addresses and IO and DMA channels to the devices. If you do not
       have a PnP-aware BIOS, you must boot with the -c option and assign
       addresses manually the first time. The general commands are described in
       the pnp README file. For the card-specific commands check in the
       file CARDS.
   
   WHAT IF THIS DRIVER DOES NOT WORK:
   
   If the driver does not work with your hardware, I am willing to
   help but I need the following:
   
     - relevant lines in your config file;
     - dmesg output
     - possibly, pnpinfo output
   
   Please send all the above in plain text, not as a mime attachment.
   
   Common mistakes:
   
   * you are trying to use /dev/audio0 instead of /dev/audio1
     For technical reasons, a PnP device is attached as unit 1 instead
     of unit 0 -- most applications are programmed to access the audio
     hardware through /dev/audio, /dev/dsp, /dev/mixer which are in turn
     symlinks to the correct device entries. Check them and possibly fix
     these symlinks in /dev
   
   * you have used a wrong config line
   
     The configuration of this driver is different from the Voxware one.
     Please read the information in this file carefully.
   
   * your BIOS is leaving the card disabled.
   
     Some BIOSes do not initialize the card, or leave it disabled. At the
     moment, the fix is to use the pnp code booting with "-c" and set the
     correct port, irq, drq etc for the card. See the PnP documentation.
   
   * your card is not recognized.
   
     This driver supports a large, but still limited, number of cards,
     mostly SB and WSS clones. Other cards may or may not work depending
     on how closely they emulate these devices. In case, send me an email
     with the info indicated above.
   
   * the mixer does not work well
   
     Different cards have different connections to the mixer, so it might
     well be that to control the volume of your CD you have to use the FM
     port, etc. Also, on some cards the volume might be lower than you
     expect. The mixer code still does not try to exploit the features of
     each card, and it just provides basic functionalities.
   
   --- ACKNWOLEDGEMENTS ---
   
   Several people helped, directly or indirectly, in the development of
   this driver. In particular I would like to thank:
   
       * Hannu Savolainen (the Voxware author) for making his code
         available. It was a very good source of technical info;
       * Amancio Hasty for continuous support and his work on guspnp code;
       * Jim Lowe for his suggestion on the block-mode select;
       * Allison Mankin and Brad Karp at ISI-East for supplying a GUS PnP
         which allowed me to support this card;
       * Eric J. Schwertfeger for donating sn ES1868 card for writing the
         driver.
       * and many people who had the patience to try the driver
         on their cards and report success/fauilure and useful
         information.
   
   It was certainly helpful to have the data sheets for some of the
   devices I support available on the net, especially in the (unfortunately
   rare) cases where the data sheets matched the actual behaviour of
   the product. Too bad that no one of the chip/card manufacturers I
   have contacted by email regarding missing or inconsistent documentation
   on their products did even care to reply to my messages.