1.\" $NetBSD: audio.9,v 1.23 2002/10/14 13:43:14 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 March 11, 2002 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. 47The interface between these is the 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 int factor_denom; /* denominator of factor */ 107 /* 108 * The following four members represent what format is used in a 109 * hardware. If hw_sample_rate != sample_rate || hw_channels != 110 * channels, the audio framework converts data. Encoding and 111 * precision are converted in sw_code(). 112 * set_params() should set correct values to them if no conversion is 113 * needed. 114 */ 115 u_long hw_sample_rate; 116 u_int hw_encoding; 117 u_int hw_precision; 118 u_int hw_channels; 119}; 120.Ed 121.Pp 122The high level audio driver attaches to the low level driver 123when the latter calls 124.Va audio_attach_mi . 125This call should be 126.Bd -literal 127 void 128 audio_attach_mi(ahwp, hdl, dev) 129 struct audio_hw_if *ahwp; 130 void *hdl; 131 struct device *dev; 132.Ed 133.Pp 134The 135.Va audio_hw_if 136struct is as shown above. 137The 138.Va hdl 139argument is a handle to some low level data structure. 140It is sent as the first argument to all the functions 141in 142.Va audio_hw_if 143when the high level driver calls them. 144.Va dev 145is the device struct for the hardware device. 146.Pp 147The upper layer of the audio driver allocates one buffer for playing 148and one for recording. 149It handles the buffering of data from the user processes in these. 150The data is presented to the lower level in smaller chunks, called blocks. 151If there, during playback, is no data available from the user process when 152the hardware request another block a block of silence will be used instead. 153Furthermore, if the user process does not read data quickly enough during 154recording data will be thrown away. 155.Pp 156The fields of 157.Va audio_hw_if 158are described in some more detail below. 159Some fields are optional and can be set to 0 if not needed. 160.Bl -tag -width indent 161.It Dv int open(void *hdl, int flags) 162is called when the audio device is opened. 163It should initialize the hardware for I/O. 164Every successful call to 165.Va open 166is matched by a call to 167.Va close . 168Return 0 on success, otherwise an error code. 169.It Dv void close(void *hdl) 170is called when the audio device is closed. 171.It Dv int drain(void *hdl) 172optional, is called before the device is closed or when 173.Dv AUDIO_DRAIN 174is called. 175It should make sure that no samples remain in to be played that could 176be lost when 177.Va close 178is called. 179Return 0 on success, otherwise an error code. 180.It Dv int query_encoding(void *hdl, struct audio_encoding *ae) 181is used when 182.Dv AUDIO_GETENC 183is called. 184It should fill the 185.Va audio_encoding 186structure and return 0 or, if there is no encoding with the 187given number, return EINVAL. 188.It Dv int set_params(void *hdl, int setmode, int usemode, 189.Dv "struct audio_params *play, struct audio_params *rec)" 190.br 191Called to set the audio encoding mode. 192.Va setmode 193is a combination of the 194.Dv AUMODE_RECORD 195and 196.Dv AUMODE_PLAY 197flags to indicate which mode(s) are to be set. 198.Va usemode 199is also a combination of these flags, but indicates the current 200mode of the device (i.e., the value of 201.Va mode 202in the 203.Va audio_info 204struct). 205The 206.Va play 207and 208.Va rec 209structures contain the encoding parameters that should be set. 210.Pp 211If the hardware requires software assistance with some encoding 212(e.g., it might be lacking mulaw support) it should fill the 213.Va sw_code , 214.Va factor 215and 216.Va factor_denom 217fields of these structures with translation information, and 218set to hw_* fields what format the hardware actually uses. 219For example, if 220.Va play 221requests [8000Hz, mulaw, 8bit, 1ch] and the hardware supports 222not 8bit mulaw but 16bit slinear_le, the driver should set 223.Va mulaw_to_slinear16_le 224to 225.Va sw_code , 2262 to 227.Va factor , 2281 to 229.Va factor_denom , 230.Dv AUDIO_ENCODING_SLINEAR_LE 231to 232.Va hw_encoding 233and 16 to 234.Va hw_precision . 235The values of the structures may also be modified if the hardware 236cannot be set to exactly the requested mode (e.g., if the requested 237sampling rate is not supported, but one close enough is). 238.Pp 239The hardware driver can also request sampling rate conversion 240and mono-stereo conversion. 241If 242.Va set_params 243sets to 244.Va hw_sampling_rate 245a value which is different than 246.Va sampling_rate 247or sets to 248.Va hw_channels 249a value which is different than 250.Va channels , 251and set 252.Dv AUDIO_ENCODING_SLINEAR_LE 253to 254.Va hw_encoding , 255the hardware independent driver performs sampling rate and/or mono-stereo 256conversion. 257If such conversion is not needed, 258.Va set_params 259must keep 260.Va sampling_rate 261and 262.Va channels 263are the same as 264.Va hw_sampling_rate 265and 266.Va hw_channels 267respectively. 268.Pp 269Note: The order of conversion is 270.Va sw_code 271followed by sampling rate and mono-stereo in playing, 272and sampling rate and mono-stereo followed by 273.Va sw_code 274in recording. 275.Pp 276If the device does not have the 277.Dv AUDIO_PROP_INDEPENDENT 278property the same value is passed in both 279.Va play 280and 281.Va rec 282and the encoding parameters from 283.Va play 284is copied into 285.Va rec 286after the call to 287.Va set_params . 288Return 0 on success, otherwise an error code. 289.It Dv int round_blocksize(void *hdl, int bs) 290optional, is called with the block size, 291.Va bs , 292that has been computed by the upper layer. 293It should return a block size, possibly changed according to the needs 294of the hardware driver. 295.It Dv int commit_settings(void *hdl) 296optional, is called after all calls to 297.Va set_params , 298and 299.Va set_port , 300are done. 301A hardware driver that needs to get the hardware in and out of command 302mode for each change can save all the changes during previous calls and 303do them all here. 304Return 0 on success, otherwise an error code. 305.It Dv int init_output(void *hdl, void *buffer, int size) 306optional, is called before any output starts, but when the total 307.Va size 308of the output 309.Va buffer 310has been determined. 311It can be used to initialize looping DMA for hardware that needs that. 312Return 0 on success, otherwise an error code. 313.It Dv int init_input(void *hdl, void *buffer, int size) 314optional, is called before any input starts, but when the total 315.Va size 316of the input 317.Va buffer 318has been determined. 319It can be used to initialize looping DMA for hardware that needs that. 320Return 0 on success, otherwise an error code. 321.It Dv int start_output(void *hdl, void *block, int blksize, 322.Dv "void (*intr)(void*), void *intrarg)" 323.br 324is called to start the transfer of 325.Va blksize 326bytes from 327.Va block 328to the audio hardware. 329The call should return when the data transfer has been initiated 330(normally with DMA). 331When the hardware is ready to accept more samples the function 332.Va intr 333should be called with the argument 334.Va intrarg . 335Calling 336.Va intr 337will normally initiate another call to 338.Va start_output . 339Return 0 on success, otherwise an error code. 340.It Dv int start_input(void *hdl, void *block, int blksize, 341.Dv "void (*intr)(void*), void *intrarg)" 342.br 343is called to start the transfer of 344.Va blksize 345bytes to 346.Va block 347from the audio hardware. 348The call should return when the data transfer has been initiated 349(normally with DMA). 350When the hardware is ready to deliver more samples the function 351.Va intr 352should be called with the argument 353.Va intrarg . 354Calling 355.Va intr 356will normally initiate another call to 357.Va start_input . 358Return 0 on success, otherwise an error code. 359.It Dv int halt_output(void *hdl) 360is called to abort the output transfer (started by 361.Va start_output ) 362in progress. 363Return 0 on success, otherwise an error code. 364.It Dv int halt_input(void *hdl) 365is called to abort the input transfer (started by 366.Va start_input ) 367in progress. 368Return 0 on success, otherwise an error code. 369.It Dv int speaker_ctl(void *hdl, int on) 370optional, is called when a half duplex device changes between 371playing and recording. 372It can, e.g., be used to turn on 373and off the speaker. 374Return 0 on success, otherwise an error code. 375.It Dv int getdev(void *hdl, struct audio_device *ret) 376Should fill the 377.Va audio_device 378struct with relevant information about the driver. 379Return 0 on success, otherwise an error code. 380.It Dv int setfd(void *hdl, int fd) 381optional, is called when 382.Dv AUDIO_SETFD 383is used, but only if the device has AUDIO_PROP_FULLDUPLEX set. 384Return 0 on success, otherwise an error code. 385.It Dv int set_port(void *hdl, mixer_ctl_t *mc) 386is called in when 387.Dv AUDIO_MIXER_WRITE 388is used. 389It should take data from the 390.Va mixer_ctl_t 391struct at set the corresponding mixer values. 392Return 0 on success, otherwise an error code. 393.It Dv int get_port(void *hdl, mixer_ctl_t *mc) 394is called in when 395.Dv AUDIO_MIXER_READ 396is used. 397It should fill the 398.Va mixer_ctl_t 399struct. 400Return 0 on success, otherwise an error code. 401.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) 402is called in when 403.Dv AUDIO_MIXER_DEVINFO 404is used. 405It should fill the 406.Va mixer_devinfo_t 407struct. 408Return 0 on success, otherwise an error code. 409.It Dv "void *allocm(void *hdl, int direction, size_t size, int type, int flags)" 410.br 411optional, is called to allocate the device buffers. 412If not present 413.Xr malloc 9 414is used instead (with the same arguments but the first two). 415The reason for using a device dependent routine instead of 416.Xr malloc 9 417is that some buses need special allocation to do DMA. 418Returns the address of the buffer, or 0 on failure. 419.It Dv void freem(void *hdl, void *addr, int type) 420optional, is called to free memory allocated by 421.Va alloc . 422If not supplied 423.Xr free 9 424is used. 425.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) 426optional, is called at startup to determine the audio 427buffer size. 428The upper layer supplies the suggested size in 429.Va bufsize , 430which the hardware driver can then change if needed. 431E.g., DMA on the ISA bus cannot exceed 65536 bytes. 432.It Dv "int mappage(void *hdl, void *addr, int offs, int prot)" 433.br 434optional, is called for 435.Xr mmap 2 . 436Should return the map value for the page at offset 437.Va offs 438from address 439.Va addr 440mapped with protection 441.Va prot . 442Returns -1 on failure, or a machine dependent opaque value 443on success. 444.It Dv int get_props(void *hdl) 445Should return the device properties; i.e., a combination of 446AUDIO_PROP_xxx. 447.It Dv int trigger_output(void *hdl, void *start, void *end, 448.Dv "int blksize, void (*intr)(void*), void *intrarg," 449.br 450.Dv "struct audio_params *param)" 451.br 452optional, is called to start the transfer of data from the circular buffer 453delimited by 454.Va start 455and 456.Va end 457to the audio hardware, parameterized as in 458.Va param . 459The call should return when the data transfer has been initiated 460(normally with DMA). 461When the hardware is finished transferring each 462.Va blksize 463sized block, the function 464.Va intr 465should be called with the argument 466.Va intrarg 467(typically from the audio hardware interrupt service routine). 468Once started the transfer may be stopped using 469.Va halt_output . 470Return 0 on success, otherwise an error code. 471.It Dv int trigger_input(void *hdl, void *start, void *end, 472.Dv "int blksize, void (*intr)(void*), void *intrarg," 473.br 474.Dv "struct audio_params *param)" 475.br 476optional, is called to start the transfer of data from the audio hardware, 477parameterized as in 478.Va param , 479to the circular buffer delimited by 480.Va start 481and 482.Va end . 483The call should return when the data transfer has been initiated 484(normally with DMA). 485When the hardware is finished transferring each 486.Va blksize 487sized block, the function 488.Va intr 489should be called with the argument 490.Va intrarg 491(typically from the audio hardware interrupt service routine). 492Once started the transfer may be stopped using 493.Va halt_input . 494Return 0 on success, otherwise an error code. 495.It Dv int dev_ioctl(void *hdl, u_long cmd, caddr_t addr, 496.br 497.Dv "int flag, struct proc *p)" 498.br 499optional, is called when an 500.Xr ioctl 2 501is not recognized by the generic audio driver. 502Return 0 on success, otherwise an error code. 503.El 504.Pp 505The 506.Va query_devinfo 507method should define certain mixer controls for 508.Dv AUDIO_SETINFO 509to be able to change the port and gain. 510.Pp 511If the audio hardware is capable of input from more 512than one source it should define 513.Dv AudioNsource 514in class 515.Dv AudioCrecord . 516This mixer control should be of type 517.Dv AUDIO_MIXER_ENUM 518or 519.Dv AUDIO_MIXER_SET 520and enumerate the possible input sources. 521For each of the named sources there should be 522a control in the 523.Dv AudioCinputs 524class of type 525.Dv AUDIO_MIXER_VALUE 526if recording level of the source can be set. 527If the overall recording level can be changed (i.e., regardless 528of the input source) then this control should be named 529.Dv AudioNrecord 530and be of class 531.Dv AudioCinputs . 532.Pp 533If the audio hardware is capable of output to more than 534one destination it should define 535.Dv AudioNoutput 536in class 537.Dv AudioCmonitor . 538This mixer control should be of type 539.Dv AUDIO_MIXER_ENUM 540or 541.Dv AUDIO_MIXER_SET 542and enumerate the possible destinations. 543For each of the named destinations there should be 544a control in the 545.Dv AudioCoutputs 546class of type 547.Dv AUDIO_MIXER_VALUE 548if output level of the destination can be set. 549If the overall output level can be changed (i.e., regardless 550of the destination) then this control should be named 551.Dv AudioNmaster 552and be of class 553.Dv AudioCoutputs . 554.Sh SEE ALSO 555.Xr audio 4 556.Sh HISTORY 557This 558.Nm 559interface first appeared in 560.Nx 1.3 . 561