| AUDIO(9) | Kernel Developer's Manual | AUDIO(9) | 
audio —
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 processes 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 succeeded. Closed phase is when no sampling device is opened and it transits 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)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, otherwise an error code.
      It is called in the Closed phase.void
    close(void *hdl)int
    query_format(void *hdl, audio_format_query_t *afp)EINVAL. It can be called at
      any time.
    
typedef struct audio_format_query {
	u_int	index;
	struct audio_format fmt;
} audio_format_query_t;
    
    It is also used by the upper layer to determine the default format, as follows:
AUDIO_ENCODING_SLINEAR_NE:16
          is preferred if exists.AUDIO_ENCODING_SLINEAR_OE:16
          is preferred if exists.If the driver supports SLINEAR_NE:16
        and the upper layer chooses it, the driver does not need to provide a
        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 supports conversion 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_format(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 indicate which modes are to
        be set.
The play and rec
        structures contain the encoding parameters that should be set to the
        hardware. All of these parameters are chosen from formats returned by
        query_format. Therefore play
        and/or rec are always settable. 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 contained in arg. src points to the input buffer block, srcfmt contains 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 the entirety of dst. For example, let count = 100, srcfmt is { precision = 16, channels = 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 necessary.
If the device does not have the
        AUDIO_PROP_INDEPENDENT property the same value
        is passed in both play and
        rec. Returns 0 on success, 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 computed by the upper layer,
        mode, AUMODE_PLAY or
        AUMODE_RECORD, and param,
        encoding parameters for the hardware. bs passed is
        always non-zero and a multiple of the frame size represented by
        param->channels * param->precision / 8. It should return a block
        size, possibly changed according to the needs of the hardware driver.
        The return value also must be non-zero and a multiple of the frame size.
        It is called in the Attach or Closed phases.
int
    commit_settings(void *hdl)int
    init_output(void *hdl, void *buffer, int size)int
    init_input(void *hdl, void *buffer, int size)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 transfer 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. Returns 0 on success, otherwise an error code. This field is optional only if the driver doesn't support playback. 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 transfer 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. Returns 0 on success, otherwise an error code. This field is optional only if the driver doesn't support recording. It is called in the Opened phase.
int
    halt_output(void *hdl)int
    halt_input(void *hdl)int
    speaker_ctl(void *hdl, int on)int
    getdev(void *hdl, struct audio_device *ret)int
    set_port(void *hdl, mixer_ctrl_t *mc)AUDIO_MIXER_WRITE is used. It
      should take data from the mixer_ctrl_t struct and
      set the corresponding mixer values. Returns 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)AUDIO_MIXER_READ is used. It
      should fill the mixer_ctrl_t struct. Returns 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)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)NULL on failure. It is called in the Attached or
      Closed phases.void
    freem(void *hdl, void *addr, size_t size)size_t
    round_buffersize(void *hdl, int direction, size_t bufsize)int
    get_props(void *hdl)AUDIO_PROP_PLAYBACKAUDIO_PROP_CAPTUREAUDIO_PROP_FULLDUPLEXAUDIO_PROP_INDEPENDENTAUDIO_PROP_MMAPint
    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 circular 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 hardware is finished transferring each blksize sized block, the function 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 success, 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 hardware is finished transferring each blksize sized block, the function 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 success, 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)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 recording 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 various 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.
audio interface first appeared in
  NetBSD 1.3.
| February 2, 2021 | NetBSD 10.0 |