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