Kernel Functions for Drivers audio_dev_add_control(9F)
NAME
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 con-
trol functionsSYNOPSIS
#include
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 withaudio_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 */
};SunOS 5.11 Last change: 21 Apr 2010 1
Kernel Functions for Drivers audio_dev_add_control(9F)
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 previouslyreturned by audio_dev_add_control()
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)DESCRIPTION
Controls for audio devices are adjustable values that affectthe operation of the device. The most common use of a con-
trol 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.SunOS 5.11 Last change: 21 Apr 2010 2
Kernel Functions for Drivers audio_dev_add_control(9F)
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 fol-
lowing 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 rightSunOS 5.11 Last change: 21 Apr 2010 3
Kernel Functions for Drivers audio_dev_add_control(9F)
channel is in the 2nd least sig-
nificant 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 selectionsSunOS 5.11 Last change: 21 Apr 2010 4
Kernel Functions for Drivers audio_dev_add_control(9F)
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 exceed255. For enumerations, acd_minvalue indicates enumeration
values that may be changed and acd_maxvalue indicates the
full mask of possible options. It is nonsensical foracd_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 enumera-
tion. The following definitions are available for use and should be used whenever possible.AUDIO_PORT_MIC
AUDIO_PORT_CD
AUDIO_PORT_VIDEO
AUDIO_PORT_AUX1OUT
AUDIO_PORT_AUX2OUT
AUDIO_PORT_LINEOUT
AUDIO_PORT_LINEIN
AUDIO_PORT_AUX1IN
AUDIO_PORT_AUX2IN
AUDIO_PORT_HEADPHONES
AUDIO_PORT_SPDIFIN
AUDIO_PORT_SPDIFOUT
AUDIO_PORT_DIGOUT
AUDIO_PORT_DIGIN
AUDIO_PORT_HDMI
AUDIO_VALUE_ON
AUDIO_VALUE_OFF
AUDIO_VALUE_VERYLOW
AUDIO_VALUE_LOW
AUDIO_VALUE_MEDIUM
AUDIO_VALUE_HIGH
AUDIO_VALUE_VERYHIGH
The readfn() function takes the supplied driver private data as its first argument and a pointer to receive the controlscurrent value as its second argument. It returns 0 on suc-
cess, 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 andSunOS 5.11 Last change: 21 Apr 2010 5
Kernel Functions for Drivers audio_dev_add_control(9F)
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 usingAUDIO_CTRL_ID_VOLUME.
The audio_control_read() function is used by a driver to
call the read function for the control. This can be usefulwhen used with layered systems which override control func-
tions.The audio_control_write() function is used by a driver to
call the write function for the control. This can be usefulwhen used with layered systems that override control func-
tions.RETURN VALUES
The audio_dev_add_control() function returns an opaque han-
dle 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.SunOS 5.11 Last change: 21 Apr 2010 6
Kernel Functions for Drivers audio_dev_add_control(9F)
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 attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
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: o Only one thread will be executing an audio control accessor function for a given audio device at any one time. o No threads will be executing any audio control accessor functions for a given audio device if thatdevice 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 withaudio_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
SunOS 5.11 Last change: 21 Apr 2010 7
Kernel Functions for Drivers audio_dev_add_control(9F)
other controls, the soft volume control is destroyedautomatically during the execution of audio_dev_free().
SunOS 5.11 Last change: 21 Apr 2010 8