audio_dev_add_control

, audio_dev_del_control

, audio_dev_update_controls

, audio_dev_add_soft_volume

, audio_control_read

, audio_control_write

- audio device control functions

Synopsis

#include <sys/audio/audio_driver.h>

typedef int (*audio_ctrl_wr_t)(void *, uint64_t);
        typedef int (*audio_ctrl_rd_t)(void *, uint64_t *);

audio_ctrl_t *audio_dev_add_control(audio_dev_t *adev,
     audio_ctrl_desc_t *desc, audio_ctrl_rd_t readfn,
     audio_ctrl_wr_t writefn, void *data);

void audio_dev_del_control(audio_ctrl_t *ctrl);

void audio_dev_update_controls(audio_dev_t *adev);

void audio_dev_add_soft_volume(audio_dev_t *adev);

int audio_control_read(audio_ctrl_t *ctrl, uint64_t *valuep);

int audio_control_write(audio_ctrl_t *ctrl, uint64_t value);

Parameters

adev

pointer to an audio device allocated with audio_dev_alloc(9F)

desc

pointer to an structure describing the control. The structure has the following definition:

struct audio_ctrl_desc {
    const char   *acd_name;       /* Controls Mnemonic */
    uint32_t     acd_type;        /* Entry type */
    uint64_t     acd_flags;       /* Characteristics */
    uint64_t     acd_maxvalue;    /* Max value control */
    uint64_t     acd_minvalue;    /* Min value control */
    const char   *acd_enum[64];   /* Enum values */
};

readfn

pointer to a function used to read the value of the control

writefn

pointer to a function used to write the value of the control

data

driver private data pointer passed to read and write functions

ctrl

opaque handle to audio control previously returned by audio_dev_add_control()

Interface Level

Solaris DDI specific (Solaris DDI)

Description

Controls for audio devices are adjustable values that affect the operation of the device. The most common use of a control is to affect volume settings.

The audio_dev_add_control() function registers a control for the audio device and associates handlers with it.

The desc parameter describes the control in more detail. It has the following structure:

struct audio_ctrl_desc {
    const char  *acd_name;      /* Controls Mnemonic */
    uint32_t    acd_type;       /* Entry type */
    uint64_t    acd_flags;      /* Characteristics */
    uint64_t    acd_maxvalue;   /* Max value control */
    uint64_t    acd_minvalue;   /* Min value control */
    const char  *acd_enum[64];  /* Enum values */
};

The acd_name field is a simple ASCII string identifying the control. The convention is to follow the same naming rules as used for C identifiers.

The following predefined control names are available and should be used when possible. Other names may be used, but might not be presented consistently to all users in all locales, so they should be used with caution.

AUDIO_CTRL_ID_VOLUME

Master play back volume

AUDIO_CTRL_ID_LINEOUT

Volume on the line out jack

AUDIO_CTRL_ID_FRONT

Front speaker volume

AUDIO_CTRL_ID_REAR

Rear speaker volume

AUDIO_CTRL_ID_HEADPHONE

Headphone volume

AUDIO_CTRL_ID_CENTER

Center speaker volume

AUDIO_CTRL_ID_LFE

Low-frequency effect volume

AUDIO_CTRL_ID_SPEAKER

Built-in speaker volume

AUDIO_CTRL_ID_MIC

Microphone gain

AUDIO_CTRL_ID_CD

CD input gain

AUDIO_CTRL_ID_LINEIN

Line input gain

AUDIO_CTRL_ID_RECGAIN

Master record gain

AUDIO_CTRL_ID_MONGAIN

Monitor gain

AUDIO_CTRL_ID_RECSRC

Record source

The acd_type field indicates the type of control. The following types are available:

AUDIO_CTRL_TYPE_BOOLEAN

A simple boolean on/off value

AUDIO_CTRL_TYPE_STEREO

A stereophonic control. The value for the right channel is in the low order byte, and for the right channel is in the 2nd least significant byte.

AUDIO_CTRL_TYPE_MONO

A monophonic value

AUDIO_CTRL_TYPE_ENUM

An enumeration

The acd_flags field is a bitmask that provides additional detail about the control. The following bits are defined; all other bits are reserved and must not be set by the driver:

