head	1.8;
access;
symbols
	RELENG_3_5_0_RELEASE:1.7
	RELENG_3_4_0_RELEASE:1.7
	RELENG_3_3_0_RELEASE:1.7
	RELENG_3_2_PAO:1.7.0.4
	RELENG_3_2_PAO_BP:1.7
	RELENG_3_2_0_RELEASE:1.7
	POST_VFS_BIO_NFS_PATCH:1.7
	PRE_VFS_BIO_NFS_PATCH:1.7
	POST_SMP_VMSHARE:1.7
	PRE_SMP_VMSHARE:1.7
	POST_NEWBUS:1.7
	PRE_NEWBUS:1.7
	RELENG_3_1_0_RELEASE:1.7
	RELENG_3:1.7.0.2
	RELENG_3_BP:1.7
	RELENG_2_2_8_RELEASE:1.2.2.3
	RELENG_3_0_0_RELEASE:1.5
	RELENG_2_2_7_RELEASE:1.2.2.2
	PRE_NOBDEV:1.4
	POST_DEVFS_SLICE:1.4
	PRE_DEVFS_SLICE:1.4
	RELENG_2_2_6_RELEASE:1.2.2.1
	POST_SOFTUPDATE:1.4
	PRE_SOFTUPDATE:1.4
	RELENG_2_2:1.2.0.2
	snd970909:1.1.1.1
	LUIGI:1.1.1;
locks; strict;
comment	@# @;


1.8
date	99.09.26.22.20.28;	author peter;	state dead;
branches;
next	1.7;

1.7
date	98.11.02.09.39.54;	author obrien;	state Exp;
branches
	1.7.4.1;
next	1.6;

1.6
date	98.10.22.15.37.35;	author bde;	state Exp;
branches;
next	1.5;

1.5
date	98.10.02.17.26.36;	author luigi;	state Exp;
branches;
next	1.4;

1.4
date	98.02.17.19.17.05;	author nate;	state Exp;
branches;
next	1.3;

1.3
date	98.02.17.14.16.04;	author scrappy;	state Exp;
branches;
next	1.2;

1.2
date	97.10.31.12.24.16;	author jmg;	state Exp;
branches
	1.2.2.1;
next	1.1;

1.1
date	97.09.14.21.42.11;	author jmg;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	97.09.14.21.42.11;	author jmg;	state Exp;
branches;
next	;

1.2.2.1
date	98.02.15.23.29.13;	author jkh;	state Exp;
branches;
next	1.2.2.2;

1.2.2.2
date	98.06.10.17.37.00;	author jkh;	state Exp;
branches;
next	1.2.2.3;

1.2.2.3
date	98.10.22.13.35.22;	author luigi;	state Exp;
branches;
next	;

1.7.4.1
date	99.06.18.19.03.11;	author imp;	state Exp;
branches;
next	;


desc
@@


