share/man/man9/audio.9

   1 .\"     $NetBSD: audio.9,v 1.41 2008/04/25 14:16:05 mjf 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
  37 The audio device driver is divided into a high level,
  38 hardware independent layer, and a low level hardware
  39 dependent layer.
  40 The interface between these is the
  41 .Va audio_hw_if
  42 structure.
  43 .Bd -literal
  44 struct 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
  95 typedef 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
 104 The high level audio driver attaches to the low level driver
 105 when the latter calls
 106 .Va audio_attach_mi .
 107 This 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
 116 The
 117 .Va audio_hw_if
 118 struct is as shown above.
 119 The
 120 .Va hdl
 121 argument is a handle to some low level data structure.
 122 It is sent as the first argument to all the functions
 123 in
 124 .Va audio_hw_if
 125 when the high level driver calls them.
 126 .Va dev
 127 is the device struct for the hardware device.
 128 .Pp
 129 The upper layer of the audio driver allocates one buffer for playing
 130 and one for recording.
 131 It handles the buffering of data from the user processes in these.
 132 The data is presented to the lower level in smaller chunks, called blocks.
 133 If, during playback, there is no data available from the user process when
 134 the hardware request another block a block of silence will be used instead.
 135 Furthermore, if the user process does not read data quickly enough during
 136 recording data will be thrown away.
 137 .Pp
 138 The fields of
 139 .Va audio_hw_if
 140 are described in some more detail below.
 141 Some 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)
 144 optional, is called when the audio device is opened.
 145 It should initialize the hardware for I/O.
 146 Every successful call to
 147 .Va open
 148 is matched by a call to
 149 .Va close .
 150 Return 0 on success, otherwise an error code.
 151 .It Dv void close(void *hdl)
 152 optional, is called when the audio device is closed.
 153 .It Dv int drain(void *hdl)
 154 optional, is called before the device is closed or when
 155 .Dv AUDIO_DRAIN
 156 is called.
 157 It should make sure that no samples remain in to be played that could
 158 be lost when
 159 .Va close
 160 is called.
 161 Return 0 on success, otherwise an error code.
 162 .It Dv int query_encoding(void *hdl, struct audio_encoding *ae)
 163 is used when
 164 .Dv AUDIO_GETENC
 165 is called.
 166 It should fill the
 167 .Va audio_encoding
 168 structure and return 0 or, if there is no encoding with the
 169 given 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
 175 Called to set the audio encoding mode.
 176 .Va setmode
 177 is a combination of the
 178 .Dv AUMODE_RECORD
 179 and
 180 .Dv AUMODE_PLAY
 181 flags to indicate which mode(s) are to be set.
 182 .Va usemode
 183 is also a combination of these flags, but indicates the current
 184 mode of the device (i.e., the value of
 185 .Va mode
 186 in the
 187 .Va audio_info
 188 struct).
 189 .Pp
 190 The
 191 .Va play
 192 and
 193 .Va rec
 194 structures contain the encoding parameters that should be set.
 195 The values of the structures may also be modified if the hardware
 196 cannot be set to exactly the requested mode (e.g., if the requested
 197 sampling rate is not supported, but one close enough is).
 198 .Pp
 199 If 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
 202 for playing or
 203 .Va rfil
 204 for recording with conversion information.
 205 For example, if
 206 .Va play
 207 requests [8000Hz, mu-law, 8/8bit, 1ch] and the hardware does not
 208 support 8bit mu-law, but 16bit slinear_le, the driver should call
 209 .Dv pfil-\*[Gt]append()
 210 with
 211 .Va pfil ,
 212 .Va mulaw_to_slinear16 ,
 213 and audio_params_t representing [8000Hz, slinear_le, 16/16bit, 2ch].
 214 If the driver needs multiple conversions, a conversion nearest to the
 215 hardware should be set to the head of
 216 .Va pfil
 217 or
 218 .Va rfil .
 219 The definition of
 220 .Dv stream_filter_list_t
 221 follows:
 222 .Bd -literal
 223 typedef 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
 242 For playing,
 243 .Va pfil
 244 constructs 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
 257 For recording,
 258 .Va rfil
 259 constructs 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
 272 If the device does not have the
 273 .Dv AUDIO_PROP_INDEPENDENT
 274 property the same value is passed in both
 275 .Va play
 276 and
 277 .Va rec
 278 and the encoding parameters from
 279 .Va play
 280 is copied into
 281 .Va rec
 282 after the call to
 283 .Va set_params .
 284 Return 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
 288 optional, is called with the block size,
 289 .Va bs ,
 290 that has been computed by the upper layer,
 291 .Va mode ,
 292 .Dv AUMODE_PLAY
 293 or
 294 .Dv AUMODE_RECORD ,
 295 and
 296 .Va param ,
 297 encoding parameters for the hardware.
 298 It should return a block size, possibly changed according to the needs
 299 of the hardware driver.
 300 .It Dv int commit_settings(void *hdl)
 301 optional, is called after all calls to
 302 .Va set_params ,
 303 and
 304 .Va set_port ,
 305 are done.
 306 A hardware driver that needs to get the hardware in and out of command
 307 mode for each change can save all the changes during previous calls and
 308 do them all here.
 309 Return 0 on success, otherwise an error code.
 310 .It Dv int init_output(void *hdl, void *buffer, int size)
 311 optional, is called before any output starts, but when the total
 312 .Va size
 313 of the output
 314 .Va buffer
 315 has been determined.
 316 It can be used to initialize looping DMA for hardware that needs that.
 317 Return 0 on success, otherwise an error code.
 318 .It Dv int init_input(void *hdl, void *buffer, int size)
 319 optional, is called before any input starts, but when the total
 320 .Va size
 321 of the input
 322 .Va buffer
 323 has been determined.
 324 It can be used to initialize looping DMA for hardware that needs that.
 325 Return 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
 329 is called to start the transfer of
 330 .Va blksize
 331 bytes from
 332 .Va block
 333 to the audio hardware.
 334 The call should return when the data transfer has been initiated
 335 (normally with DMA).
 336 When the hardware is ready to accept more samples the function
 337 .Va intr
 338 should be called with the argument
 339 .Va intrarg .
 340 Calling
 341 .Va intr
 342 will normally initiate another call to
 343 .Va start_output .
 344 Return 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
 348 is called to start the transfer of
 349 .Va blksize
 350 bytes to
 351 .Va block
 352 from the audio hardware.
 353 The call should return when the data transfer has been initiated
 354 (normally with DMA).
 355 When the hardware is ready to deliver more samples the function
 356 .Va intr
 357 should be called with the argument
 358 .Va intrarg .
 359 Calling
 360 .Va intr
 361 will normally initiate another call to
 362 .Va start_input .
 363 Return 0 on success, otherwise an error code.
 364 .It Dv int halt_output(void *hdl)
 365 is called to abort the output transfer (started by
 366 .Va start_output )
 367 in progress.
 368 Return 0 on success, otherwise an error code.
 369 .It Dv int halt_input(void *hdl)
 370 is called to abort the input transfer (started by
 371 .Va start_input )
 372 in progress.
 373 Return 0 on success, otherwise an error code.
 374 .It Dv int speaker_ctl(void *hdl, int on)
 375 optional, is called when a half duplex device changes between
 376 playing and recording.
 377 It can, e.g., be used to turn on
 378 and off the speaker.
 379 Return 0 on success, otherwise an error code.
 380 .It Dv int getdev(void *hdl, struct audio_device *ret)
 381 Should fill the
 382 .Va audio_device
 383 struct with relevant information about the driver.
 384 Return 0 on success, otherwise an error code.
 385 .It Dv int setfd(void *hdl, int fd)
 386 optional, is called when
 387 .Dv AUDIO_SETFD
 388 is used, but only if the device has AUDIO_PROP_FULLDUPLEX set.
 389 Return 0 on success, otherwise an error code.
 390 .It Dv int set_port(void *hdl, mixer_ctrl_t *mc)
 391 is called in when
 392 .Dv AUDIO_MIXER_WRITE
 393 is used.
 394 It should take data from the
 395 .Va mixer_ctrl_t
 396 struct at set the corresponding mixer values.
 397 Return 0 on success, otherwise an error code.
 398 .It Dv int get_port(void *hdl, mixer_ctrl_t *mc)
 399 is called in when
 400 .Dv AUDIO_MIXER_READ
 401 is used.
 402 It should fill the
 403 .Va mixer_ctrl_t
 404 struct.
 405 Return 0 on success, otherwise an error code.
 406 .It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di)
 407 is called in when
 408 .Dv AUDIO_MIXER_DEVINFO
 409 is used.
 410 It should fill the
 411 .Va mixer_devinfo_t
 412 struct.
 413 Return 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
 416 optional, is called to allocate the device buffers.
 417 If not present
 418 .Xr malloc 9
 419 is used instead (with the same arguments but the first two).
 420 The reason for using a device dependent routine instead of
 421 .Xr malloc 9
 422 is that some buses need special allocation to do DMA.
 423 Returns the address of the buffer, or 0 on failure.
 424 .It Dv void freem(void *hdl, void *addr, struct malloc_type *type)
 425 optional, is called to free memory allocated by
 426 .Va alloc .
 427 If not supplied
 428 .Xr free 9
 429 is used.
 430 .It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize)
 431 optional, is called at startup to determine the audio
 432 buffer size.
 433 The upper layer supplies the suggested size in
 434 .Va bufsize ,
 435 which the hardware driver can then change if needed.
 436 E.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
 439 optional, is called for
 440 .Xr mmap 2 .
 441 Should return the map value for the page at offset
 442 .Va offs
 443 from address
 444 .Va addr
 445 mapped with protection
 446 .Va prot .
 447 Returns -1 on failure, or a machine dependent opaque value
 448 on success.
 449 .It Dv int get_props(void *hdl)
 450 Should return the device properties; i.e., a combination of
 451 AUDIO_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
 457 optional, is called to start the transfer of data from the circular buffer
 458 delimited by
 459 .Va start
 460 and
 461 .Va end
 462 to the audio hardware, parameterized as in
 463 .Va param .
 464 The call should return when the data transfer has been initiated
 465 (normally with DMA).
 466 When the hardware is finished transferring each
 467 .Va blksize
 468 sized block, the function
 469 .Va intr
 470 should be called with the argument
 471 .Va intrarg
 472 (typically from the audio hardware interrupt service routine).
 473 Once started the transfer may be stopped using
 474 .Va halt_output .
 475 Return 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
 481 optional, is called to start the transfer of data from the audio hardware,
 482 parameterized as in
 483 .Va param ,
 484 to the circular buffer delimited by
 485 .Va start
 486 and
 487 .Va end .
 488 The call should return when the data transfer has been initiated
 489 (normally with DMA).
 490 When the hardware is finished transferring each
 491 .Va blksize
 492 sized block, the function
 493 .Va intr
 494 should be called with the argument
 495 .Va intrarg
 496 (typically from the audio hardware interrupt service routine).
 497 Once started the transfer may be stopped using
 498 .Va halt_input .
 499 Return 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
 504 optional, is called when an
 505 .Xr ioctl 2
 506 is not recognized by the generic audio driver.
 507 Return 0 on success, otherwise an error code.
 508 .It Dv int powerstate(void *hdl, int state)
 509 .Pp
 510 optional, is called on the first open and last close of the audio
 511 device.
 512 .Va state
 513 may be one of
 514 .Dv AUDIOPOWER_ON
 515 or
 516 .Dv AUDIOPOWER_OFF .
 517 Returns 0 on success, otherwise an error code.
 518 .El
 519 .Pp
 520 The
 521 .Va query_devinfo
 522 method should define certain mixer controls for
 523 .Dv AUDIO_SETINFO
 524 to be able to change the port and gain,
 525 and
 526 .Dv AUDIO_GETINFO
 527 to read them, as follows.
 528 .Pp
 529 If the record mixer is capable of input from more than one source,
 530 it should define
 531 .Dv AudioNsource
 532 in class
 533 .Dv AudioCrecord .
 534 This mixer control should be of type
 535 .Dv AUDIO_MIXER_ENUM
 536 or
 537 .Dv AUDIO_MIXER_SET
 538 and enumerate the possible input sources.
 539 Each of the named sources for which the recording level can be set
 540 should have a control in the
 541 .Dv AudioCrecord
 542 class of type
 543 .Dv AUDIO_MIXER_VALUE ,
 544 except the
 545 .Qq mixerout
 546 source is special,
 547 and will never have its own control.
 548 Its selection signifies,
 549 rather,
 550 that various sources in class
 551 .Dv AudioCrecord
 552 will be combined and presented to the single recording output
 553 in the same fashion that the sources of class
 554 .Dv AudioCinputs
 555 are combined and presented to the playback output(s).
 556 If the overall recording level can be changed,
 557 regardless of the input source,
 558 then this control should be named
 559 .Dv AudioNmaster
 560 and be of class
 561 .Dv AudioCrecord .
 562 .Pp
 563 Controls for various sources that affect only the playback output,
 564 as opposed to recording,
 565 should be in the
 566 .Dv AudioCinputs
 567 class,
 568 as of course should any controls that affect both playback and recording.
 569 .Pp
 570 If the play
 571 mixer is capable of output to more than one destination,
 572 it should define
 573 .Dv AudioNselect
 574 in class
 575 .Dv AudioCoutputs .
 576 This mixer control should be of type
 577 .Dv AUDIO_MIXER_ENUM
 578 or
 579 .Dv AUDIO_MIXER_SET
 580 and enumerate the possible destinations.
 581 For each of the named destinations for which the output level can be set,
 582 there should be
 583 a control in the
 584 .Dv AudioCoutputs
 585 class of type
 586 .Dv AUDIO_MIXER_VALUE .
 587 If the overall output level can be changed,
 588 which is invariably the case,
 589 then this control should be named
 590 .Dv AudioNmaster
 591 and be of class
 592 .Dv AudioCoutputs .
 593 .Pp
 594 There's one additional source recognized specially by
 595 .Dv AUDIO_SETINFO
 596 and
 597 .Dv AUDIO_GETINFO ,
 598 to be presented as monitor_gain,
 599 and that is a control named
 600 .Dv AudioNmonitor ,
 601 of class
 602 .Dv AudioCmonitor .
 603 .Sh SEE ALSO
 604 .Xr audio 4
 605 .Sh HISTORY
 606 This
 607 .Nm
 608 interface first appeared in
 609 .Nx 1.3 .