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