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