1.\" $OpenBSD: audio.9,v 1.35 2023/10/15 15:49:47 chrisz Exp $ 2.\" $NetBSD: audio.9,v 1.14 2000/02/11 22:56:15 kleink Exp $ 3.\" 4.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Lennart Augustsson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: October 15 2023 $ 32.Dt AUDIO 9 33.Os 34.Sh NAME 35.Nm audio 36.Nd interface between low and high level audio drivers 37.Sh DESCRIPTION 38The audio device driver is divided into a high level, 39hardware independent layer, and a low level, hardware 40dependent layer. 41The interface between these is the 42.Va audio_hw_if 43structure. 44.Bd -literal 45struct audio_hw_if { 46 int (*open)(void *, int); 47 void (*close)(void *); 48 int (*set_params)(void *, int, int, 49 struct audio_params *, struct audio_params *); 50 int (*round_blocksize)(void *, int); 51 52 int (*commit_settings)(void *); 53 54 int (*init_output)(void *, void *, int); 55 int (*init_input)(void *, void *, int); 56 int (*start_output)(void *, void *, int, 57 void (*)(void *), void *); 58 int (*start_input)(void *, void *, int, 59 void (*)(void *), void *); 60 int (*halt_output)(void *); 61 int (*halt_input)(void *); 62 63 int (*set_port)(void *, struct mixer_ctrl *); 64 int (*get_port)(void *, struct mixer_ctrl *); 65 66 int (*query_devinfo)(void *, struct mixer_devinfo *); 67 68 void *(*allocm)(void *, int, size_t, int, int); 69 void (*freem)(void *, void *, int); 70 size_t (*round_buffersize)(void *, int, size_t); 71 72 int (*trigger_output)(void *, void *, void *, int, 73 void (*)(void *), void *, struct audio_params *); 74 int (*trigger_input)(void *, void *, void *, int, 75 void (*)(void *), void *, struct audio_params *); 76 void (*copy_output)(void *hdl, size_t bytes); 77 void (*underrun)(void *hdl); 78 int (*set_blksz)(void *, int, 79 struct audio_params *, struct audio_params *, int); 80 int (*set_nblks)(void *, int, int, 81 struct audio_params *, int); 82}; 83 84struct audio_params { 85 u_long sample_rate; /* sample rate */ 86 u_int encoding; /* mu-law, linear, etc */ 87 u_int precision; /* bits/sample */ 88 u_int bps; /* bytes/sample */ 89 u_int msb; /* data alignment */ 90 u_int channels; /* mono(1), stereo(2) */ 91}; 92.Ed 93.Pp 94The high level audio driver attaches to the low level driver 95when the latter calls 96.Fn audio_attach_mi . 97This call is: 98.Bd -literal -offset indent 99struct device * 100audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl, 101 struct device *dev); 102.Ed 103.Pp 104The 105.Va audio_hw_if 106struct is as shown above. 107The 108.Fa hdl 109argument is a handle to some low level data structure. 110It is sent as the first argument to all the functions in 111.Fa ahwp 112when the high level driver calls them. 113.Fa dev 114is the device struct for the hardware device. 115.Pp 116The upper layer of the audio driver allocates one buffer for playing 117and one for recording. 118It handles the buffering of data from the user processes in these. 119The data is presented to the lower level in smaller chunks, called blocks. 120During playback, if there is no data available from the user process 121when the hardware requests another block, a block of silence will be 122used instead. 123Similarly, if the user process does not read data quickly enough during 124recording, data will be thrown away. 125.Pp 126The fields of 127.Va audio_hw_if 128are described in some more detail below. 129Some fields are optional and can be set to 130.Dv NULL 131if not needed. 132.Bl -tag -width indent 133.It Ft int Fn (*open) "void *hdl" "int flags" 134This function is called when the audio device is opened, with 135.Fa flags 136the kernel representation of flags passed to the 137.Xr open 2 138system call 139.Po 140see 141.Dv OFLAGS 142and 143.Dv FFLAGS 144in 145.In sys/fcntl.h 146.Pc . 147It initializes the hardware for I/O. 148Every successful call to 149.Fn open 150is matched by a call to 151.Fn close . 152This function returns 0 on success, otherwise an error code. 153.It Ft void Fn (*close) "void *hdl" 154This function is called when the audio device is closed. 155.It Ft int Fn (*set_params) "void *hdl" "int setmode" "int usemode" \ 156"struct audio_params *play" "struct audio_params *rec" 157This function is called to set the audio encoding mode. 158.Fa setmode 159is a combination of the 160.Dv AUMODE_RECORD 161and 162.Dv AUMODE_PLAY 163flags to indicate which mode(s) are to be set. 164.Fa usemode 165is also a combination of these flags, but indicates the current 166mode of the device (i.e., the value corresponding to the 167.Va flags 168argument to the 169.Fn open 170function). 171The 172.Fa play 173and 174.Fa rec 175structures contain the encoding parameters that will be set. 176The values of the structures must also be modified if the hardware 177cannot be set to exactly the requested mode (e.g., if the requested 178sampling rate is not supported, but one close enough is). 179Except the channel count, the same value is passed in both 180.Fa play 181and 182.Fa rec . 183.Pp 184The machine independent audio driver does some preliminary parameter checking; 185it verifies that the precision is compatible with the encoding, 186and it translates 187.Dv AUDIO_ENCODING_[US]LINEAR 188to 189.Dv AUDIO_ENCODING_[US]LINEAR_{LE,BE} . 190.Pp 191This function returns 0 on success, otherwise an error code. 192.It Ft int Fn (*round_blocksize) "void *hdl" "int bs" 193This function is optional. 194If supplied, it is called with the block size, 195.Fa bs , 196which has been computed by the upper layer. 197It returns a block size, possibly changed according to the needs of the 198hardware driver. 199.It Ft int Fn (*commit_settings) "void *hdl" 200This function is optional. 201If supplied, it is called after all calls to 202.Fn set_params 203and 204.Fn set_port 205are done. 206A hardware driver that needs to get the hardware in 207and out of command mode for each change can save all the changes 208during previous calls and do them all here. 209This function returns 0 on success, otherwise an error code. 210.It Ft int Fn (*init_output) "void *hdl" "void *buffer" "int size" 211This function is optional. 212If supplied, it is called before any output starts, but only after the total 213.Fa size 214of the output 215.Fa buffer 216has been determined. 217It can be used to initialize looping DMA for hardware that needs it. 218This function returns 0 on success, otherwise an error code. 219.It Ft int Fn (*init_input) "void *hdl" "void *buffer" "int size" 220This function is optional. 221If supplied, it is called before any input starts, but only after the total 222.Fa size 223of the input 224.Fa buffer 225has been determined. 226It can be used to initialize looping DMA for hardware that needs it. 227This function returns 0 on success, otherwise an error code. 228.It Ft int Fn (*start_output) "void *hdl" "void *block" "int bsize" \ 229"void (*intr)(void *)" "void *intrarg" 230This function is deprecated. 231Use 232.Fn trigger_output 233instead. 234This function is called to start the transfer of 235.Fa bsize 236bytes from 237.Fa block 238to the audio hardware. 239The call returns when the data transfer 240has been initiated (normally with DMA). 241When the hardware is ready to accept more samples, the function 242.Fa intr 243will be called with the argument 244.Fa intrarg . 245Calling 246.Fa intr 247will normally initiate another call to 248.Fn start_output . 249This function returns 0 on success, otherwise an error code. 250.It Ft int Fn (*start_input) "void *hdl" "void *block" "int bsize" \ 251"void (*intr)(void *)" "void *intrarg" 252This function is deprecated. 253Use 254.Fn trigger_input 255instead. 256This function is called to start the transfer of 257.Fa bsize 258bytes to 259.Fa block 260from the audio hardware. 261The call returns when the data transfer 262has been initiated (normally with DMA). 263When the hardware is ready to deliver more samples, the function 264.Fa intr 265will be called with the argument 266.Fa intrarg . 267Calling 268.Fa intr 269will normally initiate another call to 270.Fn start_input . 271This function returns 0 on success, otherwise an error code. 272.It Ft int Fn (*halt_output) "void *hdl" 273This function is called to abort the output transfer (started by 274.Fn trigger_output ) 275in progress. 276This function returns 0 on success, otherwise an error code. 277.It Ft int Fn (*halt_input) "void *hdl" 278This function is called to abort the input transfer (started by 279.Fn trigger_input ) 280in progress. 281This function returns 0 on success, otherwise an error code. 282.It Ft int Fn (*set_port) "void *hdl" "struct mixer_ctrl *mc" 283This function is called when the 284.Dv AUDIO_MIXER_WRITE 285.Xr ioctl 2 286is used. 287It takes data from 288.Fa mc 289and sets the corresponding mixer values. 290This function returns 0 on success, otherwise an error code. 291.It Ft int Fn (*get_port) "void *hdl" "struct mixer_ctrl *mc" 292This function is called when the 293.Dv AUDIO_MIXER_READ 294.Xr ioctl 2 295is used. 296It fills 297.Fa mc 298and returns 0 on success, or it returns an error code on failure. 299.It Ft int Fn (*query_devinfo) "void *hdl" "struct mixer_devinfo *di" 300This function is called when the 301.Dv AUDIO_MIXER_DEVINFO 302.Xr ioctl 2 303is used. 304It fills 305.Fa di 306and returns 0 on success, or it returns an error code on failure. 307.It Ft void * Fn (*allocm) "void *hdl" "int direction" "size_t size" "int type" \ 308"int flags" 309This function is optional. 310If supplied, it is called to allocate the device buffers. 311If not supplied, 312.Xr malloc 9 313is used instead (with the same arguments but the first two). 314The reason for using a device dependent routine instead of 315.Xr malloc 9 316is that some buses need special allocation to do DMA. 317.Fa direction 318is 319.Dv AUMODE_PLAY 320or 321.Dv AUMODE_RECORD . 322This function returns the address of the buffer on success, or 0 on failure. 323.It Ft void Fn (*freem) "void *hdl" "void *addr" "int type" 324This function is optional. 325If supplied, it is called to free memory allocated by 326.Fn allocm . 327If not supplied, 328.Xr free 9 329is used instead. 330.\" XXX: code passes int instead of size_t, but decl is size_t 331.It Ft size_t Fn (*round_buffersize) "void *hdl" "int direction" \ 332"size_t bufsize" 333This function is optional. 334If supplied, it is called at startup to determine the audio buffer size. 335The upper layer supplies the suggested size in 336.Fa bufsize , 337which the hardware driver can then change if needed. 338E.g., DMA on the ISA bus cannot exceed 65536 bytes. 339Note that the buffer size is always a multiple of the block size, so 340.Fn round_blocksize 341and 342.Fn round_buffersize 343must be consistent. 344.It Ft int Fn (*trigger_output) "void *hdl" "void *start" "void *end" "int blksize" \ 345"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" 346This function is called to start the transfer of data from the circular 347buffer delimited by 348.Fa start 349and 350.Fa end 351to the audio hardware, parameterized as in 352.Fa param . 353The call returns when the data transfer 354has been initiated (normally with DMA). 355When the hardware is finished transferring each 356.Fa blksize 357sized block, the function 358.Fa intr 359will be called with the argument 360.Fa intrarg 361(typically from the audio hardware interrupt service routine). 362Once started, the transfer may be stopped using 363.Fn halt_output . 364This function returns 0 on success, otherwise an error code. 365.It Ft int Fn (*trigger_input) "void *hdl" "void *start" "void *end" "int blksize" \ 366"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" 367This function is called to start the transfer of data from the audio 368hardware, parameterized as in 369.Fa param , 370to the circular buffer delimited by 371.Fa start 372and 373.Fa end . 374The call returns when the data transfer 375has been initiated (normally with DMA). 376When the hardware is finished transferring each 377.Fa blksize 378sized block, the function 379.Fa intr 380will be called with the argument 381.Fa intrarg 382(typically from the audio hardware interrupt service routine). 383Once started, the transfer may be stopped using 384.Fn halt_input . 385This function returns 0 on success, otherwise an error code. 386.It Ft void Fn (*copy_output) "void *hdl" "size_t bytes" 387This function is called whenever the given amount of bytes was 388appended to the play ring buffer, typically during a 389.Xr write 2 390system call. 391Drivers using bounce buffers for transfers between the audio 392ring buffer and the device could implement this function 393to copy the given amount of bytes into their bounce buffers. 394There's no analogue function for recording as data is 395produced by the device and could simply be copied upon 396transfer completion. 397.It Ft void Fn (*underrun) "void *hdl" 398This function is called at interrupt context whenever a 399play block was skipped by the 400.Xr audio 4 401driver. 402Drivers using bounce buffers for transfers between the audio 403ring buffer and the device must implement this method to skip 404one block from the audio ring buffer and transfer the 405corresponding amount of silence to the device. 406.It Ft int Fn (*set_blksz) "void *hdl" "int mode" \ 407"struct audio_params *play" "struct audio_params *rec" "int blksz" 408This function is called to set the audio block size. 409.Fa mode 410is a combination of the 411.Dv AUMODE_RECORD 412and 413.Dv AUMODE_PLAY 414flags indicating the current mode set with the 415.Fn open 416function. 417The 418.Fa play 419and 420.Fa rec 421structures contain the current encoding set with the 422.Fn set_params 423function. 424.Fa blksz 425is the desired block size in frames. 426It may be adjusted to match hardware constraints. 427This function returns the adjusted block size. 428.It Ft int Fn (*set_nblks) "void *hdl" "int dir" "int blksz" \ 429"struct audio_params *params" "int nblks" 430This function is called to set the number of audio blocks in 431the ring buffer. 432.Fa dir 433is either the 434.Dv AUMODE_RECORD 435or the 436.Dv AUMODE_PLAY 437flag, indicating which ring buffer size is set. 438The 439.Fa params 440structure contains the encoding parameters set by the 441.Fn set_params 442method. 443.Fa blksz 444is the current block size in frames set with the 445.Fa set_params 446function. 447The 448.Fa params 449structure is the current encoding parameters, set with the 450.Fn set_params 451function. 452.Fa nblks 453is the desired number of blocks in the ring buffer. 454It may be lowered to at least two, to match hardware constraints. 455This function returns the adjusted number of blocks. 456.El 457.Pp 458If the audio hardware is capable of input from more 459than one source, it should define 460.Dv AudioNsource 461in class 462.Dv AudioCrecord . 463This mixer control should be of type 464.Dv AUDIO_MIXER_ENUM 465or 466.Dv AUDIO_MIXER_SET 467and enumerate the possible input sources. 468For each of the named sources there should be 469a control in the 470.Dv AudioCinputs 471class of type 472.Dv AUDIO_MIXER_VALUE 473if recording level of the source can be set. 474If the overall recording level can be changed (i.e., regardless 475of the input source) then this control should be named 476.Dv AudioNrecord 477and be of class 478.Dv AudioCinputs . 479.Pp 480If the audio hardware is capable of output to more than 481one destination, it should define 482.Dv AudioNoutput 483in class 484.Dv AudioCmonitor . 485This mixer control should be of type 486.Dv AUDIO_MIXER_ENUM 487or 488.Dv AUDIO_MIXER_SET 489and enumerate the possible destinations. 490For each of the named destinations there should be 491a control in the 492.Dv AudioCoutputs 493class of type 494.Dv AUDIO_MIXER_VALUE 495if output level of the destination can be set. 496If the overall output level can be changed (i.e., regardless 497of the destination) then this control should be named 498.Dv AudioNmaster 499and be of class 500.Dv AudioCoutputs . 501.Sh SEE ALSO 502.Xr ioctl 2 , 503.Xr open 2 , 504.Xr sio_open 3 , 505.Xr audio 4 , 506.Xr free 9 , 507.Xr malloc 9 508.Sh HISTORY 509This 510.Nm 511interface first appeared in 512.Ox 1.2 . 513