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