AUDIO_CTRL_FLAG_READABLE

Control readable

AUDIO_CTRL_FLAG_WRITEABLE

Control writable

AUDIO_CTRL_FLAG_RW

Read/writable

AUDIO_CTRL_FLAG_MAINVOL

Main analog volume control

AUDIO_CTRL_FLAG_PCMVOL

PCM output volume

AUDIO_CTRL_FLAG_RECVOL

Record volume

AUDIO_CTRL_FLAG_MONVOL

Monitor volume

AUDIO_CTRL_FLAG_PLAY

Control relates to playback

AUDIO_CTRL_FLAG_REC

Control relates to recording

AUDIO_CTRL_FLAG_MONITOR

Control relates to monitoring

AUDIO_CTRL_FLAG_MULTI

Enumeration is a bitmask that allows multiple selections

The acd_minvalue and acd_maxvalue fields constrain the values that the control can take. For boolean values, they should be 0 and 1. For monophonic and stereophonic controls, they are the values for one channel, and must not exceed 255. For enumerations, acd_minvalue indicates enumeration values that may be changed and acd_maxvalue indicates the full mask of possible options. It is nonsensical for acd_minvalue to have value different from acd_maxvalue if AUDIO_CTRL_FLAG_MULTI is not set. If a bit is present in acd_maxval but not in acd_minvalue, then the corresponding bit must always be set in the value.

The acd_enum field is used with AUDIO_CTRL_TYPE_ENUM and provides ASCII strings identifying each bit in the enumeration. The following definitions are available for use and should be used whenever possible.

The readfn() function takes the supplied driver private data as its first argument and a pointer to receive the controls current value as its second argument. It returns 0 on success, or an errno on failure. It may be called in interrupt context and must not block.

The writefn() function takes the supplied driver private data as its first argument and a new value to set for the control as its second argument. It return 0 on success or an errno on failure. It may be called in interrupt context and must not block.

The data argument is a pointer to driver private state passed as is to the readfn() and writefn() functions.

If a control with the supplied name is already present, the previously associated control is automatically removed and its resources released.

The audio_dev_del_control() function removes the supplied control from the audio device and frees any related resources.

The audio_dev_update_controls() function is called by the audio driver to indicate that the value for one or more of the controls on the audio device has changed asynchronously.

The audio_dev_add_soft_volume() function is used to create a synthetic volume control for the audio device. It can be used for audio devices that lack any physical volume control capability. The control is registered using AUDIO_CTRL_ID_VOLUME.

The audio_control_read() function is used by a driver to call the read function for the control. This can be useful when used with layered systems which override control functions.

The audio_control_write() function is used by a driver to call the write function for the control. This can be useful when used with layered systems that override control functions.

Return Values

The audio_dev_add_control() function returns an opaque handle to the control.

The control read and write functions return 0 on success or an error number on failure.

Context

The audio_dev_add_control(), audio_dev_del_control(), and audio_dev_add_soft_volume() functions may be called from user or kernel context only.

The audio_dev_update_controls(), audio_control_read(), and audio_control_write() functions can be called from user, kernel, or interrupt context.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

attributes(5), audio(7D), audio_dev_alloc(9F), audio_dev_register(9F), audio_dev_suspend(9F)

Notes

The audio framework provides the following synchronization guarantees for audio controls:

• Only one thread will be executing an audio control accessor function for a given audio device at any one time.

• No threads will be executing any audio control accessor functions for a given audio device if that device is suspended. See audio_dev_suspend(9F).

Each control must have a unique name. An attempt to register a control with a name that is already in use will overwrite the previous control and return the same handle that was obtained originally. This can be used to reconfigure the settings of a control. However, care must be taken to ensure that the control is only deleted once during cleanup, or else a system crash will probably result.

Any controls added to an audio engine with audio_dev_add_control() must be destroyed with audio_dev_del_control() before the device itself is freed with audio_dev_free(9F).

If audio_dev_add_soft_volume() is performed for a device, the caller must ensure that no AUDIO_CTRL_ID_VOLUME controls are created for it using audio_dev_add_control(). Unlike other controls, the soft volume control is destroyed automatically during the execution of audio_dev_free().