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