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