1.\" $OpenBSD: audio.4,v 1.20 2001/03/07 23:58:49 todd Exp $ 2.\" $NetBSD: audio.4,v 1.20 1998/05/28 17:27:15 augustss Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by John T. Kohl. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd March 11, 1997 39.Dt AUDIO 4 40.Os 41.Sh NAME 42.Nm audio 43.Nd device-independent audio driver layer 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/ioctl.h> 47.Fd #include <string.h> 48.Fd #include <sys/audioio.h> 49.Sh DESCRIPTION 50The 51.Nm 52driver provides support for various audio peripherals. 53It provides a uniform programming interface layer above different 54underlying audio hardware drivers. 55The audio layer provides full-duplex operation if the 56underlying hardware configuration supports it. 57.Pp 58There are four device files available for audio operation: 59.Pa /dev/audio , 60.Pa /dev/sound , 61.Pa /dev/audioctl , 62and 63.Pa /dev/mixer . 64.Pa /dev/audio 65and 66.Pa /dev/sound 67are used for recording or playback of digital samples. 68.Pa /dev/mixer 69is used to manipulate volume, recording source, or other audio mixer 70functions. 71.Pa /dev/audioctl 72accepts the same 73.Xr ioctl 2 74operations as 75.Pa /dev/sound , 76but no other operations. 77In contrast to 78.Pa /dev/sound 79which has the exclusive open property 80.Pa /dev/audioctl 81can be opened at any time and can be used to manipulate the audio device 82while it is in use. 83.Sh SAMPLING DEVICES 84When 85.Pa /dev/audio 86is opened, it automatically directs the underlying driver to manipulate 87monaural 8-bit mulaw samples. 88In addition, if it is opened read-only 89(write-only) the device is set to half-duplex record (play) mode with 90recording (playing) unpaused and playing (recording) paused. 91When 92.Pa /dev/sound 93is opened, it maintains the previous audio sample mode and 94record/playback mode. 95In all other respects 96.Pa /dev/audio 97and 98.Pa /dev/sound 99are identical. 100.Pp 101Only one process may hold open a sampling device at a given time 102(although file descriptors may be shared between processes once the 103first open completes). 104.Pp 105On a half-duplex device, writes while recording is in progress will be 106immediately discarded. 107Similarly, reads while playback is in progress 108will be filled with silence but delayed to return at the current 109sampling rate. 110If both playback and recording are requested on a half-duplex 111device, playback mode takes precedence and recordings will get silence. 112On a full-duplex device, reads and writes may operate 113concurrently without interference. 114If a full-duplex capable audio device is opened for both reading and writing 115it will start in half-duplex play mode; full-duplex mode has to be set 116explicitly. 117On either type of device, if the playback mode is paused then silence is 118played instead of the provided samples, and if recording is paused then 119the process blocks in 120.Xr read 2 121until recording is unpaused. 122.Pp 123If a writing process does not call 124.Xr write 2 125frequently enough to provide samples at the pace the hardware 126consumes them silence is inserted. 127If the 128.Dv AUMODE_PLAY_ALL 129mode is not set the writing process must 130provide enough data via 131subsequent write calls to ``catch up'' in time to the current audio 132block before any more process-provided samples will be played. 133If a reading process does not call 134.Xr read 2 135frequently enough, it will simply miss samples. 136.Pp 137The audio device is normally accessed with 138.Xr read 2 139or 140.Xr write 2 141calls, but it can also be mapped into user memory with 142.Xr mmap 2 143(when supported by the device). 144Once the device has been mapped it can no longer be accessed 145by read or write; all access is by reading and writing to 146the mapped memory. 147The device appears as a block of memory 148of size 149.Va buffer_size 150(as available via 151.Dv AUDIO_GETINFO ). 152The device driver will continuously move data from this buffer 153from/to the audio hardware, wrapping around at the end of the buffer. 154To find out where the hardware is currently accessing data in the buffer the 155.Dv AUDIO_GETIOFFS 156and 157.Dv AUDIO_GETOOFFS 158calls can be used. 159The playing and recording buffers are distinct and must be 160mapped separately if both are to be used. 161Only encodings that are not emulated (i.e., where 162.Dv AUDIO_ENCODINGFLAG_EMULATED 163is not set) work properly for a mapped device. 164.Pp 165The audio device, like most devices, can be used in 166.Va select, 167can be set in non-blocking mode and can be set to send a 168.Dv SIGIO 169when I/O is possible. 170The mixer device can be set to generate a 171.Dv SIGIO 172whenever a mixer value is changed. 173.Pp 174The following 175.Xr ioctl 2 176commands are supported on the sample devices: 177.Pp 178.Bl -tag -width indent -compact 179.It Dv AUDIO_FLUSH 180This command stops all playback and recording, clears all queued 181buffers, resets error counters, and restarts recording and playback as 182appropriate for the current sampling mode. 183.It Dv AUDIO_RERROR (int) 184This command fetches the count of dropped input samples into its integer 185argument. 186There is no information regarding when in the sample stream 187they were dropped. 188.It Dv AUDIO_WSEEK (int) 189This command fetches the count of samples queued ahead of the 190first sample in the most recent sample block written into its integer argument. 191.It Dv AUDIO_DRAIN 192This command suspends the calling process until all queued playback 193samples have been played by the hardware. 194.It Dv AUDIO_GETDEV (audio_device_t) 195This command fetches the current hardware device information into the 196audio_device_t argument. 197.Bd -literal 198typedef struct audio_device { 199 char name[MAX_AUDIO_DEV_LEN]; 200 char version[MAX_AUDIO_DEV_LEN]; 201 char config[MAX_AUDIO_DEV_LEN]; 202} audio_device_t; 203.Ed 204.It Dv AUDIO_GETFD (int) 205This command returns the current setting of the full-duplex mode. 206.It Dv AUDIO_GETENC (audio_encoding_t) 207This command is used iteratively to fetch sample encoding names and 208format_ids into the input/output audio_encoding_t argument. 209.Bd -literal 210typedef struct audio_encoding { 211 int index; /* input: nth encoding */ 212 char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */ 213 int encoding; /* value for encoding parameter */ 214 int precision; /* value for precision parameter */ 215 int flags; 216#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 217} audio_encoding_t; 218.Ed 219To query 220all the supported encodings, start with an index field of 0 and 221continue with successive encodings (1, 2, ...) until the command returns 222an error. 223.It Dv AUDIO_SETFD (int) 224This command sets the device into full-duplex operation if its integer 225argument has a non-zero value, or into half-duplex operation if it 226contains a zero value. 227If the device does not support full-duplex 228operation, attempting to set full-duplex mode returns an error. 229.It Dv AUDIO_GETPROPS (int) 230This command gets a bit set of hardware properties. 231If the hardware 232has a certain property the corresponding bit is set, otherwise it is not. 233The properties can have the following values: 234.Bl -tag -width indent -compact 235.It Dv AUDIO_PROP_FULLDUPLEX 236the device admits full-duplex operation. 237.It Dv AUDIO_PROP_MMAP 238the device can be used with 239.Xr mmap 2 . 240.It Dv AUDIO_PROP_INDEPENDENT 241the device can set the playing and recording encoding parameters 242independently. 243.El 244.It Dv AUDIO_GETIOFFS (audio_offset_t) 245.It Dv AUDIO_GETOOFFS (audio_offset_t) 246This command fetches the current offset in the input(output) buffer where 247the hardware is putting(getting) data. 248It mostly useful when the device 249buffer is available in user space via the 250.Xr mmap 2 251call. 252The information is returned in the audio_offset structure. 253.Bd -literal 254typedef struct audio_offset { 255 u_int samples; /* Total number of bytes transferred */ 256 u_int deltablks; /* Blocks transferred since last checked */ 257 u_int offset; /* Physical transfer offset in buffer */ 258} audio_offset_t; 259.Ed 260.It Dv AUDIO_GETINFO (audio_info_t) 261.It Dv AUDIO_SETINFO (audio_info_t) 262Get or set audio information as encoded in the audio_info structure. 263.Bd -literal 264typedef struct audio_info { 265 struct audio_prinfo play; /* info for play (output) side */ 266 struct audio_prinfo record; /* info for record (input) side */ 267 u_int monitor_gain; 268 /* BSD extensions */ 269 u_int blocksize; /* H/W read/write block size */ 270 u_int hiwat; /* output high water mark */ 271 u_int lowat; /* output low water mark */ 272 u_int _ispare1; 273 u_int mode; /* current device mode */ 274#define AUMODE_PLAY 0x01 275#define AUMODE_RECORD 0x02 276#define AUMODE_PLAY_ALL 0x04 /* do not do real-time correction */ 277}; 278.Ed 279.Pp 280When setting the current state with 281.Dv AUDIO_SETINFO , 282the audio_info structure should first be initialized with 283.Li Dv AUDIO_INITINFO Po &info Pc 284and then the particular values to be changed should be set. 285This allows the audio driver to only set those things that you wish 286to change and eliminates the need to query the device with 287.Dv AUDIO_GETINFO 288first. 289.Pp 290The 291.Va mode 292field should be set to 293.Dv AUMODE_PLAY , 294.Dv AUMODE_RECORD , 295.Dv AUMODE_PLAY_ALL , 296or a bitwise OR combination of the three. 297Only full-duplex audio devices support 298simultaneous record and playback. 299.Pp 300.Va hiwat 301and 302.Va lowat 303are used to control write behavior. 304Writes to the audio devices will queue up blocks until the high-water 305mark is reached, at which point any more write calls will block 306until the queue is drained to the low-water mark. 307.Va hiwat 308and 309.Va lowat 310set those high- and low-water marks (in audio blocks). 311The default for 312.Va hiwat 313is the maximum value and for 314.Va lowat 31575 % of 316.Va hiwat . 317.Pp 318.Va blocksize 319sets the current audio blocksize. 320The generic audio driver layer and the hardware driver have the 321opportunity to adjust this block size to get it within 322implementation-required limits. 323Upon return from an 324.Dv AUDIO_SETINFO 325call, the actual blocksize set is returned in this field. 326Normally the 327.Va blocksize 328is calculated to correspond to 50ms of sound and it is recalculated 329when the encoding parameter changes, but if the 330.Va blocksize 331is set explicitly this value becomes sticky, i.e., it is remains 332even when the encoding is changed. 333The stickiness can be cleared by reopening the device or setting the 334.Va blocksize 335to 0. 336.Bd -literal 337struct audio_prinfo { 338 u_int sample_rate; /* sample rate in samples/s */ 339 u_int channels; /* number of channels, usually 1 or 2 */ 340 u_int precision; /* number of bits/sample */ 341 u_int encoding; /* data encoding (AUDIO_ENCODING_* above) */ 342 u_int gain; /* volume level */ 343 u_int port; /* selected I/O port */ 344 u_long seek; /* BSD extension */ 345 u_int avail_ports; /* available I/O ports */ 346 u_int buffer_size; /* total size audio buffer */ 347 u_int _ispare[1]; 348 /* Current state of device: */ 349 u_int samples; /* number of samples */ 350 u_int eof; /* End Of File (zero-size writes) counter */ 351 u_char pause; /* non-zero if paused, zero to resume */ 352 u_char error; /* non-zero if underflow/overflow occurred */ 353 u_char waiting; /* non-zero if another process hangs in open */ 354 u_char balance; /* stereo channel balance */ 355 u_char cspare[2]; 356 u_char open; /* non-zero if currently open */ 357 u_char active; /* non-zero if I/O is currently active */ 358}; 359.Ed 360.Pp 361Note: many hardware audio drivers require identical playback and 362recording sample rates, sample encodings, and channel counts. 363The playing information is always set last and will prevail on such hardware. 364If the hardware can handle different settings the 365.Dv AUDIO_PROP_INDEPENDENT 366property is set. 367.Pp 368The encoding parameter can have the following values: 369.Bl -tag -width indent -compact 370.It Dv AUDIO_ENCODING_ULAW 371mulaw encoding, 8 bits/sample 372.It Dv AUDIO_ENCODING_ALAW 373alaw encoding, 8 bits/sample 374.It Dv AUDIO_ENCODING_SLINEAR 375two's complement signed linear encoding with the platform byte order 376.It Dv AUDIO_ENCODING_ULINEAR 377unsigned linear encoding with the platform byte order 378.It Dv AUDIO_ENCODING_ADPCM 379ADPCM encoding, 8 bits/sample 380.It Dv AUDIO_ENCODING_SLINEAR_LE 381two's complement signed linear encoding with little endian byte order 382.It Dv AUDIO_ENCODING_SLINEAR_BE 383two's complement signed linear encoding with big endian byte order 384.It Dv AUDIO_ENCODING_ULINEAR_LE 385unsigned linear encoding with little endian byte order 386.It Dv AUDIO_ENCODING_ULINEAR_BE 387unsigned linear encoding with big endian byte order 388.El 389.Pp 390The 391.Va gain , 392.Va port 393and 394.Va balance 395settings provide simple shortcuts to the richer mixer 396interface described below. 397The gain should be in the range 398.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN 399and the balance in the range 400.Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE 401with the normal setting at 402.Dv AUDIO_MID_BALANCE . 403.br 404The input port should be a combination of 405.Bl -tag -width indent -compact 406.It Dv AUDIO_MICROPHONE 407to select microphone input. 408.It Dv AUDIO_LINE_IN 409to select line input. 410.It Dv AUDIO_CD 411to select CD input. 412.El 413The output port should be a combination of 414.Bl -tag -width indent -compact 415.It Dv AUDIO_SPEAKER 416to select microphone output. 417.It Dv AUDIO_HEADPHONE 418to select headphone output. 419.It Dv AUDIO_LINE_OUT 420to select line output. 421.El 422The available ports can be found in 423.Va avail_ports . 424.Pp 425.Va buffer_size 426is the total size of the audio buffer. 427The buffer size divided by the 428.Va blocksize 429gives the maximum value for 430.Va hiwat . 431Currently the 432.Va buffer_size 433can only be read and not set. 434.Pp 435The 436.Va seek 437and 438.Va samples 439fields are only used for 440.Dv AUDIO_GETINFO . 441.Va seek 442represents the count of 443samples pending; 444.Va samples 445represents the total number of bytes recorded or played, less those 446that were dropped due to inadequate consumption/production rates. 447.Pp 448.Va pause 449returns the current pause/unpause state for recording or playback. 450For 451.Dv AUDIO_SETINFO , 452if the pause value is specified it will either pause 453or unpause the particular direction. 454.El 455.Sh MIXER DEVICE 456The mixer device, 457.Pa /dev/mixer , 458may be manipulated with 459.Xr ioctl 2 460but does not support 461.Xr read 2 462or 463.Xr write 2 . 464It supports the following 465.Xr ioctl 2 466commands: 467.Bl -tag -width indent -compact 468.It Dv AUDIO_GETDEV (audio_device_t) 469This command is the same as described above for the sampling devices. 470.It Dv AUDIO_MIXER_READ (mixer_ctrl_t) 471.It Dv AUDIO_MIXER_WRITE (mixer_ctrl_t) 472.Bd -literal 473#define AUDIO_MIXER_CLASS 0 474#define AUDIO_MIXER_ENUM 1 475#define AUDIO_MIXER_SET 2 476#define AUDIO_MIXER_VALUE 3 477typedef struct mixer_ctrl { 478 int dev; /* input: nth device */ 479 int type; 480 union { 481 int ord; /* enum */ 482 int mask; /* set */ 483 mixer_level_t value; /* value */ 484 } un; 485} mixer_ctrl_t; 486.Ed 487.Bd -literal 488#define AUDIO_MIN_GAIN 0 489#define AUDIO_MAX_GAIN 255 490typedef struct mixer_level { 491 int num_channels; 492 u_char level[8]; /* [num_channels] */ 493} mixer_level_t; 494#define AUDIO_MIXER_LEVEL_MONO 0 495#define AUDIO_MIXER_LEVEL_LEFT 0 496#define AUDIO_MIXER_LEVEL_RIGHT 1 497 498.Ed 499These commands read the current mixer state or set new mixer state for 500the specified device 501.Va dev . 502.Va type 503identifies which type of value is supplied in the 504.Va mixer_ctrl_t 505argument. 506For a mixer value, the 507.Va value 508field specifies both the number of channels and the values for each of 509the channels. 510If the channel count does not match the current channel count, the 511attempt to change the setting may fail (depending on the hardware 512device driver implementation). 513For an enumeration value, the 514.Va ord 515field should be set to one of the possible values as returned by a prior 516.Dv AUDIO_MIXER_DEVINFO 517command. 518The type 519.Dv AUDIO_MIXER_CLASS 520is only used for classifying particular mixer device 521types and is not used for 522.Dv AUDIO_MIXER_READ 523or 524.Dv AUDIO_MIXER_WRITE . 525.It Dv AUDIO_MIXER_DEVINFO (mixer_devinfo_t) 526This command is used iteratively to fetch audio mixer device information 527into the input/output mixer_devinfo_t argument. 528To query all the supported encodings, start with an index field of 5290 and continue with successive encodings (1, 2, ...) until the 530command returns an error. 531.Bd -literal 532typedef struct mixer_devinfo { 533 int index; /* input: nth mixer device */ 534 audio_mixer_name_t label; 535 int type; 536 int mixer_class; 537 int next, prev; 538#define AUDIO_MIXER_LAST -1 539 union { 540 struct audio_mixer_enum { 541 int num_mem; 542 struct { 543 audio_mixer_name_t label; 544 int ord; 545 } member[32]; 546 } e; 547 struct audio_mixer_set { 548 int num_mem; 549 struct { 550 audio_mixer_name_t label; 551 int mask; 552 } member[32]; 553 } s; 554 struct audio_mixer_value { 555 audio_mixer_name_t units; 556 int num_channels; 557 } v; 558 } un; 559} mixer_devinfo_t; 560.Ed 561The 562.Va label 563field identifies the name of this particular mixer control. 564The 565.Va index 566field may be used as the 567.Va dev 568field in 569.Dv AUDIO_MIXER_READ 570and 571.Dv AUDIO_MIXER_WRITE 572commands. 573The 574.Va type 575field identifies the type of this mixer control. 576Enumeration types are typically used for on/off style controls (e.g., a 577mute control) or for input/output device selection (e.g., select 578recording input source from CD, line in, or microphone). 579Set types are similar to enumeration types but any combination 580of the mask bits can be used. 581.Pp 582The 583.Va mixer_class 584field identifies what class of control this is. 585This value is set to the index value used to query the class itself. 586For example, a mixer level controlling the input gain on the ``line 587in'' circuit would be a class that matches an input class device 588with the name ``Inputs'' (AudioCInputs). 589Mixer controls which control audio circuitry for a particular audio 590source (e.g., line-in, CD in, DAC output) are collected under the input class, 591while those which control all audio sources (e.g., master volume, 592equalization controls) are under the output class. 593.Pp 594The 595.Va next 596and 597.Va prev 598may be used by the hardware device driver to provide hints for the next 599and previous devices in a related set (for example, the line in level 600control would have the line in mute as its "next" value). 601If there is no relevant next or previous value, 602.Dv AUDIO_MIXER_LAST 603is specified. 604.Pp 605For 606.Dv AUDIO_MIXER_ENUM 607mixer control types, 608the enumeration values and their corresponding names are filled in. 609For example, a mute control would return appropriate values paired with 610AudioNon and AudioNoff. 611For 612.Dv AUDIO_MIXER_VALUE 613and 614.Dv AUDIO_MIXER_SET 615mixer control types, the channel count is 616returned; the units name specifies what the level controls (typical 617values are AudioNvolume, AudioNtreble, AudioNbass). 618.\" For AUDIO_MIXER_SET mixer control types, what is what? 619.El 620.Pp 621By convention, all the mixer device can be distinguished from other 622mixer controls because they use a name from one of the AudioC* string values. 623.Sh FILES 624.Bl -tag -width /dev/audioctl -compact 625.It Pa /dev/audio 626.It Pa /dev/audioctl 627.It Pa /dev/sound 628.It Pa /dev/mixer 629.El 630.Sh SEE ALSO 631.Xr audioctl 1 , 632.Xr mixerctl 1 , 633.Xr ioctl 2 , 634.Xr ossaudio 3 , 635.Xr ac97 4 , 636.Xr audio 9 637.Pp 638For ports using the ISA bus: 639.Xr gus 4 , 640.Xr pas 4 , 641.Xr pss 4 , 642.Xr sb 4 , 643.Xr wss 4 . 644.Pp 645For ports using the PCI bus: 646.Xr auich 4 , 647.Xr clcs 4 , 648.Xr clct 4 , 649.Xr cmpci 4 , 650.Xr eap 4 , 651.Xr eso 4 , 652.Xr maestro 4 , 653.Xr neo 4 , 654.Xr sv 4 . 655.Sh BUGS 656Some of the device-specific manual pages do not yet exist. 657.br 658If the device is used in 659.Xr mmap 2 660it is currently always mapped for writing (playing) due to 661VM system weirdness. 662