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