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