1.\" $NetBSD: audio.4,v 1.5 1997/05/07 19:24:25 augustss Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by John T. Kohl. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 11, 1997 38.Dt AUDIO 4 39.Os NetBSD 40.Sh NAME 41.Nm audio 42.Nd device-independent audio driver layer 43.Sh SYNOPSIS 44.Fd #include <sys/types.h> 45.Fd #include <sys/audioio.h> 46.Sh DESCRIPTION 47The 48.Nm 49driver provides support for various audio peripherals. It provides a 50uniform programming interface layer above different underlying audio 51hardware drivers. The audio layer provides full-duplex operation if the 52underlying hardware configuration supports it. 53.Pp 54There are three device files available for audio operation: 55.Pa /dev/audio , 56.Pa /dev/sound , 57and 58.Pa /dev/mixer . 59.Pa /dev/audio 60and 61.Pa /dev/sound 62are used for recording or playback of digital samples. 63.Pa /dev/mixer 64is used to manipulate volume, recording source, or other audio mixer 65functions. 66.Sh SAMPLING DEVICES 67When 68.Pa /dev/audio 69is opened, it automatically directs the underlying driver to manipulate 70monaural 8-bit mulaw samples. In addition, if it is opened read-only 71(write-only) the device is set to half-duplex record (play) mode with 72recording (playing) unpaused and playing (recording) paused. 73When 74.Pa /dev/sound 75is opened, it maintains the previous audio sample mode and 76record/playback mode. In all other respects 77.Pa /dev/audio 78and 79.Pa /dev/sound 80are identical. 81.Pp 82Only one process may hold open a sampling device at a given time 83(although file descriptors may be shared between processes once the 84first open completes). 85.Pp 86Reads and writes to a sampling device should be in multiples of the 87current audio block size which can be queried and set using the 88interfaces described below. 89Writes which are not multiples of the block size will be padded to a 90block boundary with silence. 91Reads which are not multiples of the block size will consume a block 92from the audio hardware but only return the requested number of bytes. 93.Pp 94On a half-duplex device, writes while recording is in progress will be 95immediately discarded. Similarly, reads while playback is in progress 96will be filled with silence but delayed to return at the current 97sampling rate. If both playback and recording are requested on a half-duplex 98device, playback mode takes precedence and recordings will get silence. 99On a full-duplex device, reads and writes may operate 100concurrently without interference. 101On either type of device, if the playback mode is paused then silence is 102played instead of the provided samples, and if recording is paused then 103the process blocks in 104.Xr read 2 105until recording is unpaused. 106.Pp 107If a writing process does not call 108.Xr write 2 109frequently enough to provide audio playback blocks in time for the next 110hardware interrupt service, one or more audio silence blocks will be 111queued for playback, unless the 112.Dv AUMODE_PLAY_ALL 113mode is set. The writing process must provide enough data via 114subsequent write calls to ``catch up'' in time to the current audio 115block before any more process-provided samples will be played. 116[Alternatively, the playing process can use one of the interfaces below 117to halt and later restart audio playback.] 118If a reading process does not call 119.Xr read 2 120frequently enough, it will simply miss samples. 121.Pp 122The following 123.Xr ioctl 2 124commands are supported on the sample devices: 125.Pp 126.Bl -tag -width indent -compact 127.It Dv AUDIO_FLUSH 128This command stops all playback and recording, clears all queued 129buffers, resets error counters, and restarts recording and playback as 130appropriate for the current sampling mode. 131.It Dv AUDIO_RERROR (int) 132This command fetches the count of dropped input samples into its integer 133argument. There is no information regarding when in the sample stream 134they were dropped. 135.It Dv AUDIO_WSEEK (int) 136This command fetches the count of samples are queued ahead of the 137first sample in the most recent sample block written into its integer argument. 138.It Dv AUDIO_DRAIN 139This command suspends the calling process until all queued playback 140samples have been played by the hardware. 141.It Dv AUDIO_GETDEV (audio_device_t) 142This command fetches the current hardware device information into the 143audio_device_t argument. 144.Bd -literal 145typedef struct audio_device { 146 char name[MAX_AUDIO_DEV_LEN]; 147 char version[MAX_AUDIO_DEV_LEN]; 148 char config[MAX_AUDIO_DEV_LEN]; 149} audio_device_t; 150.Ed 151.It Dv AUDIO_GETENC (audio_encoding_t) 152This command is used iteratively to fetch sample encoding names and 153format_ids into the input/output audio_encoding_t argument. 154.Bd -literal 155typedef struct audio_encoding { 156 int index; /* input: nth encoding */ 157 char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */ 158 int encoding; /* value for encoding parameter */ 159 int precision; /* value for precision parameter */ 160 int flags; 161#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 162} audio_encoding_t; 163.Ed 164To query 165all the supported encodings, start with an index field of zero and 166continue with successive encodings (1, 2, ...) until the command returns 167an error. 168.It Dv AUDIO_GETFD (int) 169This command fetches a non-zero value into its integer argument if the 170hardware supports full-duplex operation, or a zero value if the hardware 171only supports half-duplex operation. 172.It Dv AUDIO_SETFD (int) 173This command sets the device into full-duplex operation if its integer 174argument has a non-zero value, or into half-duplex operation if it 175contains a zero value. If the device does not support full-duplex 176operation, attempting to set full-duplex mode returns an error. 177.It Dv AUDIO_GETINFO (audio_info_t) 178.It Dv AUDIO_SETINFO (audio_info_t) 179Get or set audio information as encoded in the audio_info structure. 180.Bd -literal 181typedef struct audio_info { 182 struct audio_prinfo play; /* Info for play (output) side */ 183 struct audio_prinfo record; /* Info for record (input) side */ 184 u_int buffersize; /* total size audio buffer */ 185 /* BSD extensions */ 186 u_int blocksize; /* H/W read/write block size */ 187 u_int hiwat; /* output high water mark */ 188 u_int lowat; /* output low water mark */ 189 u_int backlog; /* samples of output backlog to gen. */ 190 u_int mode; /* current device mode */ 191#define AUMODE_PLAY 0x01 192#define AUMODE_RECORD 0x02 193#define AUMODE_PLAY_ALL 0x04 /* play all samples--no real-time correction */ 194}; 195.Ed 196.Pp 197When setting the current state with 198.Dv AUDIO_SETINFO , 199the audio_info structure should first be initialized with 200.Li Dv AUDIO_INITINFO Po &info Pc 201and then the particular values to be changed should be set. This 202allows the audio driver to only set those things that you wish to 203change and eliminates the need to query the device with 204.Dv AUDIO_GETINFO 205first. 206.Pp 207The 208.Va mode 209field should be set to 210.Dv AUMODE_PLAY , 211.Dv AUMODE_RECORD , 212.Dv AUMODE_PLAY_ALL , 213or a bitwise OR combination of the three. 214.Dv AUMODE_PLAY 215and 216.Dv AUMODE_PLAY_ALL 217are mutually exclusive, and only full-duplex audio devices support 218simultaneous record and playback. 219.Pp 220.Va hiwat 221and 222.Va lowat 223are used to control write behavior. Writes to the audio devices will 224queue up blocks until the high-water mark is reached, at which point any 225more write calls will block until the queue is drained to the low-water 226mark. 227.Va hiwat 228and 229.Va lowat 230set those high- and low-water marks (in audio blocks). 231.Pp 232.Va blocksize 233sets the current audio blocksize. The generic audio driver layer and 234the hardware driver have the opportunity to adjust this block size to 235get it within implementation-required limits. Upon return from an 236.Dv AUDIO_SETINFO 237call, the actual blocksize set is returned in this field. 238.Pp 239.Va backlog 240is currently unused. 241.Bd -literal 242struct audio_prinfo { 243 u_int sample_rate; /* sample rate in samples/s */ 244 u_int channels; /* number of channels, usually 1 or 2 */ 245 u_int precision; /* number of bits/sample */ 246 u_int encoding; /* data encoding (AUDIO_ENCODING_* above) */ 247 u_int gain; /* volume level */ 248 u_int port; /* selected I/O port */ 249 u_long seek; /* BSD extension */ 250 u_int ispare[3]; 251 /* Current state of device: */ 252 u_int samples; /* number of samples */ 253 u_int eof; /* End Of File (zero-size writes) counter */ 254 u_char pause; /* non-zero if paused, zero to resume */ 255 u_char error; /* non-zero if underflow/overflow ocurred */ 256 u_char waiting; /* non-zero if another process hangs in open */ 257 u_char cspare[3]; 258 u_char open; /* non-zero if currently open */ 259 u_char active; /* non-zero if I/O is currently active */ 260}; 261.Ed 262.Pp 263[Note: many hardware audio drivers require identical playback and 264recording sample rates, sample encodings, and channel counts. The 265recording information is always set last and will prevail on such hardware.] 266.Pp 267The encoding parameter can have the following values: 268.Bl -tag -width indent -compact 269.It Dv AUDIO_ENCODING_ULAW 270mulaw encoding, 8 bits/sample 271.It Dv AUDIO_ENCODING_ALAW 272alaw encoding, 8 bits/sample 273.It Dv AUDIO_ENCODING_LINEAR 274two's complement signed linear encoding with the platform byte order 275.It Dv AUDIO_ENCODING_ULINEAR 276unsigned linear encoding with the platform byte order 277.It Dv AUDIO_ENCODING_ADPCM 278ADPCM encoding, 8 bits/sample 279.It Dv AUDIO_ENCODING_LINEAR_LE 280two's complement signed linear encoding with little endian byte order 281.It Dv AUDIO_ENCODING_LINEAR_BE 282two's complement signed linear encoding with big endian byte order 283.It Dv AUDIO_ENCODING_ULINEAR_LE 284unsigned linear encoding with little endian byte order 285.It Dv AUDIO_ENCODING_ULINEAR_BE 286unsigned linear encoding with little big byte order 287.El 288.Pp 289The gain and port settings provide simple shortcuts to the richer mixer 290interface described below. The gain should be in the range 291.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN . 292The port value is hardware-dependent 293and should be selected (if setting with 294.Dv AUDIO_SETINFO ) 295based upon return values from the mixer query functions below or from 296a prior 297.Dv AUDIO_GETINFO . 298.Pp 299The 300.Va seek 301and 302.Va samples 303fields are only used for 304.Dv AUDIO_GETINFO . 305.Va seek 306represents the count of 307samples pending; 308.Va samples 309represents the total number of samples recorded or played, less those 310that were dropped due to inadequate consumption/production rates. 311.Pp 312.Va pause 313returns the current pause/unpause state for recording or playback. 314For 315.Dv AUDIO_SETINFO , 316if the pause value is specified it will either pause 317or unpause the particular direction. 318.El 319.Sh MIXER DEVICE 320The mixer device, 321.Pa /dev/mixer , 322may be manipulated with 323.Xr ioctl 2 324but does not support 325.Xr read 2 326or 327.Xr write 2 . 328It supports the following 329.Xr ioctl 2 330commands: 331.Bl -tag -width indent -compact 332.It Dv AUDIO_GETDEV (audio_device_t) 333This command is the same as described above for the sampling devices. 334.It Dv AUDIO_MIXER_READ (mixer_ctrl_t) 335.It Dv AUDIO_MIXER_WRITE (mixer_ctrl_t) 336.Bd -literal 337#define AUDIO_MIXER_CLASS 0 338#define AUDIO_MIXER_ENUM 1 339#define AUDIO_MIXER_SET 2 340#define AUDIO_MIXER_VALUE 3 341typedef struct mixer_ctrl { 342 int dev; /* input: nth device */ 343 int type; 344 union { 345 int ord; /* enum */ 346 int mask; /* set */ 347 mixer_level_t value; /* value */ 348 } un; 349} mixer_ctrl_t; 350.Ed 351These commands read the current mixer state or set new mixer state for 352the specified device 353.Va dev . 354.Va type 355identifies which type of value is supplied in the mixer_ctrl_t 356argument. 357For a mixer value, the 358.Va value 359field specifies both the number of channels and the values for each of 360the channels. If the channel count does not match the current channel 361count, the attempt to change the setting may fail (depending on the 362hardware device driver implementation). 363For an enumeration value, the 364.Va ord 365field should be set to one of the possible values as returned by a prior 366.Dv AUDIO_MIXER_DEVINFO 367command. The type 368.Dv AUDIO_MIXER_CLASS 369is only used for classifying particular mixer device 370types and is not used for 371.Dv AUDIO_MIXER_READ 372or 373.Dv AUDIO_MIXER_WRITE . 374.It Dv AUDIO_MIXER_DEVINFO (mixer_devinfo_t) 375This command is used iteratively to fetch audio mixer device information 376into the input/output mixer_devinfo_t argument. To query all the 377supported encodings, start with an index field of zero and continue with 378successive encodings (1, 2, ...) until the command returns an error. 379.Bd -literal 380typedef struct mixer_devinfo { 381 int index; /* input: nth mixer device */ 382 audio_mixer_name_t label; 383 int type; 384 int mixer_class; 385 int next, prev; 386#define AUDIO_MIXER_LAST -1 387 union { 388 struct audio_mixer_enum { 389 int num_mem; 390 struct { 391 audio_mixer_name_t label; 392 int ord; 393 } member[32]; 394 } e; 395 struct audio_mixer_set { 396 int num_mem; 397 struct { 398 audio_mixer_name_t label; 399 int mask; 400 } member[32]; 401 } s; 402 struct audio_mixer_value { 403 audio_mixer_name_t units; 404 int num_channels; 405 } v; 406 } un; 407} mixer_devinfo_t; 408.Ed 409The 410.Va label 411field identifies the name of this particular mixer control. The 412.Va index 413field may be used as the 414.Va dev 415field in 416.Dv AUDIO_MIXER_READ 417and 418.Dv AUDIO_MIXER_WRITE 419commands. The 420.Va type 421field identifies the type of this mixer control. 422Enumeration types are typically used for on/off style controls (e.g. a 423mute control) or for input/output device selection (e.g. select 424recording input source from CD, line in, or microphone). 425.Pp 426The 427.Va mixer_class 428field identifies what class of control this is. This value is set to 429the index value used to query the class itself. For example, a mixer 430level controlling the input gain on the ``line in'' circuit would be a 431class that matches an input class device with the name ``Inputs'' 432(AudioCInputs). 433Mixer controls which control audio circuitry for a particular audio 434source (e.g. line-in, CD in, DAC output) are collected under the input class, 435while those which control all audio sources (e.g. master volume, 436equalization controls) are under the output class. 437.Pp 438The 439.Va next 440and 441.Va prev 442may be used by the hardware device driver to provide hints for the next 443and previous devices in a related set (for example, the line in level 444control would have the line in mute as its "next" value). If there is 445no relevant next or previous value, 446.Dv AUDIO_MIXER_LAST 447is specified. 448.Pp 449For 450.Dv AUDIO_MIXER_ENUM 451mixer control types, 452the enumeration values and their corresponding names are filled in. For 453example, a mute control would return appropriate values paired with 454AudioNon and AudioNoff. 455For 456.Dv AUDIO_MIXER_VALUE 457mixer control types, the channel count is 458returned; the units name specifies what the level controls (typical 459values are AudioNvolume, AudioNtreble, AudioNbass). 460.\" For AUDIO_MIXER_SET mixer control types, what is what? 461.El 462.Pp 463By convention, all the mixer device indices for generic 464class grouping are at the end of the index number space for a particular 465hardware device, and can be distinguished from other mixer controls 466because they use a name from one of the AudioC* string values. 467.Sh FILES 468.Bl -tag -width /dev/audio -compact 469.It Pa /dev/audio 470.It Pa /dev/sound 471.It Pa /dev/mixer 472.El 473.Sh SEE ALSO 474.Xr ioctl 2 . 475.br 476For ports using the ISA bus: 477.Xr gus 4 , 478.Xr pas 4 , 479.Xr pss 4 , 480.Xr sb 4 , 481.Xr wss 4 . 482.Sh BUGS 483The device class conventions are just a wish and not yet reality. 484.Pp 485Audio playback can be scratchy with pops and crackles due to the 486audio layer's buffering scheme. Using a bigger blocksize will help 487reduce such annoyances. 488 489