Building a loadable sound driver
================================

Loadable module support in version 3.5 of VoxWare is mostly rewritten since
the previous version (3.0.1). This means that some things have changed.

To compile the sound driver as a loadable module you have to perform
the following steps:

1) Install modules-1.2.8.tar.gz package (or later if available).
2a) Check that symbol remap_page_range is defined in linux/init/ksyms.c.
Insert a line containing "X(remap_page_range)," if required. The driver will
not load if this line is missing.
2b) Recompile kernel with soundcard support disabled.
3) Boot the new kernel.
4) cd to the sound driver source directory (this directory). It's no
longer required that the sound driver sources are installed in the
kernel source tree (linux/drivers/sound). When installing a separately
distributed sound driver you may install the sources for example to
/usr/src/sound.
5) Execute make in the sound driver source directory. Enter
configuration parameters as described in Readme.cards. Then just wait until
the driver is compiled OK.
6) Copy sound.o to the directory where insmod expects to find it. 
("make install" copies it to /lib/modules/misc).
7) Use command "insmod sound" to load the driver.

8) The sound driver can be removed using command "rmmod sound".


Parameters accepted by the loadable sound driver
================================================

Setting DMA buffer size
-----------------------

The driver allocates a DMA buffer (or two for full duplex devices)
every time the audio device (/dev/dsp or /dev/audio) is opened
and frees it when the device is closed. Size of this buffer is defined
when the driver is configured (the last question). The buffer size
can be redefined when loading the driver if required (note that this is 
an optional feature which is not normally required). The buffer size
is redefined by adding dma_pagesize= parameter to the insmod command line.
For example:

	insmod sound dma_buffsize=32768

Minimum buffer size is 4096 and the maximum depends on the DMA channe. 
For 8 bit channels (0 to 3) the limit is 64k and for 16 bit ones (5 to 7)
it's 128k. Driver selects a suitable buffer size automaticly in case
you try to spesify an invalid size.

Q: What is the right DMA buffer size?

A: It depends on the sampling rate, machine speed and the load of the system.
Large buffers are required on slow machines, when recording/playing CD-quality
audio or when there are other processes running on the same system. Also
recording to hard disk is likely to require large buffers.

Very small buffers are sufficient when you are just playing 8kHz audio files 
on an empty P133 system. Using a 128k byffer just wastes 120k (or 250k)
of valuable physical RAM memory. 

The right buffer sice can be easily found by making some experiments
with the dma_buffsize= parameter. I use usually 16k buffers on a DX4/100 system
and 64k on an old 386 system. 

NOTE!	DMA buffers are used only by /dev/audio# and /dev/dsp# devices.
	Other device files don't use them but there are two exceptions:
	GUS driver uses DMA buffers when loading samples to the card.
	Ensoniq SoundScape driver uses them when doanloading the microcode
	file (sndscape.co[012]) to the card. Using large buffers doesn't
	increase performance in these cases.

Configuring device parameters when loading the driver
-----------------------------------------------------

The loadable version of the sound driver accepts now the same
sound= parameter that has been available in the LILO command line.
In this way it's possible to change I/O port, IRQ and DMA addresses
and to enable/disable various cards at load time. Normally
the driver uses the configuration parameters entered when compiling
and configuring the driver.
Look at Readme.linux for more info.

NOTE!	This method is not normally required. You should use it only when
	you have to use different configuration than normally. The sound=
	command line parameter is error phrone and not recommended.

Debugging and tracing
---------------------

Modularized sound driver doesn't display messages during initialization as
the kernel compiled one does. This feature can be turned on by adding
init_trace=1 to the insmod command line.

For example:

	insmod sound init_trace=1