suggested pcm replacement

[Mathew Kanner]

On Nov 08, Tom Rhodes wrote:
> On Fri, 7 Nov 2003 17:18:31 -0500
> Mathew Kanner <mat at cnd.mcgill.ca> wrote:
> 
> > Hello All,
> > 	I'm not subscribed to the -doc list so please CC me.  Anyway,
> > I've been pondering sound latetly and would like to see the man page
> > replaced with something like the attached.
> > 	Please note this is a first draft, I don't know how to write
> > man pages, a paragraph was ripped from the old manual, etc.
> > 
> > 	An emu10k1 manual should be simple in that the emu10k1 driver
> > supports the soundblaster 5.1, soundblaster live, dell EOM
> > soundblaster live. but NOT the audigy, audigy2, or extigy.
> 
> Hi Mat,
> 
> A few weeks ago I told Ruslan (another committer) that I would
> rework the pcm manual page.  I'll incorporate your changes into
> my work.  Thank you for the ideas which you expressed in the previous
> email.

	Tom,
	Please find attached a more verbose version, including
suggestions from Cameron Grant.

	Thanks,
	--Mat

-- 
	If you optimize everything, you will always be unhappy.
			- Don Knuth
-------------- next part --------------
PCM -- FreeBSD PCM audio device infrastructure

	PCM devices provide audio record and playback channels.  The
sound system provides dynamic mixing (VCHAN) and rate conversion (soft
formats).

	In general, the module snd_foo corresponds to the device foo and can be
loaded by the boot loader via /boot/loader.conf or from the command line.

	boot time loading
	snd_driver_load="YES"	#Loads all available drivers
	or,
	snd_emu10k1_load="YES"  #Only loads SoundBlaster 5.1 driver and dependent modules
	or,
	snd_foo_load="YES"	#Load driver for card/chipset foo

	Command line load,
	analogous examples to boot time loading,
	kldload snd_driver,
	kldload snd_emu10k1,
	kldload snd_foo

	Kernel configs
	--------------

	It is possible, though not recommended, to statically compile
the module and drivers a kernel the following in a kernel config.

	device snd_pcm
	device snd_foo

	where foo is the desired soundcard/chipset to be available
statically in the kernel.

VCHANS
	Each device can optionally supported more playback channels
that physical hardware provides by using "virtual channels" (VCHANs).
VCHAN options can be configured via the sysctl interface but can only
be manipulated while the device is inactive.  See the SYSCTLs section
for more information.

Record Channels
	On devices that have more than one recording source (ie, mic
and line) there is a corresponding /dev/dspr%d.%d per source.

CONFIGURATION
	Tunables

	pcm%d.buffersize (Tunable only, set as a hint)  Configure the
amount of (dma) bufferspace available for a device

	SYSCTLs

	PCM sysctls are rooted in hw.snd.  Most sysctls are also tunable.

	hw.snd.targetirqrate:  Set the default block size such that continous
playback will achieve this IRQ rate.  This value can be tuned to improve
application performance.  Increase this value when the sound lags and decrease
it sound stutters or breaks up.

	hw.snd.unit: When using DEVFS, the default device for /dev/dsp.  Equivalent to a symlink from /dev/dsp to /dev/dsp${hw.snd.unit}

	hw.snd.report_soft_formats:  Controls if internal format conversion is
available transparently to the application software.  When disabled (not
available), the application will only be able to select formats the device
natively supports.

	hw.snd.verbose:  Level of verbosity for the /dev/sndstat
device.  Higher values include more output and the highest level (3)
should be used when reported problems.
	0 - Installed devices and their allocated bus resources.
	1 - The number of playback, record and virtual channels and
	flags per device.
	2 - Channel information per device including the channels
	current format and speed and pseudo device statistics such as
	buffer overruns and buffer underruns.
	3 - File names and versions of the currently sound loaded modules.

	hw.snd.maxautovchans:  Global vchan setting that only affects
devices that have only one playback channel.  The sound system will
dynamically create up this many VCHANs.  Set to 0 if no VCHANS are
desired.

	hw.snd.pcm%d.vchans:  The current number of VCHANs allocated
per device.  Can be set to preallocate a certain number of VCHANs.
Setting this value to 0 will disable VCHANs for this device.

IOCTL

     The driver supports most of the OSS ioctls(), and most
applications work unmodified (including popular mpeg players and linux
binaries). A few differences exist, while memory mapped playback is
supported (natively and linux emulation), memory mapped recording is
not due to VM system design.  As a consequence, some applications
may need to be recompiled with a slightly modified audio module.  See
<sys/soundcard.h> for a complete list of the supported ioctls.

HISTORY
	The initial PCM system was written by Luigi Rizzo.  It was
later re-written by Cameron Grant.  The API evolved from the VOXWARE
standard which later became OSS standard.

See Also
	http://www.opensound.com/pguide/oss.pdf, OSS API

FILES
     /dev/audio%d.%d      Sparc-compatible audio device
     /dev/dsp%d.%d        Digitized voice device
     /dev/dspW%d.%d       Like /dev/dsp, but 16 bits per sample
     /dev/dspr%d.%d	  Connected to a record codec
     /dev/sndstat	  Current PCM status, including all channels and drivers.