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