summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTakashi Iwai <tiwai@suse.de>2009-02-09 14:47:19 +0100
committerTakashi Iwai <tiwai@suse.de>2009-03-09 15:10:01 +0100
commit79c7cdd5441f5d3900c1632adcc8cd2bee35c8da (patch)
tree13eec2a208f2d07d05bfb3e33b8869f6adecc2bd
parentf5b1db634280ecaf3147ee996f26aad0ed4828c4 (diff)
ALSA: Add kernel-doc comments to vmaster stuff
Signed-off-by: Takashi Iwai <tiwai@suse.de>
-rw-r--r--Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl4
-rw-r--r--include/sound/control.h32
-rw-r--r--sound/core/vmaster.c16
3 files changed, 50 insertions, 2 deletions
diff --git a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
index 9d644f7e241e..115962827c81 100644
--- a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
+++ b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
@@ -71,6 +71,10 @@
!Esound/pci/ac97/ac97_codec.c
!Esound/pci/ac97/ac97_pcm.c
</sect1>
+ <sect1><title>Virtual Master Control API</title>
+!Esound/core/vmaster.c
+!Iinclude/sound/control.h
+ </sect1>
</chapter>
<chapter><title>MIDI API</title>
<sect1><title>Raw MIDI API</title>
diff --git a/include/sound/control.h b/include/sound/control.h
index 4cf8f7aaa13f..ef96f07aa03b 100644
--- a/include/sound/control.h
+++ b/include/sound/control.h
@@ -176,12 +176,44 @@ int _snd_ctl_add_slave(struct snd_kcontrol *master, struct snd_kcontrol *slave,
/* optional flags for slave */
#define SND_CTL_SLAVE_NEED_UPDATE (1 << 0)
+/**
+ * snd_ctl_add_slave - Add a virtual slave control
+ * @master: vmaster element
+ * @slave: slave element to add
+ *
+ * Add a virtual slave control to the given master element created via
+ * snd_ctl_create_virtual_master() beforehand.
+ * Returns zero if successful or a negative error code.
+ *
+ * All slaves must be the same type (returning the same information
+ * via info callback). The fucntion doesn't check it, so it's your
+ * responsibility.
+ *
+ * Also, some additional limitations:
+ * at most two channels,
+ * logarithmic volume control (dB level) thus no linear volume,
+ * master can only attenuate the volume without gain
+ */
static inline int
snd_ctl_add_slave(struct snd_kcontrol *master, struct snd_kcontrol *slave)
{
return _snd_ctl_add_slave(master, slave, 0);
}
+/**
+ * snd_ctl_add_slave_uncached - Add a virtual slave control
+ * @master: vmaster element
+ * @slave: slave element to add
+ *
+ * Add a virtual slave control to the given master.
+ * Unlike snd_ctl_add_slave(), the element added via this function
+ * is supposed to have volatile values, and get callback is called
+ * at each time quried from the master.
+ *
+ * When the control peeks the hardware values directly and the value
+ * can be changed by other means than the put callback of the element,
+ * this function should be used to keep the value always up-to-date.
+ */
static inline int
snd_ctl_add_slave_uncached(struct snd_kcontrol *master,
struct snd_kcontrol *slave)
diff --git a/sound/core/vmaster.c b/sound/core/vmaster.c
index d51b198d06d9..257624bd1997 100644
--- a/sound/core/vmaster.c
+++ b/sound/core/vmaster.c
@@ -340,8 +340,20 @@ static void master_free(struct snd_kcontrol *kcontrol)
}
-/*
- * Create a virtual master control with the given name
+/**
+ * snd_ctl_make_virtual_master - Create a virtual master control
+ * @name: name string of the control element to create
+ * @tlv: optional TLV int array for dB information
+ *
+ * Creates a virtual matster control with the given name string.
+ * Returns the created control element, or NULL for errors (ENOMEM).
+ *
+ * After creating a vmaster element, you can add the slave controls
+ * via snd_ctl_add_slave() or snd_ctl_add_slave_uncached().
+ *
+ * The optional argument @tlv can be used to specify the TLV information
+ * for dB scale of the master control. It should be a single element
+ * with #SNDRV_CTL_TLVT_DB_SCALE type, and should be the max 0dB.
*/
struct snd_kcontrol *snd_ctl_make_virtual_master(char *name,
const unsigned int *tlv)