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