1.8
log
@Bid a fond farewell to these files, they live on various forms in
dev/pcm/* and dev/pcm/isa/*
@
text
@	    --- 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
old SB16 cards). 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.
Updated versions of this code will be 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---".

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 recognized, 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 (the version in ports is already modified);
  - timidity, a software midi-to-pcm converter;

  NOT WORKING
  - xquake (we do not support mmapped buffers yet);


		    ---INSTALLATION---

  * 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

    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 clones, 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
      device	 pcm2 at isa ? port? tty irq N drq D flags F
      ...

    EXAMPLES: a typical "device" line for the SB16 (full duplex) is

      device pcm0 at isa ? port? tty irq 5 drq 1 flags 0x15

    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

    (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 standard steps

	config MYKERNEL
	cd /sys/compile/MYKERNEL
	make depend
	make

  * note for PnP cards:

    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. You can use the following line:

      device pcm0 at isa ? port? tty irq 7 drq 1

    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 might to help
but I need the following information:

  - 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.

--- ACKNOWLEDGMENTS ---

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 an ES1868 card for writing the
      driver (which i haven't done yet...).
    * and many people who had the patience to try the driver
      on their cards and report success/failure 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 behavior 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.
@


1.7
log
@spell check
@
text
@@


1.7.4.1
log
@Import of PAO on the RELENG_3_2_PAO branch.  This is a branch off of
RELENG_3_2_0_RELEASE and does not have any changes since then
integrated.  This is a raw commit of the last PAO3 file.

Commits to userland code will happen later.  This only the commits
src/sys/...

This branch was approved by the core team at Usenix to allow merging
of PAO code into the mainline FreeBSD code.  The hope is that this
will reduce the divergence between the two.  The other hope is that
this branch will soon be made obsolete by merges into FreeBSD -stable
and -current.  I believe that there will be additional commiters from
the nomads group who will work on merging.

I have not tried to build anything out of this branch yet.  The
patched tree I did here built fine, so if something fails to build it
is my fault.

Submitted by:	The PAO team and nomads.
CVS repo appoved by:	Peter Wemm (peter),
	Jun-ichiro Hagino-san (itojun@@itojun.org), John Polkstra (jdp)
Obtained from:	PAO3-19990605.tar.gz
@
text
@a224 2

$Id: README,v 1.4 1998/12/21 10:03:04 sanpei Exp $
@


1.6
log
@Removed all `vector xxxintr' specifications.  Interrupt handlers are now
configured in drivers.
@
text
@d41 1
a41 1
  Many PnP cards are directly recognised, for others you might need
d86 1
a86 1
    for SB and clonse, 0x530 for WSS and clones), so you don't need
d202 1
a202 1
--- ACKNWOLEDGEMENTS ---
d216 1
a216 1
      on their cards and report success/fauilure and useful
d221 1
a221 1
rare) cases where the data sheets matched the actual behaviour of
@


1.5
log
@Update the pcm driver to the most recent version. This should
add support for Vibra16X, OPTi925, and bring in several assorted
fixes to the code and documentation.
Also present here are apm hooks so that laptops can properly
reconfigure the hardware after suspend (tested on the Libretto50).
Reviewed by: jordan
@
text
@d72 1
a72 1
      device	 pcm0 at isa ? port? tty irq N drq D flags F vector pcmintr
d98 2
a99 2
      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
d104 1
a104 1
      device pcm0 at isa ? port? tty irq 5 drq 1 flags 0x15 vector pcmintr
d116 1
a116 1
      device pcm0 at isa ? port 0x530 tty irq 7 drq 1 flags 0x13 vector pcmintr
d133 1
a133 2
    INCLUDE ALL FIELDS, including "vector pcmintr". You can use
    the following line:
d135 1
a135 1
      device pcm0 at isa ? port? tty irq 7 drq 1 vector pcmintr
@


1.4
log
@- Updated to Luigi's 2-15-98 code.  The code in 2.2 is the same except for
  select/poll and DEVFS changes, which are limited to an include/define
  in sound.h and the actual select/poll implementation in sound.c

[ This commit is blind, but the code is similar enough that there will
  hopefully be no problems. ]
@
text
@d16 1
a16 1
/dev/synth to be supported before summer'98.
d21 4
a24 2
the SB16). To make an effective use of the new functionalities you
need to recompile applications by replacing the audio module(s).
d26 2
a27 1
Updated versions of this code will available at the following URL:
d55 7
d65 2
a66 1
                    ---INSTALLATION---
d122 1
a122 1
  * build the kernel using the following steps
d129 1
a129 1
  * PnP support:
d159 2
a160 2
If the driver does not work with your hardware, I am willing to
help but I need the following:
d214 2
a215 2
    * Eric J. Schwertfeger for donating sn ES1868 card for writing the
      driver.
@


1.3
log
@Upgrade Luigi's audio driver to Jan/23 version... will bring in Feb/15th
version as soon as I've tested it...

Installed/tested on my home machine...any problems, please report directly
to me.
@
text
@a22 15
Such modified driver modules are present in the misc/ directory
for several applications.

This file gives quick information on how to install the driver. 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. I am afraid there is not yet a complete set of
manual pages for using the driver. 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.
a32 14
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. Finally, depending on the
version of their system, 3.0 users might need to uncomment the
following line in snd/sound.h:

	/* #define USE_POLL */

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;

