ALSA: Add kernel-doc comments to vmaster stuff

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: Add kernel-doc comments to vmaster stuff
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Takashi Iwai
1 parent f5b1db6342
Showing 3 changed files with 50 additions and 2 deletions Side-by-side Diff
Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
include/sound/control.h
sound/core/vmaster.c
@@ -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>
@@ -176,12 +176,44 @@
 /* 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)
@@ -340,8 +340,20 @@
 }
  
  
-/*
- * 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)
...	...	@@ -71,6 +71,10 @@
71	71	!Esound/pci/ac97/ac97_codec.c
72	72	!Esound/pci/ac97/ac97_pcm.c
73	73	</sect1>
	74	+ <sect1><title>Virtual Master Control API</title>
	75	+!Esound/core/vmaster.c
	76	+!Iinclude/sound/control.h
	77	+ </sect1>
74	78	</chapter>
75	79	<chapter><title>MIDI API</title>
76	80	<sect1><title>Raw MIDI API</title>
...	...	@@ -176,12 +176,44 @@
176	176	/* optional flags for slave */
177	177	#define SND_CTL_SLAVE_NEED_UPDATE (1 << 0)
178	178
	179	+/**
	180	+ * snd_ctl_add_slave - Add a virtual slave control
	181	+ * @master: vmaster element
	182	+ * @slave: slave element to add
	183	+ *
	184	+ * Add a virtual slave control to the given master element created via
	185	+ * snd_ctl_create_virtual_master() beforehand.
	186	+ * Returns zero if successful or a negative error code.
	187	+ *
	188	+ * All slaves must be the same type (returning the same information
	189	+ * via info callback). The fucntion doesn't check it, so it's your
	190	+ * responsibility.
	191	+ *
	192	+ * Also, some additional limitations:
	193	+ * at most two channels,
	194	+ * logarithmic volume control (dB level) thus no linear volume,
	195	+ * master can only attenuate the volume without gain
	196	+ */
179	197	static inline int
180	198	snd_ctl_add_slave(struct snd_kcontrol master, struct snd_kcontrol slave)
181	199	{
182	200	return _snd_ctl_add_slave(master, slave, 0);
183	201	}
184	202
	203	+/**
	204	+ * snd_ctl_add_slave_uncached - Add a virtual slave control
	205	+ * @master: vmaster element
	206	+ * @slave: slave element to add
	207	+ *
	208	+ * Add a virtual slave control to the given master.
	209	+ * Unlike snd_ctl_add_slave(), the element added via this function
	210	+ * is supposed to have volatile values, and get callback is called
	211	+ * at each time quried from the master.
	212	+ *
	213	+ * When the control peeks the hardware values directly and the value
	214	+ * can be changed by other means than the put callback of the element,
	215	+ * this function should be used to keep the value always up-to-date.
	216	+ */
185	217	static inline int
186	218	snd_ctl_add_slave_uncached(struct snd_kcontrol *master,
187	219	struct snd_kcontrol *slave)
...	...	@@ -340,8 +340,20 @@
340	340	}
341	341
342	342
343		-/*
344		- * Create a virtual master control with the given name
	343	+/**
	344	+ * snd_ctl_make_virtual_master - Create a virtual master control
	345	+ * @name: name string of the control element to create
	346	+ * @tlv: optional TLV int array for dB information
	347	+ *
	348	+ * Creates a virtual matster control with the given name string.
	349	+ * Returns the created control element, or NULL for errors (ENOMEM).
	350	+ *
	351	+ * After creating a vmaster element, you can add the slave controls
	352	+ * via snd_ctl_add_slave() or snd_ctl_add_slave_uncached().
	353	+ *
	354	+ * The optional argument @tlv can be used to specify the TLV information
	355	+ * for dB scale of the master control. It should be a single element
	356	+ * with #SNDRV_CTL_TLVT_DB_SCALE type, and should be the max 0dB.
345	357	*/
346	358	struct snd_kcontrol snd_ctl_make_virtual_master(char name,
347	359	const unsigned int *tlv)