AUDIO(9)               NetBSD Kernel Developer's Manual               AUDIO(9)

NAME
     audio -- interface between low and high level audio drivers

DESCRIPTION
     The audio device driver is divided into a high level, hardware indepen-
     dent layer, and a low level hardware dependent layer.  The interface
     between these is the audio_hw_if structure.

     struct audio_hw_if {
             int     (*open)(void *, int);
             void    (*close)(void *);

             int     (*query_format)(void *, audio_format_query_t *);
             int     (*set_format)(void *, int,
                         const audio_params_t *, const audio_params_t *,
                         audio_filter_reg_t *, audio_filter_reg_t *);
             int     (*round_blocksize)(void *, int, int, const audio_params_t *);

             int     (*commit_settings)(void *);

             int     (*init_output)(void *, void *, int);
             int     (*init_input)(void *, void *, int);
             int     (*start_output)(void *, void *, int, void (*)(void *),
                         void *);
             int     (*start_input)(void *, void *, int, void (*)(void *),
                         void *);
             int     (*halt_output)(void *);
             int     (*halt_input)(void *);

             int     (*speaker_ctl)(void *, int);
     #define SPKR_ON  1
     #define SPKR_OFF 0

             int     (*getdev)(void *, struct audio_device *);

             int     (*set_port)(void *, mixer_ctrl_t *);
             int     (*get_port)(void *, mixer_ctrl_t *);

             int     (*query_devinfo)(void *, mixer_devinfo_t *);

             void    *(*allocm)(void *, int, size_t);
             void    (*freem)(void *, void *, size_t);
             size_t  (*round_buffersize)(void *, int, size_t);

             int     (*get_props)(void *);

             int     (*trigger_output)(void *, void *, void *, int,
                         void (*)(void *), void *, const audio_params_t *);
             int     (*trigger_input)(void *, void *, void *, int,
                         void (*)(void *), void *, const audio_params_t *);
             int     (*dev_ioctl)(void *, u_long, void *, int, struct lwp *);
             void    (*get_locks)(void *, kmutex_t **, kmutex_t **);
     };

     typedef struct audio_params {
             u_int   sample_rate;    /* sample rate */
             u_int   encoding;       /* e.g. mu-law, linear, etc */
             u_int   precision;      /* bits/subframe */
             u_int   validbits;      /* valid bits in a subframe */
             u_int   channels;       /* mono(1), stereo(2) */
     } audio_params_t;

     The high level audio driver attaches to the low level driver when the
     latter calls audio_attach_mi.  This call should be

         device_t
         audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl, device_t dev);

     The audio_hw_if struct is as shown above.  The hdl argument is a handle
     to some low level data structure.  It is sent as the first argument to
     all the functions in audio_hw_if when the high level driver calls them.
     dev is the device struct for the hardware device.

     The upper layer of the audio driver allocates one buffer for playing and
     one for recording.  It handles the buffering of data from the user pro-
     cesses in these.  The data is presented to the lower level in smaller
     chunks, called blocks.  If, during playback, there is no data available
     from the user process when the hardware request another block a block of
     silence will be used instead.  Furthermore, if the user process does not
     read data quickly enough during recording data will be thrown away.

     The phase that these functions are called is classified into three.
     Attach phase, Closed phase and Opened phase.  Attach phase is during
     device attach and it transits to the Closed phase when the attach suc-
     ceeded.  Closed phase is when no sampling device is opened and it tran-
     sits to the Opened phase when open succeeded.  Opened phase is when any
     sampling device is opened and it transits to the Closed phase when close
     succeeded.

     The fields of audio_hw_if are described in some more detail below.  Some
     fields are optional and can be set to NULL if not needed.

     int open(void *hdl, int flags)
             optional, is called when the first device combining playback and
             recording is opened.  On a full duplex hardware, (FREAD | FWRITE)
             is passed to flags.  On a half duplex hardware, FWRITE is passed
             for playback, or FREAD for recording.  Every successful call to
             open is matched by a call to close.  Return 0 on success, other-
             wise an error code.  It is called in the Closed phase.

     void close(void *hdl)
             optional, is called when the last audio device combining playback
             and recording is closed.  It is called in the Opened phase.

     int query_format(void *hdl, audio_format_query_t *afp)
             is called to enumerate formats supported by the hardware.  It
             should fill the audio_format_t structure according to given num-
             ber afp->index.  If there is no format with given number, return
             EINVAL.  It is called at any time.

             typedef struct audio_format_query {
                     u_int   index;
                     struct audio_format fmt;
             } audio_format_query_t;

             It is also used to determine the default format.  The upper layer
             chooses the most preferred one as default format by following:

             1.   Higher priority is preferred (normally 0, the highest is 3,
                  the lowest is 0).

             2.   AUDIO_ENCODING_SLINEAR_NE:16 is preferred if exists.

             3.   AUDIO_ENCODING_SLINEAR_OE:16 is preferred if exists.

             4.   More channels is preferred.

             If the driver supports SLINEAR_NE:16 and the upper layer chooses
             it, the driver does not need to provide conversion function in
             set_format.  Similarly, if the driver supports SLINEAR_OE:16 and
             the upper layer chooses it, the driver does not need to provide a
             conversion function.  Because the upper layer only supports con-
             version between SLINEAR_NE:16 and SLINEAR_OE:16 for convenience.
             If the upper layer chooses another format, the driver needs to
             provide a conversion function in set_format.  See also
             set_format.  If the driver can not provide the conversion from/to
             SLINEAR_NE:16, set priority to -1.  It means that the hardware
             supports this format but the driver does not (e.g. AC3), and it
             will never be chosen.

     int set_foramt(void *hdl, int setmode,
             const audio_params_t *play, const audio_params_t *rec,
             audio_filter_reg_t *pfil, audio_filter_reg_t *rfil)

             is called to set specified format to the hardware, when the
             device is attached or the hardware format is changed.  setmode is
             a combination of the AUMODE_RECORD and AUMODE_PLAY flags to indi-
             cate which modes are to be set.

             The play and rec structures contain the encoding parameters that
             should be set to the hardware.  If the driver has query_format
             interface, all parameters on play and/or rec are chosen from for-
             mats returned by query_format.  Therefore play and/or rec are
             always settable.  If the driver does not have query_format inter-
             face, the driver has to validate the format.  If the hardware
             does not support AUDIO_ENCODING_SLINEAR_{NE,OE}:16, conversion
             information should be filled the pfil for playing or rfil for
             recording.  The definition of audio_filter_reg_t and a related
             structure follow:

             typedef struct {
                     const void *src;
                     const audio_format2_t *srcfmt;
                     void *dst;
                     const audio_format2_t *dstfmt;
                     int count;
                     void *context;
             } audio_filter_arg_t;

             typedef void(*audio_filter_t)(audio_filter_arg_t *arg);

             typedef struct {
                     audio_filter_t codec;
                     void *context;
             } audio_filter_reg_t;

             codec is a conversion function and context is an optional opaque
             pointer passed to codec.

             When codec is called, all parameters required by codec are con-
             tained in arg.  src points to the input buffer block, srcfmt con-
             tains the input encoding parameters, dst points to the output
             buffer block and dstfmt contains the output encoding parameters.
             count represents the number of frames to process on this call.
             src and dst are guaranteed to be able to consecutively access
             number of frames specified by count. codec must fill entire dst.
             For example, let count = 100, srcfmt is { precision = 16, chan-
             nels = 3 }, dstfmt is { precision = 8, channels = 4 }, in this
             case, src block length = 2(bytes) * 3(channels) * 100(frames) =
             600 bytes, The length to be written to dst block is 1(byte) *
             4(channels) * 100(frames) = 400 bytes.  codec cannot abort the
             conversion halfway and there is no error reporting mechanism.
             context is a opaque pointer that can be used by codec if neces-
             sary.

             If the device does not have the AUDIO_PROP_INDEPENDENT property
             the same value is passed in both play and rec.  Return 0 on suc-
             cess, otherwise an error code.  It is called in the Attach or
             Closed phases.

     int round_blocksize(void *hdl, int bs, int mode,
             const audio_params_t *param)

             optional, is called with the block size, bs, that has been com-
             puted by the upper layer, mode, AUMODE_PLAY or AUMODE_RECORD, and
             param, encoding parameters for the hardware.  It should return a
             block size, possibly changed according to the needs of the hard-
             ware driver.  It is called in the Attach or Closed phases.

     int commit_settings(void *hdl)
             optional, is called after all calls to set_params, and set_port,
             are done.  A hardware driver that needs to get the hardware in
             and out of command mode for each change can save all the changes
             during previous calls and do them all here.  Return 0 on success,
             otherwise an error code.  It is called in the Attach or Closed
             phases.

     int init_output(void *hdl, void *buffer, int size)
             optional, is called before any output starts, but when the total
             size of the output buffer has been determined.  It can be used to
             initialize looping DMA for hardware that needs that.  Return 0 on
             success, otherwise an error code.  It is called in the Attach or
             Closed phases.

     int init_input(void *hdl, void *buffer, int size)
             optional, is called before any input starts, but when the total
             size of the input buffer has been determined.  It can be used to
             initialize looping DMA for hardware that needs that.  Return 0 on
             success, otherwise an error code.  It is called in the Attach or
             Closed phases.

     int start_output(void *hdl, void *block, int blksize,
             void (*intr)(void*), void *intrarg)

             is called to start the transfer of blksize bytes from block to
             the audio hardware.  The call should return when the data trans-
             fer has been initiated (normally with DMA).  When the hardware is
             ready to accept more samples the function intr should be called
             with the argument intrarg.  Calling intr will normally initiate
             another call to start_output.  Return 0 on success, otherwise an
             error code.  It is called in the Opened phase.

     int start_input(void *hdl, void *block, int blksize,
             void (*intr)(void*), void *intrarg)

             is called to start the transfer of blksize bytes to block from
             the audio hardware.  The call should return when the data trans-
             fer has been initiated (normally with DMA).  When the hardware is
             ready to deliver more samples the function intr should be called
             with the argument intrarg.  Calling intr will normally initiate
             another call to start_input.  Return 0 on success, otherwise an
             error code.  It is called in the Opened phase.

     int halt_output(void *hdl)
             is called to abort the output transfer (started by start_output)
             in progress.  Return 0 on success, otherwise an error code.  It
             is called in the Opened phase.

     int halt_input(void *hdl)
             is called to abort the input transfer (started by start_input) in
             progress.  Return 0 on success, otherwise an error code.  It is
             called in the Opened phase.

     int speaker_ctl(void *hdl, int on)
             optional, is called when a half duplex device changes between
             playing and recording.  It can, e.g., be used to turn on and off
             the speaker.  Return 0 on success, otherwise an error code.  It
             is called in the Opened phase.

     int getdev(void *hdl, struct audio_device *ret)
             Should fill the audio_device struct with relevant information
             about the driver.  Return 0 on success, otherwise an error code.
             It is called in the Opened phase.

     int set_port(void *hdl, mixer_ctrl_t *mc)
             is called in when AUDIO_MIXER_WRITE is used.  It should take data
             from the mixer_ctrl_t struct at set the corresponding mixer val-
             ues.  Return 0 on success, otherwise an error code.  It is called
             in the Opened or Closed phases.

     int get_port(void *hdl, mixer_ctrl_t *mc)
             is called in when AUDIO_MIXER_READ is used.  It should fill the
             mixer_ctrl_t struct.  Return 0 on success, otherwise an error
             code.  It is called in the Opened or Closed phases.

     int query_devinfo(void *hdl, mixer_devinfo_t *di)
             is called in when AUDIO_MIXER_DEVINFO is used.  It should fill
             the mixer_devinfo_t struct.  Return 0 on success, otherwise an
             error code.  It is called at any time.

     void *allocm(void *hdl, int direction, size_t size)
             optional, is called to allocate the device buffers.  If not
             present malloc(9) is used instead (with the same arguments but
             the first two).  The reason for using a device dependent routine
             instead of malloc(9) is that some buses need special allocation
             to do DMA.  Returns the address of the buffer, or NULL on fail-
             ure.  It is called in the Attached or Closed phases.

     void freem(void *hdl, void *addr, size_t size)
             optional, is called to free memory allocated by allocm.  If not
             supplied free(9) is used.  It is called in the Attached or Closed
             phases.

     size_t round_buffersize(void *hdl, int direction, size_t bufsize)
             optional, is called at startup to determine the audio buffer
             size.  The upper layer supplies the suggested size in bufsize,
             which the hardware driver can then change if needed.  E.g., DMA
             on the ISA bus cannot exceed 65536 bytes.  It is called in the
             Attached or Closed phases.

     int get_props(void *hdl)
             Should return the device properties in a combination of following
             flags:

             AUDIO_PROP_PLAYBACK     the device is capable of audio playback.
             AUDIO_PROP_CAPTURE      the device is capable of audio capture.
             AUDIO_PROP_FULLDUPLEX   the device admits full duplex operation.
                                     Don't set it if the device is unidirec-
                                     tional.
             AUDIO_PROP_INDEPENDENT  the device can set the playing and
                                     recording encoding parameters indepen-
                                     dently.  Don't set it if the device is
                                     unidirectional.
             AUDIO_PROP_MMAP         is handled in the upper layer, so new
                                     drivers should not return this property.
             It is called in the Attach phase.

     int trigger_output(void *hdl, void *start, void *end,
             int blksize, void (*intr)(void*), void *intrarg,

             const audio_params_t *param)

             optional, is called to start the transfer of data from the circu-
             lar buffer delimited by start and end to the audio hardware,
             parameterized as in param.  The call should return when the data
             transfer has been initiated (normally with DMA).  When the hard-
             ware is finished transferring each blksize sized block, the func-
             tion intr should be called with the argument intrarg (typically
             from the audio hardware interrupt service routine).  Once started
             the transfer may be stopped using halt_output.  Return 0 on suc-
             cess, otherwise an error code.  It is called in the Opened phase.

     int trigger_input(void *hdl, void *start, void *end,
             int blksize, void (*intr)(void*), void *intrarg,

             const audio_params_t *param)

             optional, is called to start the transfer of data from the audio
             hardware, parameterized as in param, to the circular buffer
             delimited by start and end.  The call should return when the data
             transfer has been initiated (normally with DMA).  When the hard-
             ware is finished transferring each blksize sized block, the func-
             tion intr should be called with the argument intrarg (typically
             from the audio hardware interrupt service routine).  Once started
             the transfer may be stopped using halt_input.  Return 0 on suc-
             cess, otherwise an error code.  It is called in the Opened phase.

     int dev_ioctl(void *hdl, u_long cmd, void *addr,

             int flag, struct lwp *l)

             optional, is called when an ioctl(2) is not recognized by the
             generic audio driver.  Return 0 on success, otherwise an error
             code.  It is called in the Opened phase.

     void get_locks(void *hdl, kmutex_t **intr, kmutex_t **thread)
             Returns the interrupt and thread locks to the common audio layer.
             It is called in the Attach phase.

     The query_devinfo method should define certain mixer controls for
     AUDIO_SETINFO to be able to change the port and gain, and AUDIO_GETINFO
     to read them, as follows.

     If the record mixer is capable of input from more than one source, it
     should define AudioNsource in class AudioCrecord.  This mixer control
     should be of type AUDIO_MIXER_ENUM or AUDIO_MIXER_SET and enumerate the
     possible input sources.  Each of the named sources for which the record-
     ing level can be set should have a control in the AudioCrecord class of
     type AUDIO_MIXER_VALUE, except the "mixerout" source is special, and will
     never have its own control.  Its selection signifies, rather, that vari-
     ous sources in class AudioCrecord will be combined and presented to the
     single recording output in the same fashion that the sources of class
     AudioCinputs are combined and presented to the playback output(s).  If
     the overall recording level can be changed, regardless of the input
     source, then this control should be named AudioNmaster and be of class
     AudioCrecord.

     Controls for various sources that affect only the playback output, as
     opposed to recording, should be in the AudioCinputs class, as of course
     should any controls that affect both playback and recording.

     If the play mixer is capable of output to more than one destination, it
     should define AudioNselect in class AudioCoutputs.  This mixer control
     should be of type AUDIO_MIXER_ENUM or AUDIO_MIXER_SET and enumerate the
     possible destinations.  For each of the named destinations for which the
     output level can be set, there should be a control in the AudioCoutputs
     class of type AUDIO_MIXER_VALUE.  If the overall output level can be
     changed, which is invariably the case, then this control should be named
     AudioNmaster and be of class AudioCoutputs.

     There's one additional source recognized specially by AUDIO_SETINFO and
     AUDIO_GETINFO, to be presented as monitor_gain, and that is a control
     named AudioNmonitor, of class AudioCmonitor.

SEE ALSO
     audio(4)

HISTORY
     This audio interface first appeared in NetBSD 1.3.

NetBSD 8.0                        May 9, 2019                       NetBSD 8.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2019 Modified for NetBSD by Kimmo Suominen