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