1.\" $NetBSD: audio.9,v 1.17 2001/06/21 11:59:00 wiz Exp $ 2.\" 3.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 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 FOUNDATION OR CONTRIBUTORS 29.\" BE 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 February 11, 2000 38.Dt AUDIO 9 39.Os 40.Sh NAME 41.Nm audio 42.Nd interface between low and high level audio drivers 43.Sh DESCRIPTION 44The audio device driver is divided into a high level, 45hardware independent layer, and a low level hardware 46dependent layer. The interface between these is 47the 48.Va audio_hw_if 49structure. 50.Bd -literal 51struct audio_hw_if { 52 int (*open)__P((void *, int)); 53 void (*close)__P((void *)); 54 int (*drain)__P((void *)); 55 56 int (*query_encoding)__P((void *, struct audio_encoding *)); 57 int (*set_params)__P((void *, int, int, 58 struct audio_params *, struct audio_params *)); 59 int (*round_blocksize)__P((void *, int)); 60 61 int (*commit_settings)__P((void *)); 62 63 int (*init_output)__P((void *, void *, int)); 64 int (*init_input)__P((void *, void *, int)); 65 int (*start_output)__P((void *, void *, int, 66 void (*)(void *), void *)); 67 int (*start_input)__P((void *, void *, int, 68 void (*)(void *), void *)); 69 int (*halt_output)__P((void *)); 70 int (*halt_input)__P((void *)); 71 72 int (*speaker_ctl)__P((void *, int)); 73#define SPKR_ON 1 74#define SPKR_OFF 0 75 76 int (*getdev)__P((void *, struct audio_device *)); 77 int (*setfd)__P((void *, int)); 78 79 int (*set_port)__P((void *, mixer_ctrl_t *)); 80 int (*get_port)__P((void *, mixer_ctrl_t *)); 81 82 int (*query_devinfo)__P((void *, mixer_devinfo_t *)); 83 84 void *(*allocm)__P((void *, int, size_t, int, int)); 85 void (*freem)__P((void *, void *, int)); 86 size_t (*round_buffersize)__P((void *, int, size_t)); 87 int (*mappage)__P((void *, void *, int, int)); 88 89 int (*get_props)__P((void *)); 90 91 int (*trigger_output)__P((void *, void *, void *, int, 92 void (*)(void *), void *, struct audio_params *)); 93 int (*trigger_input)__P((void *, void *, void *, int, 94 void (*)(void *), void *, struct audio_params *)); 95}; 96 97struct audio_params { 98 u_long sample_rate; /* sample rate */ 99 u_int encoding; /* ulaw, linear, etc */ 100 u_int precision; /* bits/sample */ 101 u_int channels; /* mono(1), stereo(2) */ 102 /* Software en/decode functions, set if SW coding required by HW */ 103 void (*sw_code)__P((void *, u_char *, int)); 104 int factor; /* coding space change */ 105}; 106.Ed 107.Pp 108The high level audio driver attaches to the low level driver 109when the latter calls 110.Va audio_attach_mi . 111This call should be 112.Bd -literal 113 void 114 audio_attach_mi(ahwp, hdl, dev) 115 struct audio_hw_if *ahwp; 116 void *hdl; 117 struct device *dev; 118.Ed 119.Pp 120The 121.Va audio_hw_if 122struct is as shown above. The 123.Va hdl 124argument is a handle to some low level data structure. 125It is sent as the first argument to all the functions 126in 127.Va audio_hw_if 128when the high level driver calls them. 129.Va dev 130is the device struct for the hardware device. 131.Pp 132The upper layer of the audio driver allocates one buffer for playing 133and one for recording. It handles the buffering of data from the 134user processes in these. The data is presented to the lower level 135in smaller chunks, called blocks. If there, during playback, is 136no data available from the user process when the hardware request 137another block a block of silence will be used instead. Furthermore, 138if the user process does not read data quickly enough during recording 139data will be thrown away. 140.Pp 141The fields of 142.Va audio_hw_if 143are described in some more detail below. 144Some fields are optional and can be set to 0 if not needed. 145.Bl -tag -width indent 146.It Dv int open(void *hdl, int flags) 147is called when the audio device is opened. It should initialize 148the hardware for I/O. Every successful call to 149.Va open 150is matched by a call to 151.Va close . 152Return 0 on success, otherwise an error code. 153.It Dv void close(void *hdl) 154is called when the audio device is closed. 155.It Dv int drain(void *hdl) 156optional, is called before the device is closed or when 157.Dv AUDIO_DRAIN 158is called. It should make sure that no samples remain 159in to be played that could be lost when 160.Va close 161is called. 162Return 0 on success, otherwise an error code. 163.It Dv int query_encoding(void *hdl, struct audio_encoding *ae) 164is used when 165.Dv AUDIO_GETENC 166is called. It should fill the 167.Va audio_encoding 168structure and return 0 or, if there is no encoding with the 169given number, return EINVAL. 170.It Dv int set_params(void *hdl, int setmode, int usemode, 171.Dv "struct audio_params *play, struct audio_params *rec)" 172.br 173Called to set the audio encoding mode. 174.Va setmode 175is a combination of the 176.Dv AUMODE_RECORD 177and 178.Dv AUMODE_PLAY 179flags to indicate which mode(s) are to be set. 180.Va usemode 181is also a combination of these flags, but indicates the current 182mode of the device (i.e. the value of 183.Va mode 184in the 185.Va audio_info 186struct). 187The 188.Va play 189and 190.Va rec 191structures contain the encoding parameters that should be set. 192If the hardware requires software assistance with some encoding 193(e.g., it might be lacking mulaw support) it should fill the 194.Va sw_code 195and 196.Va factor 197fields of these structures. 198The values of the structures may also be modified if the hardware 199cannot be set to exactly the requested mode (e.g. if the requested 200sampling rate is not supported, but one close enough is). 201If the device does not have the 202.Dv AUDIO_PROP_INDEPENDENT 203property the same value is passed in both 204.Va play 205and 206.Va rec 207and the encoding parameters from 208.Va play 209is copied into 210.Va rec 211after the call to 212.Va set_params . 213Return 0 on success, otherwise an error code. 214.It Dv int round_blocksize(void *hdl, int bs) 215optional, is called with the block size, 216.Va bs , 217that has been computed by the upper layer. It should return 218a block size, possibly changed according to the needs of the 219hardware driver. 220.It Dv int commit_settings(void *hdl) 221optional, is called after all calls to 222.Va set_params , 223and 224.Va set_port , 225are done. A hardware driver that needs to get the hardware in 226and out of command mode for each change can save all the changes 227during previous calls and do them all here. 228Return 0 on success, otherwise an error code. 229.It Dv int init_output(void *hdl, void *buffer, int size) 230optional, is called before any output starts, but when the total 231.Va size 232of the output 233.Va buffer 234has been determined. It can be used to initialize looping DMA 235for hardware that needs that. 236Return 0 on success, otherwise an error code. 237.It Dv int init_input(void *hdl, void *buffer, int size) 238optional, is called before any input starts, but when the total 239.Va size 240of the input 241.Va buffer 242has been determined. It can be used to initialize looping DMA 243for hardware that needs that. 244Return 0 on success, otherwise an error code. 245.It Dv int start_output(void *hdl, void *block, int blksize, 246.Dv "void (*intr)(void*), void *intrarg)" 247.br 248is called to start the transfer of 249.Va blksize 250bytes from 251.Va block 252to the audio hardware. The call should return when the data 253transfer has been initiated (normally with DMA). When the 254hardware is ready to accept more samples the function 255.Va intr 256should be called with the argument 257.Va intrarg . 258Calling 259.Va intr 260will normally initiate another call to 261.Va start_output . 262Return 0 on success, otherwise an error code. 263.It Dv int start_input(void *hdl, void *block, int blksize, 264.Dv "void (*intr)(void*), void *intrarg)" 265.br 266is called to start the transfer of 267.Va blksize 268bytes to 269.Va block 270from the audio hardware. The call should return when the data 271transfer has been initiated (normally with DMA). When the 272hardware is ready to deliver more samples the function 273.Va intr 274should be called with the argument 275.Va intrarg . 276Calling 277.Va intr 278will normally initiate another call to 279.Va start_input . 280Return 0 on success, otherwise an error code. 281.It Dv int halt_output(void *hdl) 282is called to abort the output transfer (started by 283.Va start_output ) 284in progress. 285Return 0 on success, otherwise an error code. 286.It Dv int halt_input(void *hdl) 287is called to abort the input transfer (started by 288.Va start_input ) 289in progress. 290Return 0 on success, otherwise an error code. 291.It Dv int speaker_ctl(void *hdl, int on) 292optional, is called when a half duplex device changes between 293playing and recording. It can, e.g., be used to turn on 294and off the speaker. 295Return 0 on success, otherwise an error code. 296.It Dv int getdev(void *hdl, struct audio_device *ret) 297Should fill the 298.Va audio_device 299struct with relevant information about the driver. 300Return 0 on success, otherwise an error code. 301.It Dv int setfd(void *hdl, int fd) 302optional, is called when 303.Dv AUDIO_SETFD 304is used, but only if the device has AUDIO_PROP_FULLDUPLEX set. 305Return 0 on success, otherwise an error code. 306.It Dv int set_port(void *hdl, mixer_ctl_t *mc) 307is called in when 308.Dv AUDIO_MIXER_WRITE 309is used. It should take data from the 310.Va mixer_ctl_t 311struct at set the corresponding mixer values. 312Return 0 on success, otherwise an error code. 313.It Dv int get_port(void *hdl, mixer_ctl_t *mc) 314is called in when 315.Dv AUDIO_MIXER_READ 316is used. It should fill the 317.Va mixer_ctl_t 318struct. 319Return 0 on success, otherwise an error code. 320.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) 321is called in when 322.Dv AUDIO_MIXER_DEVINFO 323is used. It should fill the 324.Va mixer_devinfo_t 325struct. 326Return 0 on success, otherwise an error code. 327.It Dv "void *allocm(void *hdl, int direction, size_t size, int type, int flags)" 328.br 329optional, is called to allocate the device buffers. If not present 330.Xr malloc 9 331is used instead (with the same arguments but the first two). 332The reason for using a device dependent routine instead of 333.Xr malloc 9 334is that some buses need special allocation to do DMA. 335Returns the address of the buffer, or 0 on failure. 336.It Dv void freem(void *hdl, void *addr, int type) 337optional, is called to free memory allocated by 338.Va alloc . 339If not supplied 340.Xr free 9 341is used. 342.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) 343optional, is called at startup to determine the audio 344buffer size. The upper layer supplies the suggested 345size in 346.Va bufsize , 347which the hardware driver can then change if needed. 348E.g., DMA on the ISA bus cannot exceed 65536 bytes. 349.It Dv "int mappage(void *hdl, void *addr, int offs, int prot)" 350.br 351optional, is called for 352.Xr mmap 2 . 353Should return the map value for the page at offset 354.Va offs 355from address 356.Va addr 357mapped with protection 358.Va prot . 359Returns -1 on failure, or a machine dependent opaque value 360on success. 361.It Dv int get_props(void *hdl) 362Should return the device properties; i.e. a combination of 363AUDIO_PROP_xxx. 364.It Dv int trigger_output(void *hdl, void *start, void *end, 365.Dv "int blksize, void (*intr)(void*), void *intrarg," 366.br 367.Dv "struct audio_params *param)" 368.br 369optional, is called to start the transfer of data from the circular buffer 370delimited by 371.Va start 372and 373.Va end 374to the audio hardware, parameterized as in 375.Va param . 376The call should return when the data transfer has been initiated 377(normally with DMA). When the hardware is finished transferring 378each 379.Va blksize 380sized block, the function 381.Va intr 382should be called with the argument 383.Va intrarg 384(typically from the audio hardware interrupt service routine). 385Once started the transfer may be stopped using 386.Va halt_output . 387Return 0 on success, otherwise an error code. 388.It Dv int trigger_input(void *hdl, void *start, void *end, 389.Dv "int blksize, void (*intr)(void*), void *intrarg," 390.br 391.Dv "struct audio_params *param)" 392.br 393optional, is called to start the transfer of data from the audio hardware, 394parameterized as in 395.Va param , 396to the circular buffer delimited by 397.Va start 398and 399.Va end . 400The call should return when the data transfer has been initiated 401(normally with DMA). When the hardware is finished transferring 402each 403.Va blksize 404sized block, the function 405.Va intr 406should be called with the argument 407.Va intrarg 408(typically from the audio hardware interrupt service routine). 409Once started the transfer may be stopped using 410.Va halt_input . 411Return 0 on success, otherwise an error code. 412.El 413.Pp 414The 415.Va query_devinfo 416method should define certain mixer controls for 417.Dv AUDIO_SETINFO 418to be able to change the port and gain. 419.Pp 420If the audio hardware is capable of input from more 421than one source it should define 422.Dv AudioNsource 423in class 424.Dv AudioCrecord . 425This mixer control should be of type 426.Dv AUDIO_MIXER_ENUM 427or 428.Dv AUDIO_MIXER_SET 429and enumerate the possible input sources. 430For each of the named sources there should be 431a control in the 432.Dv AudioCinputs 433class of type 434.Dv AUDIO_MIXER_VALUE 435if recording level of the source can be set. 436If the overall recording level can be changed (i.e. regardless 437of the input source) then this control should be named 438.Dv AudioNrecord 439and be of class 440.Dv AudioCinputs . 441.Pp 442If the audio hardware is capable of output to more than 443one destination it should define 444.Dv AudioNoutput 445in class 446.Dv AudioCmonitor . 447This mixer control should be of type 448.Dv AUDIO_MIXER_ENUM 449or 450.Dv AUDIO_MIXER_SET 451and enumerate the possible destinations. 452For each of the named destinations there should be 453a control in the 454.Dv AudioCoutputs 455class of type 456.Dv AUDIO_MIXER_VALUE 457if output level of the destination can be set. 458If the overall output level can be changed (i.e. regardless 459of the destination) then this control should be named 460.Dv AudioNmaster 461and be of class 462.Dv AudioCoutputs . 463.Sh SEE ALSO 464.Xr audio 4 465.Sh HISTORY 466This 467.Nm 468interface first appeared in 469.Nx 1.3 . 470