1.\" $NetBSD: audio.9,v 1.40 2007/11/10 20:55:33 jmcneill 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 November 10, 2007 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 audio_params_t *, audio_params_t *, 59 stream_filter_list_t *, stream_filter_list_t *); 60 int (*round_blocksize)(void *, int, int, const audio_params_t *); 61 62 int (*commit_settings)(void *); 63 64 int (*init_output)(void *, void *, int); 65 int (*init_input)(void *, void *, int); 66 int (*start_output)(void *, void *, int, void (*)(void *), 67 void *); 68 int (*start_input)(void *, void *, int, void (*)(void *), 69 void *); 70 int (*halt_output)(void *); 71 int (*halt_input)(void *); 72 73 int (*speaker_ctl)(void *, int); 74#define SPKR_ON 1 75#define SPKR_OFF 0 76 77 int (*getdev)(void *, struct audio_device *); 78 int (*setfd)(void *, int); 79 80 int (*set_port)(void *, mixer_ctrl_t *); 81 int (*get_port)(void *, mixer_ctrl_t *); 82 83 int (*query_devinfo)(void *, mixer_devinfo_t *); 84 85 void *(*allocm)(void *, int, size_t, struct malloc_type *, int); 86 void (*freem)(void *, void *, struct malloc_type *); 87 size_t (*round_buffersize)(void *, int, size_t); 88 paddr_t (*mappage)(void *, void *, off_t, int); 89 90 int (*get_props)(void *); 91 92 int (*trigger_output)(void *, void *, void *, int, 93 void (*)(void *), void *, const audio_params_t *); 94 int (*trigger_input)(void *, void *, void *, int, 95 void (*)(void *), void *, const audio_params_t *); 96 int (*dev_ioctl)(void *, u_long, void *, int, struct lwp *); 97 int (*powerstate)(void *, int); 98#define AUDIOPOWER_ON 1 99#define AUDIOPOWER_OFF 0 100}; 101 102typedef struct audio_params { 103 u_int sample_rate; /* sample rate */ 104 u_int encoding; /* e.g. mu-law, linear, etc */ 105 u_int precision; /* bits/subframe */ 106 u_int validbits; /* valid bits in a subframe */ 107 u_int channels; /* mono(1), stereo(2) */ 108} audio_params_t; 109.Ed 110.Pp 111The high level audio driver attaches to the low level driver 112when the latter calls 113.Va audio_attach_mi . 114This call should be 115.Bd -literal 116 void 117 audio_attach_mi(ahwp, hdl, dev) 118 struct audio_hw_if *ahwp; 119 void *hdl; 120 struct device *dev; 121.Ed 122.Pp 123The 124.Va audio_hw_if 125struct is as shown above. 126The 127.Va hdl 128argument is a handle to some low level data structure. 129It is sent as the first argument to all the functions 130in 131.Va audio_hw_if 132when the high level driver calls them. 133.Va dev 134is the device struct for the hardware device. 135.Pp 136The upper layer of the audio driver allocates one buffer for playing 137and one for recording. 138It handles the buffering of data from the user processes in these. 139The data is presented to the lower level in smaller chunks, called blocks. 140If there, during playback, is no data available from the user process when 141the hardware request another block a block of silence will be used instead. 142Furthermore, if the user process does not read data quickly enough during 143recording data will be thrown away. 144.Pp 145The fields of 146.Va audio_hw_if 147are described in some more detail below. 148Some fields are optional and can be set to 0 if not needed. 149.Bl -tag -width indent 150.It Dv int open(void *hdl, int flags) 151optional, is called when the audio device is opened. 152It should initialize the hardware for I/O. 153Every successful call to 154.Va open 155is matched by a call to 156.Va close . 157Return 0 on success, otherwise an error code. 158.It Dv void close(void *hdl) 159optional, is called when the audio device is closed. 160.It Dv int drain(void *hdl) 161optional, is called before the device is closed or when 162.Dv AUDIO_DRAIN 163is called. 164It should make sure that no samples remain in to be played that could 165be lost when 166.Va close 167is called. 168Return 0 on success, otherwise an error code. 169.It Dv int query_encoding(void *hdl, struct audio_encoding *ae) 170is used when 171.Dv AUDIO_GETENC 172is called. 173It should fill the 174.Va audio_encoding 175structure and return 0 or, if there is no encoding with the 176given number, return EINVAL. 177.It Dv int set_params(void *hdl, int setmode, int usemode, 178.Dv "audio_params_t *play, audio_params_t *rec," 179.Pp 180.Dv "stream_filter_list_t *pfil, stream_filter_list_t *rfil)" 181.Pp 182Called to set the audio encoding mode. 183.Va setmode 184is a combination of the 185.Dv AUMODE_RECORD 186and 187.Dv AUMODE_PLAY 188flags to indicate which mode(s) are to be set. 189.Va usemode 190is also a combination of these flags, but indicates the current 191mode of the device (i.e., the value of 192.Va mode 193in the 194.Va audio_info 195struct). 196.Pp 197The 198.Va play 199and 200.Va rec 201structures contain the encoding parameters that should be set. 202The values of the structures may also be modified if the hardware 203cannot be set to exactly the requested mode (e.g., if the requested 204sampling rate is not supported, but one close enough is). 205.Pp 206If the hardware requires software assistance with some encoding 207(e.g., it might be lacking mu-law support) it should fill the 208.Va pfil 209for playing or 210.Va rfil 211for recording with conversion information. 212For example, if 213.Va play 214requests [8000Hz, mu-law, 8/8bit, 1ch] and the hardware does not 215support 8bit mu-law, but 16bit slinear_le, the driver should call 216.Dv pfil-\*[Gt]append() 217with 218.Va pfil , 219.Va mulaw_to_slinear16 , 220and audio_params_t representing [8000Hz, slinear_le, 16/16bit, 2ch]. 221If the driver needs multiple conversions, a conversion nearest to the 222hardware should be set to the head of 223.Va pfil 224or 225.Va rfil . 226The definition of 227.Dv stream_filter_list_t 228follows: 229.Bd -literal 230typedef struct stream_filter_list { 231 void (*append)(struct stream_filter_list *, 232 stream_filter_factory_t, 233 const audio_params_t *); 234 void (*prepend)(struct stream_filter_list *, 235 stream_filter_factory_t, 236 const audio_params_t *); 237 void (*set)(struct stream_filter_list *, int, 238 stream_filter_factory_t, 239 const audio_params_t *); 240 int req_size; 241 struct stream_filter_req { 242 stream_filter_factory_t *factory; 243 audio_params_t param; /* from-param for recording, 244 to-param for playing */ 245 } filters[AUDIO_MAX_FILTERS]; 246} stream_filter_list_t; 247.Ed 248.Pp 249For playing, 250.Va pfil 251constructs conversions as follows: 252.Bd -literal 253 (play) == write(2) input 254 | pfil-\*[Gt]filters[pfil-\*[Gt]req_size-1].factory 255 (pfil-\*[Gt]filters[pfil-\*[Gt]req_size-1].param) 256 | pfil-\*[Gt]filters[pfil-\*[Gt]req_size-2].factory 257 : 258 | pfil-\*[Gt]filters[1].factory 259 (pfil-\*[Gt]filters[1].param) 260 | pfil-\*[Gt]filters[0].factory 261 (pfil-\*[Gt]filters[0].param) == hardware input 262.Ed 263.Pp 264For recording, 265.Va rfil 266constructs conversions as follows: 267.Bd -literal 268 (rfil-\*[Gt]filters[0].param) == hardware output 269 | rfil-\*[Gt]filters[0].factory 270 (rfil-\*[Gt]filters[1].param) 271 | rfil-\*[Gt]filters[1].factory 272 : 273 | rfil-\*[Gt]filters[rfil-\*[Gt]req_size-2].factory 274 (rfil-\*[Gt]filters[rfil-\*[Gt]req_size-1].param) 275 | rfil-\*[Gt]filters[rfil-\*[Gt]req_size-1].factory 276 (rec) == read(2) output 277.Ed 278.Pp 279If the device does not have the 280.Dv AUDIO_PROP_INDEPENDENT 281property the same value is passed in both 282.Va play 283and 284.Va rec 285and the encoding parameters from 286.Va play 287is copied into 288.Va rec 289after the call to 290.Va set_params . 291Return 0 on success, otherwise an error code. 292.It Dv int round_blocksize(void *hdl, int bs, int mode, 293.Dv "const audio_params_t *param)" 294.Pp 295optional, is called with the block size, 296.Va bs , 297that has been computed by the upper layer, 298.Va mode , 299.Dv AUMODE_PLAY 300or 301.Dv AUMODE_RECORD , 302and 303.Va param , 304encoding parameters for the hardware. 305It should return a block size, possibly changed according to the needs 306of the hardware driver. 307.It Dv int commit_settings(void *hdl) 308optional, is called after all calls to 309.Va set_params , 310and 311.Va set_port , 312are done. 313A hardware driver that needs to get the hardware in and out of command 314mode for each change can save all the changes during previous calls and 315do them all here. 316Return 0 on success, otherwise an error code. 317.It Dv int init_output(void *hdl, void *buffer, int size) 318optional, is called before any output starts, but when the total 319.Va size 320of the output 321.Va buffer 322has been determined. 323It can be used to initialize looping DMA for hardware that needs that. 324Return 0 on success, otherwise an error code. 325.It Dv int init_input(void *hdl, void *buffer, int size) 326optional, is called before any input starts, but when the total 327.Va size 328of the input 329.Va buffer 330has been determined. 331It can be used to initialize looping DMA for hardware that needs that. 332Return 0 on success, otherwise an error code. 333.It Dv int start_output(void *hdl, void *block, int blksize, 334.Dv "void (*intr)(void*), void *intrarg)" 335.Pp 336is called to start the transfer of 337.Va blksize 338bytes from 339.Va block 340to the audio hardware. 341The call should return when the data transfer has been initiated 342(normally with DMA). 343When the hardware is ready to accept more samples the function 344.Va intr 345should be called with the argument 346.Va intrarg . 347Calling 348.Va intr 349will normally initiate another call to 350.Va start_output . 351Return 0 on success, otherwise an error code. 352.It Dv int start_input(void *hdl, void *block, int blksize, 353.Dv "void (*intr)(void*), void *intrarg)" 354.Pp 355is called to start the transfer of 356.Va blksize 357bytes to 358.Va block 359from the audio hardware. 360The call should return when the data transfer has been initiated 361(normally with DMA). 362When the hardware is ready to deliver more samples the function 363.Va intr 364should be called with the argument 365.Va intrarg . 366Calling 367.Va intr 368will normally initiate another call to 369.Va start_input . 370Return 0 on success, otherwise an error code. 371.It Dv int halt_output(void *hdl) 372is called to abort the output transfer (started by 373.Va start_output ) 374in progress. 375Return 0 on success, otherwise an error code. 376.It Dv int halt_input(void *hdl) 377is called to abort the input transfer (started by 378.Va start_input ) 379in progress. 380Return 0 on success, otherwise an error code. 381.It Dv int speaker_ctl(void *hdl, int on) 382optional, is called when a half duplex device changes between 383playing and recording. 384It can, e.g., be used to turn on 385and off the speaker. 386Return 0 on success, otherwise an error code. 387.It Dv int getdev(void *hdl, struct audio_device *ret) 388Should fill the 389.Va audio_device 390struct with relevant information about the driver. 391Return 0 on success, otherwise an error code. 392.It Dv int setfd(void *hdl, int fd) 393optional, is called when 394.Dv AUDIO_SETFD 395is used, but only if the device has AUDIO_PROP_FULLDUPLEX set. 396Return 0 on success, otherwise an error code. 397.It Dv int set_port(void *hdl, mixer_ctrl_t *mc) 398is called in when 399.Dv AUDIO_MIXER_WRITE 400is used. 401It should take data from the 402.Va mixer_ctrl_t 403struct at set the corresponding mixer values. 404Return 0 on success, otherwise an error code. 405.It Dv int get_port(void *hdl, mixer_ctrl_t *mc) 406is called in when 407.Dv AUDIO_MIXER_READ 408is used. 409It should fill the 410.Va mixer_ctrl_t 411struct. 412Return 0 on success, otherwise an error code. 413.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) 414is called in when 415.Dv AUDIO_MIXER_DEVINFO 416is used. 417It should fill the 418.Va mixer_devinfo_t 419struct. 420Return 0 on success, otherwise an error code. 421.It Dv "void *allocm(void *hdl, int direction, size_t size, struct malloc_type *type, int flags)" 422.Pp 423optional, is called to allocate the device buffers. 424If not present 425.Xr malloc 9 426is used instead (with the same arguments but the first two). 427The reason for using a device dependent routine instead of 428.Xr malloc 9 429is that some buses need special allocation to do DMA. 430Returns the address of the buffer, or 0 on failure. 431.It Dv void freem(void *hdl, void *addr, struct malloc_type *type) 432optional, is called to free memory allocated by 433.Va alloc . 434If not supplied 435.Xr free 9 436is used. 437.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) 438optional, is called at startup to determine the audio 439buffer size. 440The upper layer supplies the suggested size in 441.Va bufsize , 442which the hardware driver can then change if needed. 443E.g., DMA on the ISA bus cannot exceed 65536 bytes. 444.It Dv "paddr_t mappage(void *hdl, void *addr, off_t offs, int prot)" 445.Pp 446optional, is called for 447.Xr mmap 2 . 448Should return the map value for the page at offset 449.Va offs 450from address 451.Va addr 452mapped with protection 453.Va prot . 454Returns -1 on failure, or a machine dependent opaque value 455on success. 456.It Dv int get_props(void *hdl) 457Should return the device properties; i.e., a combination of 458AUDIO_PROP_xxx. 459.It Dv int trigger_output(void *hdl, void *start, void *end, 460.Dv "int blksize, void (*intr)(void*), void *intrarg," 461.Pp 462.Dv "const audio_params_t *param)" 463.Pp 464optional, is called to start the transfer of data from the circular buffer 465delimited by 466.Va start 467and 468.Va end 469to the audio hardware, parameterized as in 470.Va param . 471The call should return when the data transfer has been initiated 472(normally with DMA). 473When the hardware is finished transferring each 474.Va blksize 475sized block, the function 476.Va intr 477should be called with the argument 478.Va intrarg 479(typically from the audio hardware interrupt service routine). 480Once started the transfer may be stopped using 481.Va halt_output . 482Return 0 on success, otherwise an error code. 483.It Dv int trigger_input(void *hdl, void *start, void *end, 484.Dv "int blksize, void (*intr)(void*), void *intrarg," 485.Pp 486.Dv "const audio_params_t *param)" 487.Pp 488optional, is called to start the transfer of data from the audio hardware, 489parameterized as in 490.Va param , 491to the circular buffer delimited by 492.Va start 493and 494.Va end . 495The call should return when the data transfer has been initiated 496(normally with DMA). 497When the hardware is finished transferring each 498.Va blksize 499sized block, the function 500.Va intr 501should be called with the argument 502.Va intrarg 503(typically from the audio hardware interrupt service routine). 504Once started the transfer may be stopped using 505.Va halt_input . 506Return 0 on success, otherwise an error code. 507.It Dv int dev_ioctl(void *hdl, u_long cmd, void *addr, 508.Pp 509.Dv "int flag, struct lwp *l)" 510.Pp 511optional, is called when an 512.Xr ioctl 2 513is not recognized by the generic audio driver. 514Return 0 on success, otherwise an error code. 515.It Dv int powerstate(void *hdl, int state) 516.Pp 517optional, is called on the first open and last close of the audio 518device. 519.Va state 520may be one of 521.Dv AUDIOPOWER_ON 522or 523.Dv AUDIOPOWER_OFF . 524Returns 0 on success, otherwise an error code. 525.El 526.Pp 527The 528.Va query_devinfo 529method should define certain mixer controls for 530.Dv AUDIO_SETINFO 531to be able to change the port and gain, 532and 533.Dv AUDIO_GETINFO 534to read them, as follows. 535.Pp 536If the record mixer is capable of input from more than one source, 537it should define 538.Dv AudioNsource 539in class 540.Dv AudioCrecord . 541This mixer control should be of type 542.Dv AUDIO_MIXER_ENUM 543or 544.Dv AUDIO_MIXER_SET 545and enumerate the possible input sources. 546Each of the named sources for which the recording level can be set 547should have a control in the 548.Dv AudioCrecord 549class of type 550.Dv AUDIO_MIXER_VALUE , 551except the 552.Qq mixerout 553source is special, 554and will never have its own control. 555Its selection signifies, 556rather, 557that various sources in class 558.Dv AudioCrecord 559will be combined and presented to the single recording output 560in the same fashion that the sources of class 561.Dv AudioCinputs 562are combined and presented to the playback output(s). 563If the overall recording level can be changed, 564regardless of the input source, 565then this control should be named 566.Dv AudioNmaster 567and be of class 568.Dv AudioCrecord . 569.Pp 570Controls for various sources that affect only the playback output, 571as opposed to recording, 572should be in the 573.Dv AudioCinputs 574class, 575as of course should any controls that affect both playback and recording. 576.Pp 577If the play 578mixer is capable of output to more than one destination, 579it should define 580.Dv AudioNselect 581in class 582.Dv AudioCoutputs . 583This mixer control should be of type 584.Dv AUDIO_MIXER_ENUM 585or 586.Dv AUDIO_MIXER_SET 587and enumerate the possible destinations. 588For each of the named destinations for which the output level can be set, 589there should be 590a control in the 591.Dv AudioCoutputs 592class of type 593.Dv AUDIO_MIXER_VALUE . 594If the overall output level can be changed, 595which is invariably the case, 596then this control should be named 597.Dv AudioNmaster 598and be of class 599.Dv AudioCoutputs . 600.Pp 601There's one additional source recognized specially by 602.Dv AUDIO_SETINFO 603and 604.Dv AUDIO_GETINFO , 605to be presented as monitor_gain, 606and that is a control named 607.Dv AudioNmonitor , 608of class 609.Dv AudioCmonitor . 610.Sh SEE ALSO 611.Xr audio 4 612.Sh HISTORY 613This 614.Nm 615interface first appeared in 616.Nx 1.3 . 617