 @@ -1,718 +1,716 @@
-.\"	$NetBSD: audio.4,v 1.68 2008/04/30 13:10:53 martin Exp $
+.\"	$NetBSD: audio.4,v 1.69 2009/01/03 17:44:20 christos Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
 .\" by John T. Kohl.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 11, 2007
+.Dd January 3, 2009
 .Dt AUDIO 4
 .Os
 .Sh NAME
 .Nm audio
 .Nd device-independent audio driver layer
 .Sh SYNOPSIS
 .In sys/audioio.h
 .Sh DESCRIPTION
 The
 .Nm
 driver provides support for various audio peripherals.
 It provides a uniform programming interface layer above different
 underlying audio hardware drivers.
 The audio layer provides full-duplex operation if the
 underlying hardware configuration supports it.
 .Pp
 There are four device files available for audio operation:
 .Pa /dev/audio ,
 .Pa /dev/sound ,
 .Pa /dev/audioctl ,
 and
 .Pa /dev/mixer .
 .Pp
 .Pa /dev/audio
 and
 .Pa /dev/sound
 are used for recording or playback of digital samples.
 .Pp
 .Pa /dev/mixer
 is used to manipulate volume, recording source, or other audio mixer
 functions.
 .Pp
 .Pa /dev/audioctl
 accepts the same
 .Xr ioctl 2
 operations as
 .Pa /dev/sound ,
 but no other operations.
 .Pp
 In contrast to
 .Pa /dev/sound
 which has the exclusive open property
 .Pa /dev/audioctl
 can be opened at any time and can be used to manipulate the audio device
 while it is in use.
 .Sh SAMPLING DEVICES
 When
 .Pa /dev/audio
 is opened, it automatically directs the underlying driver to manipulate
 monaural 8-bit mu-law samples.
 In addition, if it is opened read-only
 (write-only) the device is set to half-duplex record (play) mode with
 recording (playing) unpaused and playing (recording) paused.
 When
 .Pa /dev/sound
 is opened, it maintains the previous audio sample mode and
 record/playback mode.
 In all other respects
 .Pa /dev/audio
 and
 .Pa /dev/sound
 are identical.
 .Pp
 Only one process may hold open a sampling device at a given time
 (although file descriptors may be shared between processes once the
 first open completes).
 .Pp
 On a half-duplex device, writes while recording is in progress will be
 immediately discarded.
 Similarly, reads while playback is in progress
 will be filled with silence but delayed to return at the current
 sampling rate.
 If both playback and recording are requested on a half-duplex
 device, playback mode takes precedence and recordings will get silence.
 .Pp
 On a full-duplex device, reads and writes may operate
 concurrently without interference.
 If a full-duplex capable audio device is opened for both reading and writing
 it will start in half-duplex play mode; full-duplex mode has to be set
 explicitly.
 .Pp
 On either type of device, if the playback mode is paused then silence is
 played instead of the provided samples, and if recording is paused then
 the process blocks in
 .Xr read 2
 until recording is unpaused.
 .Pp
 If a writing process does not call
 .Xr write 2
 frequently enough to provide samples at the pace the hardware
 consumes them silence is inserted.
 If the
 .Dv AUMODE_PLAY_ALL
 mode is not set the writing process must
 provide enough data via
 subsequent write calls to
 .Dq catch up
 in time to the current audio
 block before any more process-provided samples will be played.
 If a reading process does not call
 .Xr read 2
 frequently enough, it will simply miss samples.
 .Pp
 The audio device is normally accessed with
 .Xr read 2
 or
 .Xr write 2
 calls, but it can also be mapped into user memory with
 .Xr mmap 2
 (when supported by the device).
 Once the device has been mapped it can no longer be accessed
 by read or write; all access is by reading and writing to
 the mapped memory.
 The device appears as a block of memory
 of size
 .Va buffersize
 (as available via
 .Dv AUDIO_GETINFO
 or
 .Dv AUDIO_GETBUFINFO ) .
 The device driver will continuously move data from this buffer
 from/to the audio hardware, wrapping around at the end of the buffer.
 To find out where the hardware is currently accessing data in the buffer the
 .Dv AUDIO_GETIOFFS
 and
 .Dv AUDIO_GETOOFFS
 calls can be used.
 The playing and recording buffers are distinct and must be
 mapped separately if both are to be used.
 Only encodings that are not emulated (i.e. where
 .Dv AUDIO_ENCODINGFLAG_EMULATED
 is not set) work properly for a mapped device.
 .Pp
 The audio device, like most devices, can be used in
 .Va select ,
 can be set in non-blocking mode and can be set (with a
 .Dv FIOASYNC
 ioctl) to send a
 .Dv SIGIO
 when I/O is possible.
 The mixer device can be set to generate a
 .Dv SIGIO
 whenever a mixer value is changed.
 .Pp
 The following
 .Xr ioctl 2
 commands are supported on the sample devices:
 .Pp
 .Bl -tag -width indent
 .It Dv AUDIO_FLUSH
 This command stops all playback and recording, clears all queued
 buffers, resets error counters, and restarts recording and playback as
 appropriate for the current sampling mode.
 .It Dv AUDIO_RERROR (int)
 This command fetches the count of dropped input samples into its integer
 argument.
 There is no information regarding when in the sample stream
 they were dropped.
 .It Dv AUDIO_WSEEK (int)
 This command fetches the count of samples that are queued ahead of the
 first sample in the most recent sample block written into its integer argument.
 .It Dv AUDIO_DRAIN
 This command suspends the calling process until all queued playback
 samples have been played by the hardware.
 .It Dv AUDIO_GETDEV (audio_device_t)
 This command fetches the current hardware device information into the
 audio_device_t argument.
 .Bd -literal
 typedef struct audio_device {
         char name[MAX_AUDIO_DEV_LEN];
         char version[MAX_AUDIO_DEV_LEN];
         char config[MAX_AUDIO_DEV_LEN];
 } audio_device_t;
 .Ed
 .It Dv AUDIO_GETFD (int)
 The command returns the current setting of the full duplex mode.
 .It Dv AUDIO_GETENC (audio_encoding_t)
 This command is used iteratively to fetch sample encoding names and
 format_ids into the input/output audio_encoding_t argument.
 .Bd -literal
 typedef struct audio_encoding {
 	int index;      /* input: nth encoding */
 	char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */
 	int encoding;   /* value for encoding parameter */
 	int precision;  /* value for precision parameter */
 	int flags;
 #define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */
 } audio_encoding_t;
 .Ed
 .Pp
 To query
 all the supported encodings, start with an index field of 0 and
 continue with successive encodings (1, 2, ...) until the command returns
 an error.
 .It Dv AUDIO_SETFD (int)
 This command sets the device into full-duplex operation if its integer
 argument has a non-zero value, or into half-duplex operation if it
 contains a zero value.
 If the device does not support full-duplex
 operation, attempting to set full-duplex mode returns an error.
 .It Dv AUDIO_GETPROPS (int)
 This command gets a bit set of hardware properties.
 If the hardware
 has a certain property the corresponding bit is set, otherwise it is not.
 The properties can have the following values:
 .Pp
 .Bl -tag -width AUDIO_PROP_INDEPENDENT -compact
 .It Dv AUDIO_PROP_FULLDUPLEX
 the device admits full duplex operation.
 .It Dv AUDIO_PROP_MMAP
 the device can be used with
 .Xr mmap 2 .
 .It Dv AUDIO_PROP_INDEPENDENT
 the device can set the playing and recording encoding parameters
 independently.
 .El
 .It Dv AUDIO_GETIOFFS (audio_offset_t)
 .It Dv AUDIO_GETOOFFS (audio_offset_t)
 This command fetches the current offset in the input(output) buffer where
 the audio hardware's DMA engine will be putting(getting) data.
 It mostly useful when the device
 buffer is available in user space via the
 .Xr mmap 2
 call.
 The information is returned in the audio_offset structure.
 .Bd -literal
 typedef struct audio_offset {
 	u_int	samples;   /* Total number of bytes transferred */
 	u_int	deltablks; /* Blocks transferred since last checked */
 	u_int	offset;    /* Physical transfer offset in buffer */
 } audio_offset_t;
 .Ed
 .It Dv AUDIO_GETINFO (audio_info_t)
 .It Dv AUDIO_GETBUFINFO (audio_info_t)
 .It Dv AUDIO_SETINFO (audio_info_t)
 Get or set audio information as encoded in the audio_info structure.
 .Bd -literal
 typedef struct audio_info {
 	struct	audio_prinfo play;   /* info for play (output) side */
 	struct	audio_prinfo record; /* info for record (input) side */
         u_int	monitor_gain;			/* input to output mix */
 	/* BSD extensions */
 	u_int	blocksize;	/* H/W read/write block size */
 	u_int	hiwat;		/* output high water mark */
 	u_int	lowat;		/* output low water mark */
 	u_int	_ispare1;
 	u_int	mode;		/* current device mode */
 #define AUMODE_PLAY	0x01
 #define AUMODE_RECORD	0x02
 #define AUMODE_PLAY_ALL 0x04	/* do not do real-time correction */
 } audio_info_t;
 .Ed
 .Pp
 When setting the current state with
 .Dv AUDIO_SETINFO ,
 the audio_info structure should first be initialized with
 .Dv AUDIO_INITINFO Po \*[Am]info Pc
 and then the particular values to be changed should be set.
 This allows the audio driver to only set those things that you wish
 to change and eliminates the need to query the device with
 .Dv AUDIO_GETINFO
 or
 .Dv AUDIO_GETBUFINFO
 first.
 .Pp
 The
 .Va mode
 field should be set to
 .Dv AUMODE_PLAY ,
 .Dv AUMODE_RECORD ,
 .Dv AUMODE_PLAY_ALL ,
 or a bitwise OR combination of the three.
 Only full-duplex audio devices support
 simultaneous record and playback.
 .Pp
 .Va hiwat
 and
 .Va lowat
 are used to control write behavior.
 Writes to the audio devices will queue up blocks until the high-water
 mark is reached, at which point any more write calls will block
 until the queue is drained to the low-water mark.
 .Va hiwat
 and
 .Va lowat
 set those high- and low-water marks (in audio blocks).
 The default for
 .Va hiwat
 is the maximum value and for
 .Va lowat
 % of
 .Va hiwat .
 .Pp
 .Va blocksize
 sets the current audio blocksize.
 The generic audio driver layer and the hardware driver have the
 opportunity to adjust this block size to get it within
 implementation-required limits.
 Upon return from an
 .Dv AUDIO_SETINFO
 call, the actual blocksize set is returned in this field.
 Normally the
 .Va blocksize
 is calculated to correspond to 50ms of sound and it is recalculated
 when the encoding parameter changes, but if the
 .Va blocksize
 is set explicitly this value becomes sticky, i.e., it remains
 even when the encoding is changed.
 The stickiness can be cleared by reopening the device or setting the
 .Va blocksize
 to 0.
 .Bd -literal
 struct audio_prinfo {
 	u_int	sample_rate;	/* sample rate in samples/s */
 	u_int	channels;	/* number of channels, usually 1 or 2 */
 	u_int	precision;	/* number of bits/sample */
 	u_int	encoding;	/* data encoding (AUDIO_ENCODING_* below) */
 	u_int	gain;		/* volume level */
 	u_int	port;		/* selected I/O port */
 	u_long	seek;		/* BSD extension */
 	u_int	avail_ports;	/* available I/O ports */
 	u_int	buffer_size;	/* total size audio buffer */
 	u_int	_ispare[1];
 	/* Current state of device: */
 	u_int	samples;	/* number of samples */
 	u_int	eof;		/* End Of File (zero-size writes) counter */
 	u_char	pause;		/* non-zero if paused, zero to resume */
 	u_char	error;		/* non-zero if underflow/overflow occurred */
 	u_char	waiting;	/* non-zero if another process hangs in open */
 	u_char	balance;	/* stereo channel balance */
 	u_char	cspare[2];
 	u_char	open;		/* non-zero if currently open */
 	u_char	active;		/* non-zero if I/O is currently active */
 };
 .Ed
 .Pp
 Note:  many hardware audio drivers require identical playback and
 recording sample rates, sample encodings, and channel counts.
 The playing information is always set last and will prevail on such hardware.
 If the hardware can handle different settings the
 .Dv AUDIO_PROP_INDEPENDENT
 property is set.
 .Pp
 The encoding parameter can have the following values:
 .Pp
 .Bl -tag -width AUDIO_ENCODING_SLINEAR_BE -compact
 .It Dv AUDIO_ENCODING_ULAW
 mu-law encoding, 8 bits/sample
 .It Dv AUDIO_ENCODING_ALAW
 A-law encoding, 8 bits/sample
 .It Dv AUDIO_ENCODING_SLINEAR
 two's complement signed linear encoding with the platform byte order
 .It Dv AUDIO_ENCODING_ULINEAR
 unsigned linear encoding with the platform byte order
 .It Dv AUDIO_ENCODING_ADPCM
 ADPCM encoding, 8 bits/sample
 .It Dv AUDIO_ENCODING_SLINEAR_LE
 two's complement signed linear encoding with little endian byte order
 .It Dv AUDIO_ENCODING_SLINEAR_BE
 two's complement signed linear encoding with big endian byte order
 .It Dv AUDIO_ENCODING_ULINEAR_LE
 unsigned linear encoding with little endian byte order
 .It Dv AUDIO_ENCODING_ULINEAR_BE
 unsigned linear encoding with big endian byte order
 .El
 .Pp
 The
 .Va gain ,
 .Va port
 and
 .Va balance
 settings provide simple shortcuts to the richer mixer
 interface described below and are not obtained by
 .Dv AUDIO_GETBUFINFO .
 The gain should be in the range
 .Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN
 and the balance in the range
 .Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE
 with the normal setting at
 .Dv AUDIO_MID_BALANCE .
 .Pp
 The input port should be a combination of:
 .Pp
 .Bl -tag -width AUDIO_MICROPHONE -compact
 .It Dv AUDIO_MICROPHONE
 to select microphone input.
 .It Dv AUDIO_LINE_IN
 to select line input.
 .It Dv AUDIO_CD
 to select CD input.
 .El
 .Pp
 The output port should be a combination of:
 .Pp
 .Bl -tag -width AUDIO_HEADPHONE -compact
 .It Dv AUDIO_SPEAKER
 to select speaker output.
 .It Dv AUDIO_HEADPHONE
 to select headphone output.
 .It Dv AUDIO_LINE_OUT
 to select line output.
 .El
 .Pp
 The available ports can be found in
 .Va avail_ports
 .Dv ( AUDIO_GETBUFINFO
 only).
 .Pp
 .Va buffer_size
 is the total size of the audio buffer.
 The buffer size divided by the
 .Va blocksize
 gives the maximum value for
 .Va hiwat .
 Currently the
 .Va buffer_size
 can only be read and not set.
 .Pp
 The
 .Va seek
 and
 .Va samples
 fields are only used by
 .Dv AUDIO_GETINFO
 and
 .Dv AUDIO_GETBUFINFO .
 .Va seek
 represents the count of
 samples pending;
 .Va samples
 represents the total number of bytes recorded or played, less those
 that were dropped due to inadequate consumption/production rates.
 .Pp
 .Va pause
 returns the current pause/unpause state for recording or playback.
 For
 .Dv AUDIO_SETINFO ,
 if the pause value is specified it will either pause
 or unpause the particular direction.
 .El
 .Sh MIXER DEVICE
 The mixer device,
 .Pa /dev/mixer ,
 may be manipulated with
 .Xr ioctl 2
 but does not support
 .Xr read 2
 or
 .Xr write 2 .
 It supports the following
 .Xr ioctl 2
 commands:
 .Bl -tag -width indent
 .It Dv AUDIO_GETDEV (audio_device_t)
 This command is the same as described above for the sampling devices.
 .It Dv AUDIO_MIXER_READ (mixer_ctrl_t)
 .It Dv AUDIO_MIXER_WRITE (mixer_ctrl_t)
 These commands read the current mixer state or set new mixer state for
 the specified device
 .Va dev .
 .Va type
 identifies which type of value is supplied in the
 .Va mixer_ctrl_t
 argument.
 .Bd -literal
 #define AUDIO_MIXER_CLASS  0
 #define AUDIO_MIXER_ENUM   1
 #define AUDIO_MIXER_SET    2
 #define AUDIO_MIXER_VALUE  3
 typedef struct mixer_ctrl {
 	int dev;			/* input: nth device */
 	int type;
 	union {
 		int ord;		/* enum */
 		int mask;		/* set */
 		mixer_level_t value;	/* value */
 	} un;
 } mixer_ctrl_t;
 #define AUDIO_MIN_GAIN  0
 #define AUDIO_MAX_GAIN  255
 typedef struct mixer_level {
         int num_channels;
         u_char level[8];               /* [num_channels] */
 } mixer_level_t;
 #define AUDIO_MIXER_LEVEL_MONO  0
 #define AUDIO_MIXER_LEVEL_LEFT  0
 #define AUDIO_MIXER_LEVEL_RIGHT 1
 .Ed
 .Pp
 For a mixer value, the
 .Va value
 field specifies both the number of channels and the values for each
 channel.
 If the channel count does not match the current channel count, the
 attempt to change the setting may fail (depending on the hardware
 device driver implementation).
 For an enumeration value, the
 .Va ord
 field should be set to one of the possible values as returned by a prior
 .Dv AUDIO_MIXER_DEVINFO
 command.
 The type
 .Dv AUDIO_MIXER_CLASS
 is only used for classifying particular mixer device
 types and is not used for
 .Dv AUDIO_MIXER_READ
 or
 .Dv AUDIO_MIXER_WRITE .
 .It Dv AUDIO_MIXER_DEVINFO (mixer_devinfo_t)
 This command is used iteratively to fetch audio mixer device information
 into the input/output mixer_devinfo_t argument.
 To query all the supported devices, start with an index field of
 and continue with successive devices (1, 2, ...) until the
 command returns an error.
 .Bd -literal
 typedef struct mixer_devinfo {
 	int index;		/* input: nth mixer device */
 	audio_mixer_name_t label;
 	int type;
 	int mixer_class;
 	int next, prev;
 #define AUDIO_MIXER_LAST	-1
 	union {
 		struct audio_mixer_enum {
 			int num_mem;
 			struct {
 				audio_mixer_name_t label;
 				int ord;
 			} member[32];
 		} e;
 		struct audio_mixer_set {
 			int num_mem;
 			struct {
 				audio_mixer_name_t label;
 				int mask;
 			} member[32];
 		} s;
 		struct audio_mixer_value {
 			audio_mixer_name_t units;
 			int num_channels;
 			int delta;
 		} v;
 	} un;
 } mixer_devinfo_t;
 .Ed
 .Pp
 The
 .Va label
 field identifies the name of this particular mixer control.
 The
 .Va index
 field may be used as the
 .Va dev
 field in
 .Dv AUDIO_MIXER_READ
 and
 .Dv AUDIO_MIXER_WRITE
 commands.
 The
 .Va type
 field identifies the type of this mixer control.
 Enumeration types are typically used for on/off style controls (e.g. a
 mute control) or for input/output device selection (e.g. select
 recording input source from CD, line in, or microphone).
 Set types are similar to enumeration types but any combination
 of the mask bits can be used.
 .Pp
 The
 .Va mixer_class
 field identifies what class of control this is.
 The
 .Pq arbitrary
 value set by the hardware driver may be determined by examining the
 .Va mixer_class
 field of the class itself,
 a mixer of type
 .Dv AUDIO_MIXER_CLASS .
 For example, a mixer controlling the input gain on the line in circuit
 would have a
 .Va mixer_class
 that matches an input class device with the name
 .Dq inputs
 .Dv ( AudioCinputs ) ,
 and would have a
 .Va label
 of
 .Dq line
 .Dv ( AudioNline ) .
 Mixer controls which control audio circuitry for a particular audio
 source (e.g. line-in, CD in, DAC output) are collected under the input class,
 while those which control all audio sources (e.g. master volume,
 equalization controls) are under the output class.
 Hardware devices capable of recording typically also have a record class,
 for controls that only affect recording,
 and also a monitor class.
 .Pp
 The
 .Va next
 and
 .Va prev
 may be used by the hardware device driver to provide hints for the next
 and previous devices in a related set (for example, the line in level
 control would have the line in mute as its
 .Dq next
 value).
 If there is no relevant next or previous value,
 .Dv AUDIO_MIXER_LAST
 is specified.
 .Pp
 For
 .Dv AUDIO_MIXER_ENUM
 mixer control types,
 the enumeration values and their corresponding names are filled in.
 For example, a mute control would return appropriate values paired with
 .Dv AudioNon
 and
 .Dv AudioNoff .
 For
 .Dv AUDIO_MIXER_VALUE
 and
 .Dv AUDIO_MIXER_SET
 mixer control types, the channel count is
 returned; the units name specifies what the level controls (typical
 values are
 .Dv AudioNvolume ,
 .Dv AudioNtreble ,
 .Dv AudioNbass ) .
 .\" For AUDIO_MIXER_SET mixer control types, what is what?
 .El
 .Pp
 By convention, all the mixer devices can be distinguished from other
 mixer controls because they use a name from one of the
 .Dv AudioC*
 string values.
 .Sh FILES
 .Bl -tag -width /dev/audioctl -compact
 .It Pa /dev/audio
 .It Pa /dev/audioctl
 .It Pa /dev/sound
 .It Pa /dev/mixer
 .El
 .Sh SEE ALSO
 .Xr audioctl 1 ,
 .Xr mixerctl 1 ,
 .Xr ioctl 2 ,
 .Xr ossaudio 3 ,
 .Xr midi 4 ,
 .Xr radio 4
 .Ss ISA bus
 .Xr aria 4 ,
 .Xr ess 4 ,
 .Xr gus 4 ,
 .Xr guspnp 4 ,
 .Xr pas 4 ,
 .Xr sb 4 ,
 .Xr wss 4 ,
 .Xr ym 4
 .Ss PCI bus
 .Xr auacer 4 ,
 .Xr auich 4 ,
 .Xr auixp 4 ,
 .Xr autri 4 ,
 .Xr auvia 4 ,
 .Xr azalia 4 ,
 .Xr clcs 4 ,
 .Xr clct 4 ,
 .Xr cmpci 4 ,
 .Xr eap 4 ,
 .Xr emuxki 4 ,
 .Xr esa 4 ,
 .Xr esm 4 ,
 .Xr eso 4 ,
 .Xr fms 4 ,
 .Xr neo 4 ,
 .Xr sv 4 ,
 .Xr yds 4
 .Ss PCMCIA
 .Xr esl 4
 .Ss TURBOchannel
 .Xr bba 4
 .Ss USB
 .Xr uaudio 4
 .Sh BUGS
 If the device is used in
 .Xr mmap 2
 it is currently always mapped for writing (playing) due to
 VM system weirdness.

 @@ -1,517 +1,515 @@