a51 8
  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;

d55 1
a55 38

		    ---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 (Jan.98) have
included the modifications to isa.c .

Installation requires the following steps:

  * 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.
@


1.2
log
@This updates Luigi's sound code to the basic code in snd971023...
changes:
    o rip the old select from his distribution to prevent extra pollution
    o the code now uses audio dma, helps reduce clicks
    o improved card support, should work in full duplex on sb16 cards
    o add better voxware ioctl support pointed out by Joao Carlos Mendes
       Luis <jonny@@coppe.ufrj.br>
    o remove an unused file that I included for more complete history
    o and MANY other changes

I have personally tested this code with a CS4237 based card and an AWE32
(non-PnP).  Both cards worked fine in 8bit and 16bit mode.
@
text
@d4 285
a288 123

This is an experimental version of the audio driver for FreeBSD.
I have almost completely rewritten the main parts of the code,
starting from the Voxware 3.5-alpha release with patches from
Amancio Hasty. The only file which is largely similar to the original
ones is "soundcard.h" (for compatibility reasons, since it contains
the definition of all the ioctls).

Visit http://www.iet.unipi.it/~luigi/FreeBSD.html for the latest
information on the drivers.  There you can obtain the latest source
package that includes documentation on the design of the driver.


CARD SUPPORT INFORMATION:

For PnP cards, I also include the vendor_id and serial numbers of
cards I have encountered.

CS4236: PnP id 0x3642630e
CS4237: PnP id 0x3742630e

    works like a charm. All modes, including full duplex, supported in
    MSS mode.

CS4232: PnP id 0x3242630e

    this chip is reported as broken in the OSS documentation. As a
    matter of fact, on my Intel Zappa motherboard, I have problems in
    make it use the secondary DMA channel. I have it working in
    half duplex (both capture and playback) in SB3.2 emulation,
    and working in playback mode in MSS emulation.

OPTi931: PnP id 0x3109143e

    The data sheets of this chip are very cryptic and do not match
    what the cards I have seem to do. I have it working
    in WSS emulation, in full duplex and all modes.
    In SB emulation mode the driver does not work yet (maybe I do
    not initialize it the right way). It is not a major concern
    anyways.
    I am strongly convinced of a couple of bugs in the chip. I have
    sent email to OPTI but got no reply so far. The bugs are:
    - you cannot set both playback and capture format to use
      a companded mode (ULAW, ALAW). If you do, the card will screw
      up on the capture section.
      The driver has a partial fix in software: when using ULAW, it
      programs ULAW on the playback section, U8 on the capture, and
      does a conversion in software (much like the SBPro). Of course
      you lose 4-5 bits of dynamic range in the process.
    - in full duplex (and single DMA mode), the card occasionally
      misses interrupts, or generates spurious ones. Spurious ints are
      not problematic since they can be ignored, but missed ones are
      as you can imagine... This is fixed by auto-dma mode.

SB16 PnP: PnP id 0xXX008c0e

    There are many such cards (plain SB16 PnP, AWE32, AWE64, Vibra16,
    etc.) all differing in the PnP id. They have different synthesis
    devices, which we do not support, so we are not affected by these
    differences. Don't worry if the driver identifies the card as a
    different SB16 than the one you have.

    Full duplex support of this card is tricky since one channel can
    work in 16-bit and the other in 8-bit mode. You will need to use
    the new set of ioctl to use separate data formats on the two
    channels (the vat driver does this). Of course, quality in 8-bit
    is much lower than in 16-bit.

    Full duplex operation is unsupported by Creative. It seems to
    work, although on my Vibra16 the command to stop DMA transfer
    seems to erroneously affect both channels instead of the one
    they are issued for. The driver has a workaround, but I cannot
    guarantee that it works for everybody. I have had several
    positive reports.

Yamaha SA2

    this card emulates a WSS or SB. Have reports that it works, although
    it has mixer problems (maybe the driver has the wrong set of
    parameters).

Ensoniq Soundscape VIVO

    this card emulates a WSS or SB. Have reports that it works.

