1.\" $OpenBSD: audio.9,v 1.23 2014/01/21 03:15:46 schwarze Exp $ 2.\" $NetBSD: audio.9,v 1.14 2000/02/11 22:56:15 kleink Exp $ 3.\" 4.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Lennart Augustsson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: January 21 2014 $ 32.Dt AUDIO 9 33.Os 34.Sh NAME 35.Nm audio 36.Nd interface between low and high level audio drivers 37.Sh DESCRIPTION 38The audio device driver is divided into a high level, 39hardware independent layer, and a low level, hardware 40dependent layer. 41The interface between these is the 42.Va audio_hw_if 43structure. 44.Bd -literal 45struct audio_hw_if { 46 int (*open)(void *, int); 47 void (*close)(void *); 48 int (*drain)(void *); 49 50 int (*query_encoding)(void *, struct audio_encoding *); 51 int (*set_params)(void *, int, int, 52 struct audio_params *, struct audio_params *); 53 int (*round_blocksize)(void *, int); 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, 60 void (*)(void *), void *); 61 int (*start_input)(void *, void *, int, 62 void (*)(void *), 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 *, struct mixer_ctrl *); 74 int (*get_port)(void *, struct mixer_ctrl *); 75 76 int (*query_devinfo)(void *, struct mixer_devinfo *); 77 78 void *(*allocm)(void *, int, size_t, int, int); 79 void (*freem)(void *, void *, int); 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 *, struct audio_params *); 87 int (*trigger_input)(void *, void *, void *, int, 88 void (*)(void *), void *, struct audio_params *); 89 void (*get_default_params)(void *, int, struct audio_params *); 90}; 91 92struct audio_params { 93 u_long sample_rate; /* sample rate */ 94 u_int encoding; /* mu-law, linear, etc */ 95 u_int precision; /* bits/sample */ 96 u_int bps; /* bytes/sample */ 97 u_int msb; /* data alignment */ 98 u_int channels; /* mono(1), stereo(2) */ 99 /* Software en/decode functions, set if SW coding required by HW */ 100 void (*sw_code)(void *, u_char *, int); 101 int factor; /* coding space change */ 102}; 103.Ed 104.Pp 105The high level audio driver attaches to the low level driver 106when the latter calls 107.Fn audio_attach_mi . 108This call is: 109.Bd -literal -offset indent 110struct device * 111audio_attach_mi(struct audio_hw_if *ahwp, void *hdl, 112 struct device *dev); 113.Ed 114.Pp 115The 116.Va audio_hw_if 117struct is as shown above. 118The 119.Fa hdl 120argument is a handle to some low level data structure. 121It is sent as the first argument to all the functions in 122.Fa ahwp 123when the high level driver calls them. 124.Fa dev 125is the device struct for the hardware device. 126.Pp 127The upper layer of the audio driver allocates one buffer for playing 128and one for recording. 129It handles the buffering of data from the user processes in these. 130The data is presented to the lower level in smaller chunks, called blocks. 131During playback, if there is no data available from the user process 132when the hardware requests another block, a block of silence will be 133used instead. 134Similarly, if the user process does not read data quickly enough during 135recording, data will be thrown away. 136.Pp 137The fields of 138.Va audio_hw_if 139are described in some more detail below. 140Some fields are optional and can be set to 141.Dv NULL 142if not needed. 143.Bl -tag -width indent 144.It Fn "int (*open)" "void *hdl" "int flags" 145This function is called when the audio device is opened, with 146.Fa flags 147the kernel representation of flags passed to the 148.Xr open 2 149system call 150.Po 151see 152.Dv OFLAGS 153and 154.Dv FFLAGS 155in 156.In sys/fcntl.h 157.Pc . 158It initializes the hardware for I/O. 159Every successful call to 160.Fn open 161is matched by a call to 162.Fn close . 163This function returns 0 on success, otherwise an error code. 164.It Fn "void (*close)" "void *hdl" 165This function is called when the audio device is closed. 166.It Fn "int (*drain)" "void *hdl" 167This function is optional. 168If supplied, it is called before the device is closed or when the 169.Dv AUDIO_DRAIN 170.Xr ioctl 2 171is called. 172It makes sure that no samples remain to be played that could 173be lost when 174.Fn close 175is called. 176This function returns 0 on success, otherwise an error code. 177.It Fn "int (*query_encoding)" "void *hdl" "struct audio_encoding *ae" 178This function is used when the 179.Dv AUDIO_GETENC 180.Xr ioctl 2 181is called. 182It fills 183.Fa ae 184and returns 0 or, if there is no encoding with the given number, returns 185.Er EINVAL . 186.It Fn "int (*set_params)" "void *hdl" "int setmode" "int usemode" \ 187"struct audio_params *play" "struct audio_params *rec" 188This function is called to set the audio encoding mode. 189.Fa setmode 190is a combination of the 191.Dv AUMODE_RECORD 192and 193.Dv AUMODE_PLAY 194flags to indicate which mode(s) are to be set. 195.Fa usemode 196is also a combination of these flags, but indicates the current 197mode of the device (i.e., the value of 198.Va mode 199in the 200.Va audio_info 201struct). 202The 203.Fa play 204and 205.Fa rec 206structures contain the encoding parameters that will be set. 207If the hardware requires software assistance with some encoding 208(e.g., it might be lacking mu-law support), it will fill the 209.Va sw_code 210and 211.Va factor 212fields of these structures. 213See 214.Pa /usr/src/sys/dev/auconv.h 215for available software support. 216The values of the structures may also be modified if the hardware 217cannot be set to exactly the requested mode (e.g., if the requested 218sampling rate is not supported, but one close enough is). 219If the device does not have the 220.Dv AUDIO_PROP_INDEPENDENT 221property, the same value is passed in both 222.Fa play 223and 224.Fa rec 225and the encoding parameters from 226.Fa play 227are copied into 228.Fa rec 229after the call to 230.Fn set_params . 231.Pp 232The machine independent audio driver does some preliminary parameter checking; 233it verifies that the precision is compatible with the encoding, 234and it translates 235.Dv AUDIO_ENCODING_[US]LINEAR 236to 237.Dv AUDIO_ENCODING_[US]LINEAR_{LE,BE} . 238.Pp 239This function returns 0 on success, otherwise an error code. 240.It Fn "int (*round_blocksize)" "void *hdl" "int bs" 241This function is optional. 242If supplied, it is called with the block size, 243.Fa bs , 244which has been computed by the upper layer. 245It returns a block size, possibly changed according to the needs of the 246hardware driver. 247.It Fn "int (*commit_settings)" "void *hdl" 248This function is optional. 249If supplied, it is called after all calls to 250.Fn set_params 251and 252.Fn set_port 253are done. 254A hardware driver that needs to get the hardware in 255and out of command mode for each change can save all the changes 256during previous calls and do them all here. 257This function returns 0 on success, otherwise an error code. 258.It Fn "int (*init_output)" "void *hdl" "void *buffer" "int size" 259This function is optional. 260If supplied, it is called before any output starts, but only after the total 261.Fa size 262of the output 263.Fa buffer 264has been determined. 265It can be used to initialize looping DMA for hardware that needs it. 266This function returns 0 on success, otherwise an error code. 267.It Fn "int (*init_input)" "void *hdl" "void *buffer" "int size" 268This function is optional. 269If supplied, it is called before any input starts, but only after the total 270.Fa size 271of the input 272.Fa buffer 273has been determined. 274It can be used to initialize looping DMA for hardware that needs it. 275This function returns 0 on success, otherwise an error code. 276.It Fn "int (*start_output)" "void *hdl" "void *block" "int bsize" \ 277"void (*intr)(void *)" "void *intrarg" 278This function is called to start the transfer of 279.Fa bsize 280bytes from 281.Fa block 282to the audio hardware. 283The call returns when the data transfer 284has been initiated (normally with DMA). 285When the hardware is ready to accept more samples the function 286.Fa intr 287will be called with the argument 288.Fa intrarg . 289Calling 290.Fa intr 291will normally initiate another call to 292.Fn start_output . 293This function returns 0 on success, otherwise an error code. 294.It Fn "int (*start_input)" "void *hdl" "void *block" "int bsize" \ 295"void (*intr)(void *)" "void *intrarg" 296This function is called to start the transfer of 297.Fa bsize 298bytes to 299.Fa block 300from the audio hardware. 301The call returns when the data transfer 302has been initiated (normally with DMA). 303When the hardware is ready to deliver more samples the function 304.Fa intr 305will be called with the argument 306.Fa intrarg . 307Calling 308.Fa intr 309will normally initiate another call to 310.Fn start_input . 311This function returns 0 on success, otherwise an error code. 312.It Fn "int (*halt_output)" "void *hdl" 313This function is called to abort the output transfer (started by 314.Fn start_output ) 315in progress. 316This function returns 0 on success, otherwise an error code. 317.It Fn "int (*halt_input)" "void *hdl" 318This function is called to abort the input transfer (started by 319.Fn start_input ) 320in progress. 321This function returns 0 on success, otherwise an error code. 322.It Fn "int (*speaker_ctl)" "void *hdl" "int on" 323This function is optional. 324If supplied, it is called when a half duplex device changes between 325playing and recording. 326It can, e.g., be used to turn the speaker on and off. 327This function returns 0 on success, otherwise an error code. 328.It Fn "int (*getdev)" "void *hdl" "struct audio_device *ret" 329This function fills 330.Fa ret 331with relevant information about the driver and returns 0 on success, 332or it returns an error code on failure. 333.It Fn "int (*setfd)" "void *hdl" "int fd" 334This function is optional. 335If supplied, it is called when the 336.Dv AUDIO_SETFD 337.Xr ioctl 2 338is used, but only if the device has 339.Dv AUDIO_PROP_FULLDUPLEX 340set. 341This function returns 0 on success, otherwise an error code. 342.It Fn "int (*set_port)" "void *hdl" "struct mixer_ctrl *mc" 343This function is called when the 344.Dv AUDIO_MIXER_WRITE 345.Xr ioctl 2 346is used. 347It takes data from 348.Fa mc 349and sets the corresponding mixer values. 350This function returns 0 on success, otherwise an error code. 351.It Fn "int (*get_port)" "void *hdl" "struct mixer_ctrl *mc" 352This function is called when the 353.Dv AUDIO_MIXER_READ 354.Xr ioctl 2 355is used. 356It fills 357.Fa mc 358and returns 0 on success, or it returns an error code on failure. 359.It Fn "int (*query_devinfo)" "void *hdl" "struct mixer_devinfo *di" 360This function is called when the 361.Dv AUDIO_MIXER_DEVINFO 362.Xr ioctl 2 363is used. 364It fills 365.Fa di 366and returns 0 on success, or it returns an error code on failure. 367.It Fn "void *(*allocm)" "void *hdl" "int direction" "size_t size" "int type" \ 368"int flags" 369This function is optional. 370If supplied, it is called to allocate the device buffers. 371If not supplied, 372.Xr malloc 9 373is used instead (with the same arguments but the first two). 374The reason for using a device dependent routine instead of 375.Xr malloc 9 376is that some buses need special allocation to do DMA. 377.Fa direction 378is 379.Dv AUMODE_PLAY 380or 381.Dv AUMODE_RECORD . 382This function returns the address of the buffer on success, or 0 on failure. 383.It Fn "void (*freem)" "void *hdl" "void *addr" "int type" 384This function is optional. 385If supplied, it is called to free memory allocated by 386.Fn allocm . 387If not supplied, 388.Xr free 9 389is used instead. 390.\" XXX: code passes int instead of size_t, but decl is size_t 391.It Fn "size_t (*round_buffersize)" "void *hdl" "int direction" \ 392"size_t bufsize" 393This function is optional. 394If supplied, it is called at startup to determine the audio buffer size. 395The upper layer supplies the suggested size in 396.Fa bufsize , 397which the hardware driver can then change if needed. 398E.g., DMA on the ISA bus cannot exceed 65536 bytes. 399Note that the buffer size is always a multiple of the block size, so 400.Fn round_blocksize 401and 402.Fn round_buffersize 403must be consistent. 404.It Fn "paddr_t (*mappage)" "void *hdl" "void *addr" "off_t offs" "int prot" 405This function is optional. 406If supplied, it is called for 407.Xr mmap 2 . 408It returns the map value for the page at offset 409.Fa offs 410from address 411.Fa addr 412mapped with protection 413.Fa prot . 414This function returns \-1 on failure, or a machine dependent opaque 415value on success. 416.It Fn "int (*get_props)" "void *hdl" 417This function returns the device properties, as per 418.Xr audio 4 419.Dv AUDIO_GETPROPS 420.Xr ioctl 2 , 421i.e., a combination of 422.Dv AUDIO_PROP_xxx 423properties. 424.It Fn "int (*trigger_output)" "void *hdl" "void *start" "void *end" "int blksize" \ 425"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" 426This function is optional. 427If supplied, it is called to start the transfer of data from the circular 428buffer delimited by 429.Fa start 430and 431.Fa end 432to the audio hardware, parameterized as in 433.Fa param . 434The call returns when the data transfer 435has been initiated (normally with DMA). 436When the hardware is finished transferring each 437.Fa blksize 438sized block, the function 439.Fa intr 440will be called with the argument 441.Fa intrarg 442(typically from the audio hardware interrupt service routine). 443Once started, the transfer may be stopped using 444.Fn halt_output . 445This function returns 0 on success, otherwise an error code. 446.It Fn "int (*trigger_input)" "void *hdl" "void *start" "void *end" "int blksize" \ 447"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" 448This function is optional. 449If supplied, it is called to start the transfer of data from the audio 450hardware, parameterized as in 451.Fa param , 452to the circular buffer delimited by 453.Fa start 454and 455.Fa end . 456The call returns when the data transfer 457has been initiated (normally with DMA). 458When the hardware is finished transferring each 459.Fa blksize 460sized block, the function 461.Fa intr 462will be called with the argument 463.Fa intrarg 464(typically from the audio hardware interrupt service routine). 465Once started, the transfer may be stopped using 466.Fn halt_input . 467This function returns 0 on success, otherwise an error code. 468.It Fn "void (*get_default_params)" "void *hdl" "int direction" \ 469"struct audio_params *param" 470This function is optional. 471If supplied, it is called to retrieve the default configuration 472for the given 473.Fa direction , 474parameterized in 475.Fa param . 476.Fa direction 477is 478.Dv AUMODE_PLAY 479or 480.Dv AUMODE_RECORD . 481The default configuration should not include emulated formats, and should 482reflect the optimal operating configuration for the underlying hardware. 483.El 484.Pp 485The 486.Fn query_devinfo 487method should define certain mixer controls for 488.Dv AUDIO_SETINFO 489to be able to change the port and gain. 490.Pp 491If the audio hardware is capable of input from more 492than one source it should define 493.Dv AudioNsource 494in class 495.Dv AudioCrecord . 496This mixer control should be of type 497.Dv AUDIO_MIXER_ENUM 498or 499.Dv AUDIO_MIXER_SET 500and enumerate the possible input sources. 501For each of the named sources there should be 502a control in the 503.Dv AudioCinputs 504class of type 505.Dv AUDIO_MIXER_VALUE 506if recording level of the source can be set. 507If the overall recording level can be changed (i.e., regardless 508of the input source) then this control should be named 509.Dv AudioNrecord 510and be of class 511.Dv AudioCinputs . 512.Pp 513If the audio hardware is capable of output to more than 514one destination it should define 515.Dv AudioNoutput 516in class 517.Dv AudioCmonitor . 518This mixer control should be of type 519.Dv AUDIO_MIXER_ENUM 520or 521.Dv AUDIO_MIXER_SET 522and enumerate the possible destinations. 523For each of the named destinations there should be 524a control in the 525.Dv AudioCoutputs 526class of type 527.Dv AUDIO_MIXER_VALUE 528if output level of the destination can be set. 529If the overall output level can be changed (i.e., regardless 530of the destination) then this control should be named 531.Dv AudioNmaster 532and be of class 533.Dv AudioCoutputs . 534.Sh SEE ALSO 535.Xr ioctl 2 , 536.Xr mmap 2 , 537.Xr open 2 , 538.Xr sio_open 3 , 539.Xr audio 4 , 540.Xr free 9 , 541.Xr malloc 9 542.Sh HISTORY 543This 544.Nm 545interface first appeared in 546.Ox 1.2 . 547