-.\"	$NetBSD: pci.4,v 1.89 2008/12/16 02:14:24 jakllsch Exp $
+.\"	$NetBSD: pci.4,v 1.90 2009/01/03 17:44:20 christos Exp $
 .\"
 .\" Copyright (c) 1997 Jason R. Thorpe.  All rights reserved.
 .\" Copyright (c) 1997 Jonathan Stone
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 3. All advertising materials mentioning features or use of this software
 .\"    must display the following acknowledgements:
 .\"      This product includes software developed by Jonathan Stone
 .\" 4. The name of the author may not be used to endorse or promote products
 .\"    derived from this software without specific prior written permission
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 16, 2008
+.Dd January 3, 2009
 .Dt PCI 4
 .Os
 .Sh NAME
 .Nm pci
 .Nd introduction to machine-independent PCI bus support and drivers
 .Sh SYNOPSIS
 .Cd "pci* at mainbus? bus ?"
 .Cd "pci* at pchb? bus ?"
 .Cd "pci* at ppb? bus ?"
 .Pp
 .Cd options PCIVERBOSE
 .Cd options PCI_CONFIG_DUMP
 .Cd options PCI_ADDR_FIXUP
 .Cd options PCI_BUS_FIXUP
 .Cd options PCI_INTR_FIXUP
 .Sh DESCRIPTION
 Other
 .Nm
 attachments are machine-dependent and depend on the bus topology and
 .Tn PCI
 bus interface of your system.
 See
 .Xr intro 4
 for your system for details.
 .Pp
 .Nx
 includes a machine-independent
 .Tn PCI
 bus subsystem and
 several machine-independent
 .Tn PCI
 device drivers.
 .Pp
 Your system may support additional
 .Tn PCI
 devices.
 Drivers for
 .Tn PCI
 devices not listed here are machine-dependent.
 Consult your system's
 .Xr intro 4
 for additional information.
 .Sh OPTIONS
 .Bl -tag -width PCI_ADDR_FIXUP -offset 3n
 .It Dv PCI_ADDR_FIXUP
 Fixup PCI I/O and memory addresses.
 .Pp
 Some i386 and amd64 BIOS implementations don't allocate I/O space and
 memory space for some PCI devices -- primarily BIOS in PnP mode, or laptops
 that expect devices to be configured via ACPI.
 Since necessary space isn't allocated, those devices
 will not work without special handling.
 .Pp
 This option allocates I/O space and memory space
 instead of relying upon the BIOS to do so.
 .Pp
 If necessary space is already correctly assigned to the devices,
 this option leaves the space as is.
 .Pp
 .It Dv PCI_BUS_FIXUP
 Fixup PCI bus numbering; needed for many
 .Xr cardbus 4
 bridges.
 .Pp
 Each PCI bus and CardBus should have a unique bus number.
 But some BIOS implementations don't assign a bus number
 for subordinate PCI buses.
 And many BIOS implementations
 don't assign a bus number for CardBuses.
 .Pp
 A typical symptom of this is the following boot message:
 .D1 Sy cardbus0 at cardslot0: bus 0 device 0...
 Please note that this cardbus0 has a bus number
 .Sq 0 ,
 but normally the bus number 0 is used by the machine's
 primary PCI bus.
 Thus, this bus number for cardbus is incorrect
 .Pq not assigned .
 In this situation, a device located in cardbus0 doesn't
 show correct device ID,
 because its bus number 0 incorrectly refers to the primary
 PCI bus, and a device ID in the primary PCI bus is shown
 in the boot message instead of the device's ID in the cardbus0.
 .Pp
 This option assigns bus numbers for all subordinate
 PCI buses and CardBuses.
 .Pp
 Since this option renumbers all PCI buses and CardBuses,
 all bus numbers of subordinate buses become different
 when this option is enabled.
 .It Dv PCI_INTR_FIXUP
 Fixup PCI interrupt routing via PCIBIOS or ACPI.
 .Pp
 Some i386 and amd64 BIOS implementations don't assign an interrupt for
 some devices.
 .Pp
 This option assigns an interrupt for such devices instead
 of relying upon the BIOS to do so.
 .Pp
 If a valid interrupt has already been assigned to a device, this
 option leaves the interrupt as is.
 .El
 .Sh HARDWARE
 .Nx
 includes machine-independent
 .Tn PCI
 drivers, sorted by device type and driver name:
 .Ss SCSI interfaces
 .Bl -tag -width pcdisplay -offset indent
 .It ahc
 Adaptec 29xx, 39xx, and other AIC-7xxx-based
 .Tn SCSI
 interfaces.
 .It adv
 Advansys
 .Tn SCSI
 interfaces.
 .It adw
 Advansys Ultra Wide
 .Tn SCSI
 interfaces.
 .It bha
 Buslogic BT-9xx
 .Tn SCSI
 interfaces.
 .It dpt
 DPT SmartCache/SmartRAID III and IV
 .Tn SCSI
 interfaces.
 .It iha
 Initio INIC-940/950
 .Tn SCSI
 interfaces.
 .It isp
 QLogic ISP-1020, ISP-1040, and ISP-2100
 .Tn SCSI
 and
 .Tn FibreChannel
 interfaces.
 .It mfi
 LSI Logic \*[Am] Dell MegaRAID SAS RAID controllers.
 .It mly
 Mylex AcceleRAID and eXtremeRAID controllers with v6 firmware.
 .It pcscp
 Advanced Micro Devices Am53c974 PCscsi-PCI
 .Tn SCSI
 interfaces.
 .It siop
 Symbios Logic/NCR 53c8xx-family
 .Tn SCSI
 interfaces.
 .It trm
 Tekram TRM-S1040 ASIC based
 .Tn SCSI
 interfaces.
 .El
 .Ss Disk and tape controllers
 .Bl -tag -width pcdisplay -offset indent
 .It aac
 The Adaptec AAC family of RAID controllers.
 .It ahcisata
 AHCI 1.0 and 1.1 compliant SATA controllers.
 .It amr
 The AMI and LSI Logic MegaRAID family of RAID controllers.
 .It cac
 Compaq array controllers.
 .It icp
 ICP Vortex GDT and Intel Storage RAID controllers.
 .It mlx
 Mylex DAC960 and DEC SWXCR RAID controllers.
 .It pciide
 IDE disk controllers.
 .It siisata
 Silicon Image SATA-II controllers.
 .It twe
 Ware Escalade RAID controllers.
 .El
 .Ss Network interfaces
 .Bl -tag -width pcdisplay -offset indent
 .It an
 .Tn Aironet
 /4800 and
 .Tn Cisco
 series 802.11 interfaces.
 .It bnx
 Broadcom NetXtreme II 10/100/1000 Ethernet interfaces.
 .It de
 .Tn DEC
 DC21x4x (Tulip) based
 .Tn Ethernet
 interfaces, including the DE435,
 DE450, and DE500, and Znyx, SMC, Cogent/Adaptec, and Asante single- and
 multi-port
 .Tn Ethernet
 interfaces.
 .It en
 Midway-based Efficient Networks Inc. and Adaptec ATM interfaces.
 .It ep
 Com 3c590, 3c595, 3c900, and 3c905
 .Tn Ethernet
 interfaces.
 .It epic
 SMC83C170 (EPIC/100)
 .Tn Ethernet
 interfaces.
 .It esh
 RoadRunner-based HIPPI interfaces.
 .It ex
 Com 3c900, 3c905, and 3c980
 .Tn Ethernet
 interfaces.
 .It fpa
 .Tn DEC
 DEFPA
 .Tn FDDI
 interfaces.
 .It fxp
 Intel EtherExpress PRO 10+/100B
 .Tn Ethernet
 interfaces.
 .It gsip
 National Semiconductor DP83820 based Gigabit
 .Tn Ethernet
 interfaces.
 .It hme
 Sun Microelectronics STP2002-STQ
 .Tn Ethernet
 interfaces.
 .It le
 PCNet-PCI
 .Tn Ethernet
 interfaces.
 Note, the
 .Xr pcn 4
 driver supersedes this driver.
 .It lmc
 LAN Media Corp WAN interfaces.
 .It msk
 Marvell Yukon 2 based Gigabit
 .Tn Ethernet
 interfaces.
 .It ne
 NE2000-compatible
 .Tn Ethernet
 interfaces.
 .It nfe
 NVIDIA nForce
 .Tn Ethernet
 interfaces.
 .It ntwoc
 SDL Communications N2pci and WAN/ic 400 synchronous serial interfaces.
 .It pcn
 AMD PCnet-PCI family of
 .Tn Ethernet
 interfaces.
 .It ral
 Ralink Technology RT2500/RT2600-based 802.11a/b/g wireless network interfaces.
 .It rtk
 Realtek 8129/8139 based
 .Tn Ethernet
 interfaces.
 .It sf
 Adaptec AIC-6915 10/100
 .Tn Ethernet
 interfaces.
 .It sip
 Silicon Integrated Systems SiS 900, SiS 7016, and National Semiconductor
 DP83815 based
 .Tn Ethernet
 interfaces.
 .It sk
 SysKonnect SK-98xx based Gigabit
 .Tn Ethernet
 interfaces.
 .It ste
 Sundance ST-201 10/100 based
 .Tn Ethernet
 interfaces.
 .It stge
 Sundance/Tamarack TC9021 based Gigabit
 .Tn Ethernet
 interfaces.
 .It ti
 Alteon Networks Tigon I and Tigon II Gigabit Ethernet driver.
 .It tl
 Texas Instruments ThunderLAN-based
 .Tn Ethernet
 interfaces.
 .It tlp
 DECchip 21x4x and clone
 .Tn Ethernet
 interfaces.
 .It vge
 VIA Networking Technologies VT6122 PCI Gigabit Ethernet adapter driver.
 .It vr
 VIA VT3043 (Rhine) and VT86C100A (Rhine-II)
 .Tn Ethernet
 interfaces.
 .It wi
 WaveLAN/IEEE and PRISM-II 802.11 wireless interfaces.
 .It wm
 Intel i8254x Gigabit
 .Tn Ethernet
 driver.
 .El
 .Ss Serial interfaces
 .Bl -tag -width pcdisplay -offset indent
 .It cy
 Cyclades Cyclom-4Y, -8Y, and -16Y multi-port serial interfaces.
 .It cz
 Cyclades-Z series multi-port serial interfaces.
 .El
 .Ss Audio devices
 .Bl -tag -width pcdisplay -offset indent
 .It auacer
 Acer Labs M5455 I/O Controller Hub integrated AC'97 audio device.
 .It auich
 Intel I/O Controller Hub integrated AC'97 audio device.
 .It auvia
 VIA VT82C686A integrated AC'97 audio device.
 .It autri
 Trident 4DWAVE-DX/NX, SiS 7018, ALi M5451 AC'97 audio device.
 .It clcs
 Cirrus Logic CS4280 audio device.
 .It clct
 Cirrus Logic CS4281 audio device.
 .It cmpci
 C-Media CMI8x38 audio device.
 .It eap
 Ensoniq AudioPCI audio device.
 .It emuxki
 Creative Labs SBLive! and PCI 512 audio device.
 .It esa
 ESS Technology Allegro-1 / Maestro-3 audio device.
 .It esm
 ESS Maestro-1/2/2e PCI AC'97 Audio Accelerator audio device.
 .It eso
 ESS Solo-1 PCI AudioDrive audio device.
 .It fms
 Forte Media FM801 audio device.
 .It neo
 NeoMagic MagicMedia 256 audio device.
 .It sv
 S3 SonicVibes audio device.
 .It yds
 Yamaha YMF724/740/744/754-based audio device.
 .El
 .Ss Bridges
 .Bl -tag -width pcdisplay -offset indent
 .It cbb
 .Tn PCI
 Yenta compatible
 .Tn CardBus
 bridges.
 .It ppb
 Generic
 .Tn PCI Ns \- Ns Tn PCI
 bridges, including
 .Tn PCI
 expansion backplanes.
 .El
 .Ss Miscellaneous devices
 .Bl -tag -width pcdisplay -offset indent
 .It bktr
 Brooktree 848 compatible TV cards.
 .It ehci
 USB EHCI host controllers.
 .It iop
 I2O I/O processors.
 .It mr
 Guillemot Maxi Radio FM 2000 FM radio device.
 .It oboe
 Toshiba OBOE IrDA SIR/FIR controller.
 .It ohci
 USB OHCI host controllers.
 .It pcic
 .Tn PCI
 .Tn PCMCIA
 controllers, including the Cirrus Logic GD6729.
 .It puc
 PCI
 .Dq universal
 communications cards, containing
 .Xr com 4
 and
 .Xr lpt 4
 communications ports.
 .It uhci
 USB UHCI host controllers.
 .It viapm
 VIA VT82C686A hardware monitors.
 .It vga
 VGA graphics boards.
 .El
 .Sh SEE ALSO
 .Xr aac 4 ,
 .Xr adv 4 ,
 .Xr adw 4 ,
 .Xr agp 4 ,
 .Xr ahc 4 ,
 .Xr ahcisata 4 ,
 .Xr amr 4 ,
 .Xr an 4 ,
 .Xr auich 4 ,
 .Xr autri 4 ,
 .Xr auvia 4 ,
 .Xr bha 4 ,
 .Xr bktr 4 ,
 .Xr bnx 4 ,
 .Xr cac 4 ,
 .Xr cbb 4 ,
 .Xr clcs 4 ,
 .Xr cmpci 4 ,
 .Xr cy 4 ,
 .Xr cz 4 ,
 .Xr de 4 ,
 .Xr dpt 4 ,
 .Xr eap 4 ,
 .Xr ehci 4 ,
 .Xr emuxki 4 ,
 .Xr en 4 ,
 .Xr ep 4 ,
 .Xr epic 4 ,
 .Xr esa 4 ,
 .Xr esh 4 ,
 .Xr esm 4 ,
 .Xr eso 4 ,
 .Xr ex 4 ,
 .Xr fms 4 ,
 .Xr fpa 4 ,
 .Xr fxp 4 ,
 .Xr gsip 4 ,
 .Xr hme 4 ,
 .Xr icp 4 ,
 .Xr iha 4 ,
 .Xr intro 4 ,
 .Xr iop 4 ,
 .Xr isp 4 ,
 .Xr le 4 ,
 .Xr lmc 4 ,
 .Xr mfi 4 ,
 .Xr mlx 4 ,
 .Xr mly 4 ,
 .Xr mpt 4 ,
 .Xr msk 4 ,
 .Xr ne 4 ,
 .Xr neo 4 ,
 .Xr nfe 4 ,
 .Xr ntwoc 4 ,
 .Xr oboe 4 ,
 .Xr ohci 4 ,
 .Xr pcic 4 ,
 .Xr pciide 4 ,
 .Xr pcn 4 ,
 .Xr pcscp 4 ,
 .Xr ppb 4 ,
 .Xr puc 4 ,
 .Xr ral 4 ,
 .Xr rtk 4 ,
 .Xr sf 4 ,
 .Xr siop 4 ,
 .Xr sip 4 ,
 .Xr sk 4 ,
 .Xr ste 4 ,
 .Xr stge 4 ,
 .Xr sv 4 ,
 .Xr ti 4 ,
 .Xr tl 4 ,
 .Xr tlp 4 ,
 .Xr trm 4 ,
 .Xr twe 4 ,
 .Xr uhci 4 ,
 .Xr vga 4 ,
 .Xr vge 4 ,
 .Xr viapm 4 ,
 .Xr vr 4 ,
 .Xr wi 4 ,
 .Xr wm 4 ,
 .Xr wscons 4 ,
 .Xr yds 4
 .Sh HISTORY
 The machine-independent
 .Tn PCI
 subsystem appeared in
 .Nx 1.2 .