AUDIO(9)

📦
version 11.0 · 2 versions
, in nixpkgs unstable

🎧 AUDIO(9) — the audio(9) page, Kernel Developer's Manual ✨

okay bestie, buckle up — this is the manual page for audio(9), and it's literally the whole interface between your low-level and high-level audio drivers 💖

🌸 NAME

audio — the interface between low and high level audio drivers. that's it, that's the vibe 🎀

💅 DESCRIPTION

okay so the audio device driver is split into two whole layers, and yes it's giving main character energy:

  • a high level, hardware independent layer 🔥
  • a low level, hardware dependent layer 🛠

and the thing that lives between them — the glue, the moment, the bridge — is the audio_hw_if structure. here she is, in all her glory:

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 **);
};

and then there's this lil cutie, the params struct 🍓:

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;

🧚 how the layers actually meet

the high level audio driver attaches to the low level driver when the low level driver calls audio_attach_mi. and that call should look exactly like this, no cap:

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

the audio_hw_if struct is the one up there ⬆️. the hdl argument is a handle to some low level data structure — and it gets sent as the first argument to every single function in audio_hw_if whenever the high level driver calls them. dev is the device struct for the hardware device. iykyk 💜

🦋 buffering, aka where your audio actually lives

the upper layer of the audio driver allocates one buffer for playing and one for recording 🌈 and it handles buffering data from the user processes in those. the data gets presented to the lower level in smaller chunks, and those chunks are called blocks.

now the spicy part 🌶 — during playback, if there's no data available from the user process when the hardware requests another block, a block of silence gets used instead. and during recording, if the user process doesn't read data quickly enough, that data gets thrown away. gone. deleted. 💀

🔁 the three phases (vibe check for function calls)

every function call happens in one of three phases — attach phase, closed phase, opened phase. let's break it down:

  1. Attach phase — this is during device attach, and it transits to the Closed phase when the attach succeeded ✨
  2. Closed phase — this is when no sampling device is opened, and it transits to the Opened phase when open succeeded 🫶
  3. Opened phase — this is when any sampling device is opened, and it transits to the Closed phase when close succeeded 🎀

🛠 the fields of audio_hw_if, explained with love

the fields get described in a lil more detail below. and listen — some of these fields are optional and can be set to NULL if you don't need them. no pressure bestie 💅

int open(void *hdl, int flags)

optional! this one's 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 (they're literally soulmates 🫶). return 0 on success, otherwise an error code. it's called in the Closed phase.

void close(void *hdl)

optional too! called when the last audio device combining playback and recording is closed. before this call happens, halt_input and halt_output are called if necessary. it's called in the Opened phase.

int query_format(void *hdl, audio_format_query_t *afp)

this one's called to enumerate the formats the hardware supports 🎨. it should fill the audio_format_t structure according to the given number afp->index. if there's no format with that given number, return 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's also used by the upper layer to figure out the default format, like this:

  1. higher priority is preferred (normally 0, the highest is 3, the lowest is 0)
  2. AUDIO_ENCODING_SLINEAR_NE:16 is preferred if it exists
  3. AUDIO_ENCODING_SLINEAR_OE:16 is preferred if it exists
  4. the format with more channels is preferred

so here's the tea ☕: 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 🎁. but if the upper layer chooses another format, the driver does need to provide a conversion function in set_format. see also set_format below 👀

and if the driver can't provide the conversion from/to SLINEAR_NE:16, set priority to -1. that means the hardware supports this format but the driver does not (e.g. AC3), and it will never be chosen. periodt 💅

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)

called to set a 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, indicating which modes are to be set.

the play and rec structures contain the encoding parameters that should be set to the hardware. and here's the reassuring bit, bestie: all of these parameters are chosen from formats returned by query_format. therefore play and/or rec are always settable ✅

if the hardware doesn't support AUDIO_ENCODING_SLINEAR_{NE,OE}:16, conversion information should be filled into pfil for playing or rfil for recording. the definition of audio_filter_reg_t and its related structure look like this:

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
  • 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 the number of frames specified by count. codec must fill the entirety of dst — no half-jobs, no shortcuts 💅

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, and the length to be written to dst block is 1(byte) * 4(channels) * 100(frames) = 400 bytes.

and here's the serious bit, so listen up 🫶: codec cannot abort the conversion halfway and there is no error reporting mechanism. none. not a single one. so get it right the first time 💀

context is an 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's called in the Attach or Closed phases.

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

optional! 🎈 this gets called with:

  • the block size bs, which has been computed by the upper layer
  • mode, which is AUMODE_PLAY or AUMODE_RECORD
  • param, the encoding parameters for the hardware

and heads up: the bs passed in 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's called in the Attach or Closed phases.

int commit_settings(void *hdl)

