1.\" $NetBSD: audio.4,v 1.65 2006/03/28 21:43:06 wiz 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 FOUNDATION OR CONTRIBUTORS 29.\" BE 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 28, 2006 38.Dt AUDIO 4 39.Os 40.Sh NAME 41.Nm audio 42.Nd device-independent audio driver layer 43.Sh SYNOPSIS 44.In sys/audioio.h 45.Sh DESCRIPTION 46The 47.Nm 48driver provides support for various audio peripherals. 49It provides a uniform programming interface layer above different 50underlying audio hardware drivers. 51The audio layer provides full-duplex operation if the 52underlying hardware configuration supports it. 53.Pp 54There are four device files available for audio operation: 55.Pa /dev/audio , 56.Pa /dev/sound , 57.Pa /dev/audioctl , 58and 59.Pa /dev/mixer . 60.Pp 61.Pa /dev/audio 62and 63.Pa /dev/sound 64are used for recording or playback of digital samples. 65.Pp 66.Pa /dev/mixer 67is used to manipulate volume, recording source, or other audio mixer 68functions. 69.Pp 70.Pa /dev/audioctl 71accepts the same 72.Xr ioctl 2 73operations as 74.Pa /dev/sound , 75but no other operations. 76.Pp 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 mu-law 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. 112.Pp 113On a full-duplex device, reads and writes may operate 114concurrently without interference. 115If a full-duplex capable audio device is opened for both reading and writing 116it will start in half-duplex play mode; full-duplex mode has to be set 117explicitly. 118.Pp 119On either type of device, if the playback mode is paused then silence is 120played instead of the provided samples, and if recording is paused then 121the process blocks in 122.Xr read 2 123until recording is unpaused. 124.Pp 125If a writing process does not call 126.Xr write 2 127frequently enough to provide samples at the pace the hardware 128consumes them silence is inserted. 129If the 130.Dv AUMODE_PLAY_ALL 131mode is not set the writing process must 132provide enough data via 133subsequent write calls to 134.Dq catch up 135in time to the current audio 136block before any more process-provided samples will be played. 137If a reading process does not call 138.Xr read 2 139frequently enough, it will simply miss samples. 140.Pp 141The audio device is normally accessed with 142.Xr read 2 143or 144.Xr write 2 145calls, but it can also be mapped into user memory with 146.Xr mmap 2 147(when supported by the device). 148Once the device has been mapped it can no longer be accessed 149by read or write; all access is by reading and writing to 150the mapped memory. 151The device appears as a block of memory 152of size 153.Va buffersize 154(as available via 155.Dv AUDIO_GETINFO ) . 156The device driver will continuously move data from this buffer 157from/to the audio hardware, wrapping around at the end of the buffer. 158To find out where the hardware is currently accessing data in the buffer the 159.Dv AUDIO_GETIOFFS 160and 161.Dv AUDIO_GETOOFFS 162calls can be used. 163The playing and recording buffers are distinct and must be 164mapped separately if both are to be used. 165Only encodings that are not emulated (i.e. where 166.Dv AUDIO_ENCODINGFLAG_EMULATED 167is not set) work properly for a mapped device. 168.Pp 169The audio device, like most devices, can be used in 170.Va select , 171can be set in non-blocking mode and can be set (with a 172.Dv FIOASYNC 173ioctl) to send a 174.Dv SIGIO 175when I/O is possible. 176The mixer device can be set to generate a 177.Dv SIGIO 178whenever a mixer value is changed. 179.Pp 180The following 181.Xr ioctl 2 182commands are supported on the sample devices: 183.Pp 184.Bl -tag -width indent 185.It Dv AUDIO_FLUSH 186This command stops all playback and recording, clears all queued 187buffers, resets error counters, and restarts recording and playback as 188appropriate for the current sampling mode. 189.It Dv AUDIO_RERROR (int) 190This command fetches the count of dropped input samples into its integer 191argument. 192There is no information regarding when in the sample stream 193they were dropped. 194.It Dv AUDIO_WSEEK (int) 195This command fetches the count of samples that are queued ahead of the 196first sample in the most recent sample block written into its integer argument. 197.It Dv AUDIO_DRAIN 198This command suspends the calling process until all queued playback 199samples have been played by the hardware. 200.It Dv AUDIO_GETDEV (audio_device_t) 201This command fetches the current hardware device information into the 202audio_device_t argument. 203.Bd -literal 204typedef struct audio_device { 205 char name[MAX_AUDIO_DEV_LEN]; 206 char version[MAX_AUDIO_DEV_LEN]; 207 char config[MAX_AUDIO_DEV_LEN]; 208} audio_device_t; 209.Ed 210.It Dv AUDIO_GETFD (int) 211The command returns the current setting of the full duplex mode. 212.It Dv AUDIO_GETENC (audio_encoding_t) 213This command is used iteratively to fetch sample encoding names and 214format_ids into the input/output audio_encoding_t argument. 215.Bd -literal 216typedef struct audio_encoding { 217 int index; /* input: nth encoding */ 218 char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */ 219 int encoding; /* value for encoding parameter */ 220 int precision; /* value for precision parameter */ 221 int flags; 222#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 223} audio_encoding_t; 224.Ed 225.Pp 226To query 227all the supported encodings, start with an index field of 0 and 228continue with successive encodings (1, 2, ...) until the command returns 229an error. 230.It Dv AUDIO_SETFD (int) 231This command sets the device into full-duplex operation if its integer 232argument has a non-zero value, or into half-duplex operation if it 233contains a zero value. 234If the device does not support full-duplex 235operation, attempting to set full-duplex mode returns an error. 236.It Dv AUDIO_GETPROPS (int) 237This command gets a bit set of hardware properties. 238If the hardware 239has a certain property the corresponding bit is set, otherwise it is not. 240The properties can have the following values: 241.Pp 242.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact 243.It Dv AUDIO_PROP_FULLDUPLEX 244the device admits full duplex operation. 245.It Dv AUDIO_PROP_MMAP 246the device can be used with 247.Xr mmap 2 . 248.It Dv AUDIO_PROP_INDEPENDENT 249the device can set the playing and recording encoding parameters 250independently. 251.El 252.It Dv AUDIO_GETIOFFS (audio_offset_t) 253.It Dv AUDIO_GETOOFFS (audio_offset_t) 254This command fetches the current offset in the input(output) buffer where 255the audio hardware's DMA engine will be putting(getting) data. 256It mostly useful when the device 257buffer is available in user space via the 258.Xr mmap 2 259call. 260The information is returned in the audio_offset structure. 261.Bd -literal 262typedef struct audio_offset { 263 u_int samples; /* Total number of bytes transferred */ 264 u_int deltablks; /* Blocks transferred since last checked */ 265 u_int offset; /* Physical transfer offset in buffer */ 266} audio_offset_t; 267.Ed 268.It Dv AUDIO_GETINFO (audio_info_t) 269.It Dv AUDIO_SETINFO (audio_info_t) 270Get or set audio information as encoded in the audio_info structure. 271.Bd -literal 272typedef struct audio_info { 273 struct audio_prinfo play; /* info for play (output) side */ 274 struct audio_prinfo record; /* info for record (input) side */ 275 u_int monitor_gain; /* input to output mix */ 276 /* BSD extensions */ 277 u_int blocksize; /* H/W read/write block size */ 278 u_int hiwat; /* output high water mark */ 279 u_int lowat; /* output low water mark */ 280 u_int _ispare1; 281 u_int mode; /* current device mode */ 282#define AUMODE_PLAY 0x01 283#define AUMODE_RECORD 0x02 284#define AUMODE_PLAY_ALL 0x04 /* do not do real-time correction */ 285} audio_info_t; 286.Ed 287.Pp 288When setting the current state with 289.Dv AUDIO_SETINFO , 290the audio_info structure should first be initialized with 291.Dv AUDIO_INITINFO Po \*[Am]info Pc 292and then the particular values to be changed should be set. 293This allows the audio driver to only set those things that you wish 294to change and eliminates the need to query the device with 295.Dv AUDIO_GETINFO 296first. 297.Pp 298The 299.Va mode 300field should be set to 301.Dv AUMODE_PLAY , 302.Dv AUMODE_RECORD , 303.Dv AUMODE_PLAY_ALL , 304or a bitwise OR combination of the three. 305Only full-duplex audio devices support 306simultaneous record and playback. 307.Pp 308.Va hiwat 309and 310.Va lowat 311are used to control write behavior. 312Writes to the audio devices will queue up blocks until the high-water 313mark is reached, at which point any more write calls will block 314until the queue is drained to the low-water mark. 315.Va hiwat 316and 317.Va lowat 318set those high- and low-water marks (in audio blocks). 319The default for 320.Va hiwat 321is the maximum value and for 322.Va lowat 32375 % of 324.Va hiwat . 325.Pp 326.Va blocksize 327sets the current audio blocksize. 328The generic audio driver layer and the hardware driver have the 329opportunity to adjust this block size to get it within 330implementation-required limits. 331Upon return from an 332.Dv AUDIO_SETINFO 333call, the actual blocksize set is returned in this field. 334Normally the 335.Va blocksize 336is calculated to correspond to 50ms of sound and it is recalculated 337when the encoding parameter changes, but if the 338.Va blocksize 339is set explicitly this value becomes sticky, i.e., it remains 340even when the encoding is changed. 341The stickiness can be cleared by reopening the device or setting the 342.Va blocksize 343to 0. 344.Bd -literal 345struct audio_prinfo { 346 u_int sample_rate; /* sample rate in samples/s */ 347 u_int channels; /* number of channels, usually 1 or 2 */ 348 u_int precision; /* number of bits/sample */ 349 u_int encoding; /* data encoding (AUDIO_ENCODING_* below) */ 350 u_int gain; /* volume level */ 351 u_int port; /* selected I/O port */ 352 u_long seek; /* BSD extension */ 353 u_int avail_ports; /* available I/O ports */ 354 u_int buffer_size; /* total size audio buffer */ 355 u_int _ispare[1]; 356 /* Current state of device: */ 357 u_int samples; /* number of samples */ 358 u_int eof; /* End Of File (zero-size writes) counter */ 359 u_char pause; /* non-zero if paused, zero to resume */ 360 u_char error; /* non-zero if underflow/overflow occurred */ 361 u_char waiting; /* non-zero if another process hangs in open */ 362 u_char balance; /* stereo channel balance */ 363 u_char cspare[2]; 364 u_char open; /* non-zero if currently open */ 365 u_char active; /* non-zero if I/O is currently active */ 366}; 367.Ed 368.Pp 369Note: many hardware audio drivers require identical playback and 370recording sample rates, sample encodings, and channel counts. 371The playing information is always set last and will prevail on such hardware. 372If the hardware can handle different settings the 373.Dv AUDIO_PROP_INDEPENDENT 374property is set. 375.Pp 376The encoding parameter can have the following values: 377.Pp 378.Bl -tag -width AUDIO_ENCODING_SLINEAR_BE -compact 379.It Dv AUDIO_ENCODING_ULAW 380mu-law encoding, 8 bits/sample 381.It Dv AUDIO_ENCODING_ALAW 382A-law encoding, 8 bits/sample 383.It Dv AUDIO_ENCODING_SLINEAR 384two's complement signed linear encoding with the platform byte order 385.It Dv AUDIO_ENCODING_ULINEAR 386unsigned linear encoding with the platform byte order 387.It Dv AUDIO_ENCODING_ADPCM 388ADPCM encoding, 8 bits/sample 389.It Dv AUDIO_ENCODING_SLINEAR_LE 390two's complement signed linear encoding with little endian byte order 391.It Dv AUDIO_ENCODING_SLINEAR_BE 392two's complement signed linear encoding with big endian byte order 393.It Dv AUDIO_ENCODING_ULINEAR_LE 394unsigned linear encoding with little endian byte order 395.It Dv AUDIO_ENCODING_ULINEAR_BE 396unsigned linear encoding with big endian byte order 397.El 398.Pp 399The 400.Va gain , 401.Va port 402and 403.Va balance 404settings provide simple shortcuts to the richer mixer 405interface described below. 406The gain should be in the range 407.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN 408and the balance in the range 409.Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE 410with the normal setting at 411.Dv AUDIO_MID_BALANCE . 412.Pp 413The input port should be a combination of: 414.Pp 415.Bl -tag -width AUDIO_MICROPHONE -compact 416.It Dv AUDIO_MICROPHONE 417to select microphone input. 418.It Dv AUDIO_LINE_IN 419to select line input. 420.It Dv AUDIO_CD 421to select CD input. 422.El 423.Pp 424The output port should be a combination of: 425.Pp 426.Bl -tag -width AUDIO_HEADPHONE -compact 427.It Dv AUDIO_SPEAKER 428to select speaker output. 429.It Dv AUDIO_HEADPHONE 430to select headphone output. 431.It Dv AUDIO_LINE_OUT 432to select line output. 433.El 434.Pp 435The available ports can be found in 436.Va avail_ports . 437.Pp 438.Va buffer_size 439is the total size of the audio buffer. 440The buffer size divided by the 441.Va blocksize 442gives the maximum value for 443.Va hiwat . 444Currently the 445.Va buffer_size 446can only be read and not set. 447.Pp 448The 449.Va seek 450and 451.Va samples 452fields are only used for 453.Dv AUDIO_GETINFO . 454.Va seek 455represents the count of 456samples pending; 457.Va samples 458represents the total number of bytes recorded or played, less those 459that were dropped due to inadequate consumption/production rates. 460.Pp 461.Va pause 462returns the current pause/unpause state for recording or playback. 463For 464.Dv AUDIO_SETINFO , 465if the pause value is specified it will either pause 466or unpause the particular direction. 467.El 468.Sh MIXER DEVICE 469The mixer device, 470.Pa /dev/mixer , 471may be manipulated with 472.Xr ioctl 2 473but does not support 474.Xr read 2 475or 476.Xr write 2 . 477It supports the following 478.Xr ioctl 2 479commands: 480.Bl -tag -width indent 481.It Dv AUDIO_GETDEV (audio_device_t) 482This command is the same as described above for the sampling devices. 483.It Dv AUDIO_MIXER_READ (mixer_ctrl_t) 484.It Dv AUDIO_MIXER_WRITE (mixer_ctrl_t) 485These commands read the current mixer state or set new mixer state for 486the specified device 487.Va dev . 488.Va type 489identifies which type of value is supplied in the 490.Va mixer_ctrl_t 491argument. 492.Bd -literal 493#define AUDIO_MIXER_CLASS 0 494#define AUDIO_MIXER_ENUM 1 495#define AUDIO_MIXER_SET 2 496#define AUDIO_MIXER_VALUE 3 497typedef struct mixer_ctrl { 498 int dev; /* input: nth device */ 499 int type; 500 union { 501 int ord; /* enum */ 502 int mask; /* set */ 503 mixer_level_t value; /* value */ 504 } un; 505} mixer_ctrl_t; 506 507#define AUDIO_MIN_GAIN 0 508#define AUDIO_MAX_GAIN 255 509typedef struct mixer_level { 510 int num_channels; 511 u_char level[8]; /* [num_channels] */ 512} mixer_level_t; 513#define AUDIO_MIXER_LEVEL_MONO 0 514#define AUDIO_MIXER_LEVEL_LEFT 0 515#define AUDIO_MIXER_LEVEL_RIGHT 1 516.Ed 517.Pp 518For a mixer value, the 519.Va value 520field specifies both the number of channels and the values for each 521channel. 522If the channel count does not match the current channel count, the 523attempt to change the setting may fail (depending on the hardware 524device driver implementation). 525For an enumeration value, the 526.Va ord 527field should be set to one of the possible values as returned by a prior 528.Dv AUDIO_MIXER_DEVINFO 529command. 530The type 531.Dv AUDIO_MIXER_CLASS 532is only used for classifying particular mixer device 533types and is not used for 534.Dv AUDIO_MIXER_READ 535or 536.Dv AUDIO_MIXER_WRITE . 537.It Dv AUDIO_MIXER_DEVINFO (mixer_devinfo_t) 538This command is used iteratively to fetch audio mixer device information 539into the input/output mixer_devinfo_t argument. 540To query all the supported devices, start with an index field of 5410 and continue with successive devices (1, 2, ...) until the 542command returns an error. 543.Bd -literal 544typedef struct mixer_devinfo { 545 int index; /* input: nth mixer device */ 546 audio_mixer_name_t label; 547 int type; 548 int mixer_class; 549 int next, prev; 550#define AUDIO_MIXER_LAST -1 551 union { 552 struct audio_mixer_enum { 553 int num_mem; 554 struct { 555 audio_mixer_name_t label; 556 int ord; 557 } member[32]; 558 } e; 559 struct audio_mixer_set { 560 int num_mem; 561 struct { 562 audio_mixer_name_t label; 563 int mask; 564 } member[32]; 565 } s; 566 struct audio_mixer_value { 567 audio_mixer_name_t units; 568 int num_channels; 569 int delta; 570 } v; 571 } un; 572} mixer_devinfo_t; 573.Ed 574.Pp 575The 576.Va label 577field identifies the name of this particular mixer control. 578The 579.Va index 580field may be used as the 581.Va dev 582field in 583.Dv AUDIO_MIXER_READ 584and 585.Dv AUDIO_MIXER_WRITE 586commands. 587The 588.Va type 589field identifies the type of this mixer control. 590Enumeration types are typically used for on/off style controls (e.g. a 591mute control) or for input/output device selection (e.g. select 592recording input source from CD, line in, or microphone). 593Set types are similar to enumeration types but any combination 594of the mask bits can be used. 595.Pp 596The 597.Va mixer_class 598field identifies what class of control this is. 599The 600.Pq arbitrary 601value set by the hardware driver may be determined by examining the 602.Va mixer_class 603field of the class itself, 604a mixer of type 605.Dv AUDIO_MIXER_CLASS . 606For example, a mixer controlling the input gain on the line in circuit 607would have a 608.Va mixer_class 609that matches an input class device with the name 610.Dq inputs 611.Dv ( AudioCinputs ) , 612and would have a 613.Va label 614of 615.Dq line 616.Dv ( AudioNline ) . 617Mixer controls which control audio circuitry for a particular audio 618source (e.g. line-in, CD in, DAC output) are collected under the input class, 619while those which control all audio sources (e.g. master volume, 620equalization controls) are under the output class. 621Hardware devices capable of recording typically also have a record class, 622for controls that only affect recording, 623and also a monitor class. 624.Pp 625The 626.Va next 627and 628.Va prev 629may be used by the hardware device driver to provide hints for the next 630and previous devices in a related set (for example, the line in level 631control would have the line in mute as its 632.Dq next 633value). 634If there is no relevant next or previous value, 635.Dv AUDIO_MIXER_LAST 636is specified. 637.Pp 638For 639.Dv AUDIO_MIXER_ENUM 640mixer control types, 641the enumeration values and their corresponding names are filled in. 642For example, a mute control would return appropriate values paired with 643.Dv AudioNon 644and 645.Dv AudioNoff . 646For 647.Dv AUDIO_MIXER_VALUE 648and 649.Dv AUDIO_MIXER_SET 650mixer control types, the channel count is 651returned; the units name specifies what the level controls (typical 652values are 653.Dv AudioNvolume , 654.Dv AudioNtreble , 655.Dv AudioNbass ) . 656.\" For AUDIO_MIXER_SET mixer control types, what is what? 657.El 658.Pp 659By convention, all the mixer devices can be distinguished from other 660mixer controls because they use a name from one of the 661.Dv AudioC* 662string values. 663.Sh FILES 664.Bl -tag -width /dev/audioctl -compact 665.It Pa /dev/audio 666.It Pa /dev/audioctl 667.It Pa /dev/sound 668.It Pa /dev/mixer 669.El 670.Sh SEE ALSO 671.Xr audioctl 1 , 672.Xr mixerctl 1 , 673.Xr ioctl 2 , 674.Xr ossaudio 3 , 675.Xr midi 4 , 676.Xr radio 4 677.Ss ISA bus 678.Xr aria 4 , 679.Xr ess 4 , 680.Xr gus 4 , 681.Xr guspnp 4 , 682.Xr pas 4 , 683.Xr sb 4 , 684.Xr wss 4 , 685.Xr ym 4 686.Ss PCI bus 687.Xr auacer 4 , 688.Xr auich 4 , 689.Xr auixp 4 , 690.Xr autri 4 , 691.Xr auvia 4 , 692.Xr azalia 4 , 693.Xr clcs 4 , 694.Xr clct 4 , 695.Xr cmpci 4 , 696.Xr eap 4 , 697.Xr emuxki 4 , 698.Xr esa 4 , 699.Xr esm 4 , 700.Xr eso 4 , 701.Xr fms 4 , 702.Xr neo 4 , 703.Xr sv 4 , 704.Xr yds 4 705.Ss PCMCIA 706.Xr esl 4 707.Ss TURBOchannel 708.Xr bba 4 709.Ss USB 710.Xr uaudio 4 711.Sh BUGS 712If the device is used in 713.Xr mmap 2 714it is currently always mapped for writing (playing) due to 715VM system weirdness. 716