GusPnP: PnP id 0x0100561e

    I have code to recognize the board as MSS, but some initializations
    of the IW chip is still missing, so the card is not supported yet.
    I am working on this problem...

OPTI924: PnP

    I have this card but it is still unsupported.

OPTI925: PnP id 0x2509143e

    there is code to recognize it as a SB clone. I have reports that
    it probes ok, but not sure if it works.

OPTI930:

    should work as an MSS clone, but support for it is not implemented
    yet.

ESS1868

    this card is not supported yet. It might work in SB emulation but
    am not sure.

ESS688

    this card is used on many notebook. I don't have docs on this card
    so I cannot support it. Pointers to the data sheets are welcome.

PCI cards:

    some vendors have PCI cards. This code _cannot_ work on these
    cards as it is now, since they cannot obviously use the ISA DMA
    controller. As there are no data sheets available for these PCI
    cards, none of them is supported at the moment, although support
    should be easy as soon as I can put my hands on the data sheets
    and cards.
@


1.2.2.1
log
@Update to luigi's latest.

Compiles OK for me under 2.2 (of course, so did the previous version).
@
text
@d4 123
a126 211
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 before summer'98.

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).

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---".

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, ...);

  NOT WORKING
  - xquake (we do not support mmapped buffers yet);

                    ---INSTALLATION---

  * 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.
@


1.2.2.2
log
@Update to Luigi's latest sound driver for -stable (snd980419).
@
text
@a22 15
Such modified driver modules are present in the misc/ directory
for several applications.

This file gives quick information on how to install the driver. 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. I am afraid there is not yet a complete set of
manual pages for using the driver. 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.
a32 15
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;

a51 8
  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;

d55 1
a55 38

		    ---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 (Jan.98) have
included the modifications to isa.c .

Installation requires the following steps:

  * 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.
@


1.2.2.3
log
@Update the -stable driver to what is in -current. Mostly
bugfixes, improved SB16 support, apm hooks. No ESS support
yet, some PnP device IDs still missing.
@
text
@d16 1
a16 1
/dev/synth to be supported anytime soon.
d26 6
a31 7
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
d100 1
a100 1
-stable and -current at the time of this writing (Jun.98) have
a104 5
2.2.6 USERS:
  * replace the files in /sys/i386/isa/snd with the files in this
    directory.

2.2.5 AND EARLIER VERSIONS:
a131 1
ALL VERSIONS:
@


1.1
log
@Initial revision
@
text
@d1 2
a2 2
            --- A new  FreeBSD sound driver ---
            by Luigi Rizzo (luigi@@iet.unipi.it)
d5 1
a5 1
This is an experimental version of the sound driver for FreeBSD.
d23 1
a27 5
CS4237: PnP id 0x3742630e

    I had early reports of success with this board, which is almost
    the same as the CS4236.

d38 19
a56 12
    The data sheets of this chip are very cryptic. I have it working
    in full duplex in all modes _except_ capture of uLAW/ALAW data.
    I am strongly convinced of a bug in the chip. I have sent email
    to OPTI but got no reply so far.  In SB emulation mode the
    driver does not work yet (maybe I do not initialize it the
    right way).

    Another bug seems to affect full duplex operation -- it appears
    that at times DMA transfer are requested but not counted by
    the device. In normal DMA mode this causes deadlocks.  The only
    solution I have found is to fetch the count from the ISA DMA
    registers, but this does not seem to work very well either.
d61 25
a85 2
    etc. all differing in the PnP id (and with different synthesis
    devices, which we do not support anyways).
d87 1
a87 2
    Since 970903 the driver supports them all, both capture and
    playback, 8 and 16 bits.
d91 7
a97 2
    I have code to recognize the board as MSS, but have not tested it
    since I don't own the board. Hopefully someone will test it soon.
d109 18
@


1.1.1.1
log
@Import of Luigi Rizzo's sound code.  For more information about the driver
check out the README that is included.

Submitted by:	Luigi Rizzo <luigi@@labinfo.iet.unipi.it>
@
text
@@
