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