optional! called after all the calls to set_format 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 the previous calls and do them all here — one big batch, one big slay ✨ returns 0 on success, otherwise an error code. it's called in the Attach or Closed phases.

int init_output(void *hdl, void *buffer, int size)

optional 🦋 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's called in the Attach or Closed phases.

and that's where part 1 wraps... except no it doesn't, keep reading bestie, there's more coming 💖

  • int init_input(void *hdl, void *buffer, int size) — optional bestie, and it gets called before any input starts, but at the exact moment when the total size of the input buffer has been determined. It's the vibe-setter for hardware that needs looping DMA initialized early. Returns 0 on success, otherwise an error code. Runs in the Attach or Closed phases.
  • int start_output(void *hdl, void *block, int blksize, void (*intr)(void*), void *intrarg) — gets called to start the transfer of blksize bytes from block to the audio hardware 🎧. The call should return once the data transfer has been initiated (normally with DMA, obviously). When the hardware is ready to accept more samples, the function intr should be called with the argument intrarg. And calling intr will normally initiate another call to start_output — yes it's a whole little loop, iykyk 🔁. Returns 0 on success, otherwise an error code. This field is optional only if the driver doesn't support playback. Runs in the Opened phase.
  • int start_input(void *hdl, void *block, int blksize, void (*intr)(void*), void *intrarg) — the ✨mirror image✨: called to start the transfer of blksize bytes to block from the audio hardware. Same deal — the call should return once the data transfer has been initiated (normally with DMA). When the hardware is ready to deliver more samples, 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. Optional only if the driver doesn't support recording. Runs in the Opened phase.
  • int halt_output(void *hdl) — the "stop, babe" button 🛑. Called to abort the output transfer (the one started by start_output) that's currently in progress. Returns 0 on success, otherwise an error code. Optional only if the driver doesn't support playback. Runs in the Opened phase.
  • int halt_input(void *hdl) — same energy for the other direction: aborts the input transfer (started by start_input) in progress. Returns 0 on success, otherwise an error code. Optional only if the driver doesn't support recording. Runs in the Opened phase.
  • int speaker_ctl(void *hdl, int on) — optional! Called when a half duplex device flips between playing and recording 🔀. Classic use case: turning the speaker on and off. Returns 0 on success, otherwise an error code. Runs in the Opened phase.
  • int getdev(void *hdl, struct audio_device *ret) — should fill the audio_device struct with the relevant info about the driver 📋. Returns 0 on success, otherwise an error code. Runs in the Opened phase.
  • int set_port(void *hdl, mixer_ctrl_t *mc) — called in when 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. Runs in the Opened or Closed phases.
  • int get_port(void *hdl, mixer_ctrl_t *mc) — called in when AUDIO_MIXER_READ is used. It should fill the mixer_ctrl_t struct. Returns 0 on success, otherwise an error code. Runs in the Opened or Closed phases.
  • int query_devinfo(void *hdl, mixer_devinfo_t *di) — called in when AUDIO_MIXER_DEVINFO is used. It should fill the mixer_devinfo_t struct. Returns 0 on success, otherwise an error code. This one runs at any time ⏰, main character energy honestly.
  • void *allocm(void *hdl, int direction, size_t size) — optional, called to allocate the device buffers. If it's not present, malloc(9) is used instead (with the same arguments but the first two 👀). The whole reason for 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 failure. Runs in the Attached or Closed phases.
  • void freem(void *hdl, void *addr, size_t size) — optional, called to free memory allocated by allocm. If it's not supplied, free(9) is used. Runs in the Attached or Closed phases.
  • size_t round_buffersize(void *hdl, int direction, size_t bufsize) — optional, 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. Real talk: e.g. DMA on the ISA bus cannot exceed 65536 bytes. Runs in the Attached or Closed phases.
  • int get_props(void *hdl) — should return the device properties as a combination of the 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 unidirectional.
    • AUDIO_PROP_INDEPENDENT — the device can set the playing and recording encoding parameters independently. 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. 💀

Runs 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, 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. Runs 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, the reverse cut 💅: 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, 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. Runs in the Opened phase.
  • int dev_ioctl(void *hdl, u_long cmd, void *addr, int flag, struct lwp *l) — optional, called when an ioctl(2) is not recognized by the generic audio driver. Return 0 on success, otherwise an error code. Runs 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 🔐. Runs in the Attach phase.

🎛️ the mixer-control lore (still DESCRIPTION, we're just deep in it now)

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. That's the whole list, no cap 🧚

👀 SEE ALSO

📜 HISTORY

This audio interface first appeared in NetBSD 1.3. Yes she's an icon, she's a legend, she is the moment 🌟

okay that's the whole page bestie, go forth and write drivers 💖 This one came from the Debian crew and is dated February 2, 2021 — the page itself is AUDIO(9), section 9, and honestly? She ate. 🎀

📦 where this page comes from