1.\" $NetBSD: audio.9,v 1.58 2020/02/29 05:39:03 isaki 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 May 9, 2019 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 48 int (*query_format)(void *, audio_format_query_t *); 49 int (*set_format)(void *, int, 50 const audio_params_t *, const audio_params_t *, 51 audio_filter_reg_t *, audio_filter_reg_t *); 52 int (*round_blocksize)(void *, int, int, const audio_params_t *); 53 54 int (*commit_settings)(void *); 55 56 int (*init_output)(void *, void *, int); 57 int (*init_input)(void *, void *, int); 58 int (*start_output)(void *, void *, int, void (*)(void *), 59 void *); 60 int (*start_input)(void *, void *, int, void (*)(void *), 61 void *); 62 int (*halt_output)(void *); 63 int (*halt_input)(void *); 64 65 int (*speaker_ctl)(void *, int); 66#define SPKR_ON 1 67#define SPKR_OFF 0 68 69 int (*getdev)(void *, struct audio_device *); 70 71 int (*set_port)(void *, mixer_ctrl_t *); 72 int (*get_port)(void *, mixer_ctrl_t *); 73 74 int (*query_devinfo)(void *, mixer_devinfo_t *); 75 76 void *(*allocm)(void *, int, size_t); 77 void (*freem)(void *, void *, size_t); 78 size_t (*round_buffersize)(void *, int, size_t); 79 80 int (*get_props)(void *); 81 82 int (*trigger_output)(void *, void *, void *, int, 83 void (*)(void *), void *, const audio_params_t *); 84 int (*trigger_input)(void *, void *, void *, int, 85 void (*)(void *), void *, const audio_params_t *); 86 int (*dev_ioctl)(void *, u_long, void *, int, struct lwp *); 87 void (*get_locks)(void *, kmutex_t **, kmutex_t **); 88}; 89 90typedef struct audio_params { 91 u_int sample_rate; /* sample rate */ 92 u_int encoding; /* e.g. mu-law, linear, etc */ 93 u_int precision; /* bits/subframe */ 94 u_int validbits; /* valid bits in a subframe */ 95 u_int channels; /* mono(1), stereo(2) */ 96} audio_params_t; 97.Ed 98.Pp 99The high level audio driver attaches to the low level driver 100when the latter calls 101.Va audio_attach_mi . 102This call should be 103.Bd -literal 104 device_t 105 audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl, device_t dev); 106.Ed 107.Pp 108The 109.Va audio_hw_if 110struct is as shown above. 111The 112.Va hdl 113argument is a handle to some low level data structure. 114It is sent as the first argument to all the functions 115in 116.Va audio_hw_if 117when the high level driver calls them. 118.Va dev 119is the device struct for the hardware device. 120.Pp 121The upper layer of the audio driver allocates one buffer for playing 122and one for recording. 123It handles the buffering of data from the user processes in these. 124The data is presented to the lower level in smaller chunks, called blocks. 125If, during playback, there is no data available from the user process when 126the hardware request another block a block of silence will be used instead. 127Furthermore, if the user process does not read data quickly enough during 128recording data will be thrown away. 129.Pp 130The phase that these functions are called is classified into three. 131Attach phase, Closed phase and Opened phase. 132Attach phase is during device attach and 133it transits to the Closed phase when the attach succeeded. 134Closed phase is when no sampling device is opened and 135it transits to the Opened phase when open succeeded. 136Opened phase is when any sampling device is opened and 137it transits to the Closed phase when close succeeded. 138.Pp 139The fields of 140.Va audio_hw_if 141are described in some more detail below. 142Some fields are optional and can be set to 143.Dv NULL 144if not needed. 145.Bl -tag -width indent 146.It Dv int open(void *hdl, int flags) 147optional, is called when the first device combining playback and recording 148is opened. 149On a full duplex hardware, 150.Dv ( FREAD | FWRITE ) 151is passed to flags. 152On a half duplex hardware, 153.Dv FWRITE 154is passed for playback, or 155.Dv FREAD 156for recording. 157Every successful call to 158.Va open 159is matched by a call to 160.Va close . 161Return 0 on success, otherwise an error code. 162It is called in the Closed phase. 163.It Dv void close(void *hdl) 164optional, is called when the last audio device combining 165playback and recording is closed. 166It is called in the Opened phase. 167.It Dv int query_format(void *hdl, audio_format_query_t *afp) 168is called to enumerate formats supported by the hardware. 169It should fill the 170.Vt audio_format_t 171structure according to given number 172.Va afp->index . 173If there is no format with given number, return 174.Er EINVAL . 175It is called at any time. 176.Bd -literal 177typedef struct audio_format_query { 178 u_int index; 179 struct audio_format fmt; 180} audio_format_query_t; 181.Ed 182.Pp 183It is also used to determine the default format. 184The upper layer chooses the most preferred one as default format by following: 185.Bl -enum 186.It 187Higher priority is preferred (normally 0, the highest is 3, the lowest is 0). 188.It 189.Dv AUDIO_ENCODING_SLINEAR_NE:16 190is preferred if exists. 191.It 192.Dv AUDIO_ENCODING_SLINEAR_OE:16 193is preferred if exists. 194.It 195More channels is preferred. 196.El 197.Pp 198If the driver supports 199.Dv SLINEAR_NE:16 200and the upper layer chooses it, 201the driver does not need to provide conversion function in 202.Va set_format . 203Similarly, if the driver supports 204.Dv SLINEAR_OE:16 205and the upper layer chooses it, 206the driver does not need to provide a conversion function. 207Because the upper layer only supports conversion between 208.Dv SLINEAR_NE:16 209and 210.Dv SLINEAR_OE:16 211for convenience. 212If the upper layer chooses another format, 213the driver needs to provide a conversion function in 214.Va set_format . 215See also 216.Va set_format . 217If the driver can not provide the conversion from/to 218.Dv SLINEAR_NE:16 , 219set priority to \-1. 220It means that the hardware supports this format but the driver does not 221(e.g. AC3), and it will never be chosen. 222.It Dv int set_foramt(void *hdl, int setmode, 223.Dv "const audio_params_t *play, const audio_params_t *rec," 224.Dv "audio_filter_reg_t *pfil, audio_filter_reg_t *rfil)" 225.Pp 226is called to set specified format to the hardware, 227when the device is attached or the hardware format is changed. 228.Va setmode 229is a combination of the 230.Dv AUMODE_RECORD 231and 232.Dv AUMODE_PLAY 233flags to indicate which modes are to be set. 234.Pp 235The 236.Va play 237and 238.Va rec 239structures contain the encoding parameters that should be set to the hardware. 240If the driver has query_format interface, 241all parameters on 242.Va play 243and/or 244.Va rec 245are chosen from formats returned by query_format. 246Therefore 247.Va play 248and/or 249.Va rec 250are always settable. 251If the driver does not have query_format interface, 252the driver has to validate the format. 253If the hardware does not support 254.Dv AUDIO_ENCODING_SLINEAR_{NE,OE}:16 , 255conversion information should be filled the 256.Va pfil 257for playing or 258.Va rfil 259for recording. 260The definition of 261.Vt audio_filter_reg_t 262and a related structure follow: 263.Bd -literal 264typedef struct { 265 const void *src; 266 const audio_format2_t *srcfmt; 267 void *dst; 268 const audio_format2_t *dstfmt; 269 int count; 270 void *context; 271} audio_filter_arg_t; 272 273typedef void(*audio_filter_t)(audio_filter_arg_t *arg); 274 275typedef struct { 276 audio_filter_t codec; 277 void *context; 278} audio_filter_reg_t; 279.Ed 280.Pp 281.Va codec 282is a conversion function and 283.Va context 284is an optional opaque pointer passed to 285.Va codec . 286.Pp 287When 288.Va codec 289is called, all parameters required by 290.Va codec 291are contained in 292.Va arg . 293.Va src 294points to the input buffer block, 295.Va srcfmt 296contains the input encoding parameters, 297.Va dst 298points to the output buffer block and 299.Va dstfmt 300contains the output encoding parameters. 301.Va count 302represents the number of frames to process on this call. 303.Va src 304and 305.Va dst 306are guaranteed to be able to consecutively access number of frames 307specified by 308.Va count. 309.Va codec 310must fill entire 311.Va dst . 312For example, let count = 100, srcfmt is { precision = 16, channels = 3 }, 313dstfmt is { precision = 8, channels = 4 }, 314in this case, 315src block length = 2(bytes) * 3(channels) * 100(frames) = 600 bytes, 316The length to be written to 317.Va dst 318block is 1(byte) * 4(channels) * 100(frames) = 400 bytes. 319.Va codec 320cannot abort the conversion halfway and there is no error reporting mechanism. 321.Va context 322is a opaque pointer that can be used by 323.Va codec 324if necessary. 325.Pp 326If the device does not have the 327.Dv AUDIO_PROP_INDEPENDENT 328property the same value is passed in both 329.Va play 330and 331.Va rec . 332Return 0 on success, otherwise an error code. 333It is called in the Attach or Closed phases. 334.It Dv int round_blocksize(void *hdl, int bs, int mode, 335.Dv "const audio_params_t *param)" 336.Pp 337optional, is called with the block size, 338.Va bs , 339that has been computed by the upper layer, 340.Va mode , 341.Dv AUMODE_PLAY 342or 343.Dv AUMODE_RECORD , 344and 345.Va param , 346encoding parameters for the hardware. 347.Va bs 348passed is always non-zero and a multiple of the frame size represented by 349param->channels * param->precision / 8. 350It should return a block size, possibly changed according to the needs 351of the hardware driver. 352The return value also must be non-zero and a multiple of the frame size. 353It is called in the Attach or Closed phases. 354.It Dv int commit_settings(void *hdl) 355optional, is called after all calls to 356.Va set_params , 357and 358.Va set_port , 359are done. 360A hardware driver that needs to get the hardware in and out of command 361mode for each change can save all the changes during previous calls and 362do them all here. 363Return 0 on success, otherwise an error code. 364It is called in the Attach or Closed phases. 365.It Dv int init_output(void *hdl, void *buffer, int size) 366optional, is called before any output starts, but when the total 367.Va size 368of the output 369.Va buffer 370has been determined. 371It can be used to initialize looping DMA for hardware that needs that. 372Return 0 on success, otherwise an error code. 373It is called in the Attach or Closed phases. 374.It Dv int init_input(void *hdl, void *buffer, int size) 375optional, is called before any input starts, but when the total 376.Va size 377of the input 378.Va buffer 379has been determined. 380It can be used to initialize looping DMA for hardware that needs that. 381Return 0 on success, otherwise an error code. 382It is called in the Attach or Closed phases. 383.It Dv int start_output(void *hdl, void *block, int blksize, 384.Dv "void (*intr)(void*), void *intrarg)" 385.Pp 386is called to start the transfer of 387.Va blksize 388bytes from 389.Va block 390to the audio hardware. 391The call should return when the data transfer has been initiated 392(normally with DMA). 393When the hardware is ready to accept more samples the function 394.Va intr 395should be called with the argument 396.Va intrarg . 397Calling 398.Va intr 399will normally initiate another call to 400.Va start_output . 401Return 0 on success, otherwise an error code. 402This field is optional only if the driver doesn't support playback. 403It is called in the Opened phase. 404.It Dv int start_input(void *hdl, void *block, int blksize, 405.Dv "void (*intr)(void*), void *intrarg)" 406.Pp 407is called to start the transfer of 408.Va blksize 409bytes to 410.Va block 411from the audio hardware. 412The call should return when the data transfer has been initiated 413(normally with DMA). 414When the hardware is ready to deliver more samples the function 415.Va intr 416should be called with the argument 417.Va intrarg . 418Calling 419.Va intr 420will normally initiate another call to 421.Va start_input . 422Return 0 on success, otherwise an error code. 423This field is optional only if the driver doesn't support recording. 424It is called in the Opened phase. 425.It Dv int halt_output(void *hdl) 426is called to abort the output transfer (started by 427.Va start_output ) 428in progress. 429Return 0 on success, otherwise an error code. 430This field is optional only if the driver doesn't support playback. 431It is called in the Opened phase. 432.It Dv int halt_input(void *hdl) 433is called to abort the input transfer (started by 434.Va start_input ) 435in progress. 436Return 0 on success, otherwise an error code. 437This field is optional only if the driver doesn't support recording, 438It is called in the Opened phase. 439.It Dv int speaker_ctl(void *hdl, int on) 440optional, is called when a half duplex device changes between 441playing and recording. 442It can, e.g., be used to turn on 443and off the speaker. 444Return 0 on success, otherwise an error code. 445It is called in the Opened phase. 446.It Dv int getdev(void *hdl, struct audio_device *ret) 447Should fill the 448.Va audio_device 449struct with relevant information about the driver. 450Return 0 on success, otherwise an error code. 451It is called in the Opened phase. 452.It Dv int set_port(void *hdl, mixer_ctrl_t *mc) 453is called in when 454.Dv AUDIO_MIXER_WRITE 455is used. 456It should take data from the 457.Va mixer_ctrl_t 458struct at set the corresponding mixer values. 459Return 0 on success, otherwise an error code. 460It is called in the Opened or Closed phases. 461.It Dv int get_port(void *hdl, mixer_ctrl_t *mc) 462is called in when 463.Dv AUDIO_MIXER_READ 464is used. 465It should fill the 466.Va mixer_ctrl_t 467struct. 468Return 0 on success, otherwise an error code. 469It is called in the Opened or Closed phases. 470.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) 471is called in when 472.Dv AUDIO_MIXER_DEVINFO 473is used. 474It should fill the 475.Va mixer_devinfo_t 476struct. 477Return 0 on success, otherwise an error code. 478It is called at any time. 479.It Dv "void *allocm(void *hdl, int direction, size_t size)" 480optional, is called to allocate the device buffers. 481If not present 482.Xr malloc 9 483is used instead (with the same arguments but the first two). 484The reason for using a device dependent routine instead of 485.Xr malloc 9 486is that some buses need special allocation to do DMA. 487Returns the address of the buffer, or 488.Dv NULL 489on failure. 490It is called in the Attached or Closed phases. 491.It Dv void freem(void *hdl, void *addr, size_t size) 492optional, is called to free memory allocated by 493.Va allocm . 494If not supplied 495.Xr free 9 496is used. 497It is called in the Attached or Closed phases. 498.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) 499optional, is called at startup to determine the audio 500buffer size. 501The upper layer supplies the suggested size in 502.Va bufsize , 503which the hardware driver can then change if needed. 504E.g., DMA on the ISA bus cannot exceed 65536 bytes. 505It is called in the Attached or Closed phases. 506.It Dv int get_props(void *hdl) 507Should return the device properties in a combination of following flags: 508.Pp 509.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact 510.It Dv AUDIO_PROP_PLAYBACK 511the device is capable of audio playback. 512.It Dv AUDIO_PROP_CAPTURE 513the device is capable of audio capture. 514.It Dv AUDIO_PROP_FULLDUPLEX 515the device admits full duplex operation. 516Don't set it if the device is unidirectional. 517.It Dv AUDIO_PROP_INDEPENDENT 518the device can set the playing and recording encoding parameters 519independently. 520Don't set it if the device is unidirectional. 521.It Dv AUDIO_PROP_MMAP 522is handled in the upper layer, so new drivers should not return this property. 523.El 524It is called in the Attach phase. 525.It Dv int trigger_output(void *hdl, void *start, void *end, 526.Dv "int blksize, void (*intr)(void*), void *intrarg," 527.Pp 528.Dv "const audio_params_t *param)" 529.Pp 530optional, is called to start the transfer of data from the circular buffer 531delimited by 532.Va start 533and 534.Va end 535to the audio hardware, parameterized as in 536.Va param . 537The call should return when the data transfer has been initiated 538(normally with DMA). 539When the hardware is finished transferring each 540.Va blksize 541sized block, the function 542.Va intr 543should be called with the argument 544.Va intrarg 545(typically from the audio hardware interrupt service routine). 546Once started the transfer may be stopped using 547.Va halt_output . 548Return 0 on success, otherwise an error code. 549It is called in the Opened phase. 550.It Dv int trigger_input(void *hdl, void *start, void *end, 551.Dv "int blksize, void (*intr)(void*), void *intrarg," 552.Pp 553.Dv "const audio_params_t *param)" 554.Pp 555optional, is called to start the transfer of data from the audio hardware, 556parameterized as in 557.Va param , 558to the circular buffer delimited by 559.Va start 560and 561.Va end . 562The call should return when the data transfer has been initiated 563(normally with DMA). 564When the hardware is finished transferring each 565.Va blksize 566sized block, the function 567.Va intr 568should be called with the argument 569.Va intrarg 570(typically from the audio hardware interrupt service routine). 571Once started the transfer may be stopped using 572.Va halt_input . 573Return 0 on success, otherwise an error code. 574It is called in the Opened phase. 575.It Dv int dev_ioctl(void *hdl, u_long cmd, void *addr, 576.Pp 577.Dv "int flag, struct lwp *l)" 578.Pp 579optional, is called when an 580.Xr ioctl 2 581is not recognized by the generic audio driver. 582Return 0 on success, otherwise an error code. 583It is called in the Opened phase. 584.It Dv void get_locks(void *hdl, kmutex_t **intr, kmutex_t **thread) 585Returns the interrupt and thread locks to the common audio layer. 586It is called in the Attach phase. 587.El 588.Pp 589The 590.Va query_devinfo 591method should define certain mixer controls for 592.Dv AUDIO_SETINFO 593to be able to change the port and gain, 594and 595.Dv AUDIO_GETINFO 596to read them, as follows. 597.Pp 598If the record mixer is capable of input from more than one source, 599it should define 600.Dv AudioNsource 601in class 602.Dv AudioCrecord . 603This mixer control should be of type 604.Dv AUDIO_MIXER_ENUM 605or 606.Dv AUDIO_MIXER_SET 607and enumerate the possible input sources. 608Each of the named sources for which the recording level can be set 609should have a control in the 610.Dv AudioCrecord 611class of type 612.Dv AUDIO_MIXER_VALUE , 613except the 614.Qq mixerout 615source is special, 616and will never have its own control. 617Its selection signifies, 618rather, 619that various sources in class 620.Dv AudioCrecord 621will be combined and presented to the single recording output 622in the same fashion that the sources of class 623.Dv AudioCinputs 624are combined and presented to the playback output(s). 625If the overall recording level can be changed, 626regardless of the input source, 627then this control should be named 628.Dv AudioNmaster 629and be of class 630.Dv AudioCrecord . 631.Pp 632Controls for various sources that affect only the playback output, 633as opposed to recording, 634should be in the 635.Dv AudioCinputs 636class, 637as of course should any controls that affect both playback and recording. 638.Pp 639If the play 640mixer is capable of output to more than one destination, 641it should define 642.Dv AudioNselect 643in class 644.Dv AudioCoutputs . 645This mixer control should be of type 646.Dv AUDIO_MIXER_ENUM 647or 648.Dv AUDIO_MIXER_SET 649and enumerate the possible destinations. 650For each of the named destinations for which the output level can be set, 651there should be 652a control in the 653.Dv AudioCoutputs 654class of type 655.Dv AUDIO_MIXER_VALUE . 656If the overall output level can be changed, 657which is invariably the case, 658then this control should be named 659.Dv AudioNmaster 660and be of class 661.Dv AudioCoutputs . 662.Pp 663There's one additional source recognized specially by 664.Dv AUDIO_SETINFO 665and 666.Dv AUDIO_GETINFO , 667to be presented as monitor_gain, 668and that is a control named 669.Dv AudioNmonitor , 670of class 671.Dv AudioCmonitor . 672.Sh SEE ALSO 673.Xr audio 4 674.Sh HISTORY 675This 676.Nm 677interface first appeared in 678.Nx 1.3 . 679