[alsa-devel] [PATCH v9 7/7] ALSA: Docs: Add documentation for Jack kcontrols

[Jie Yang]

Add documentation describing Jack embedded kcontrols, and how to
use it on HD-Audio and ASoC case.

Signed-off-by: Jie Yang <yang.jie at intel.com>
---
 Documentation/sound/alsa/Jack-Controls.txt | 49 ++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 Documentation/sound/alsa/Jack-Controls.txt

diff --git a/Documentation/sound/alsa/Jack-Controls.txt b/Documentation/sound/alsa/Jack-Controls.txt
new file mode 100644
index 0000000..c5dd866
--- /dev/null
+++ b/Documentation/sound/alsa/Jack-Controls.txt
@@ -0,0 +1,49 @@
+Why we need kcontrols for Jack?
+===============================
+
+ALSA using kcontrols to export controlling(switch, volume, Mux, ...) to
+user space, e.g. pulseaudio can switch off headphone and switch on
+speaker when no heaphone is pluged in.
+
+For each physical jack, there may be dynamic pluged in/out status which
+upper layer may be interested in. Currently the ALSA jack core registers
+only input devices for each jack registered. These jack input devices
+are not readable by userspace devices that run as non root.
+
+So we create embeded kcontrols for each jack(including phantom jack),
+report jack event via these kcontrols, userspace switch them to ack on
+these event, to implement what they are wanna to.
+
+Combining with ucm machanism, userpace can do fantasic controlling as
+they want to.
+
+Jack and kcontrols
+==================
+
+Each jack will have a kcontrol list, we can create a kcontrol and attach
+it to the jack, at jack creating stage. Also, we can add kcontrol to an
+exist jack, at anytime when you are happy.
+
+Those kcontrols will be freed automatically when the Jack is freed.
+
+How to create kcontrol embedded jack?
+=====================================
+
+To be compatible with previous HD-Audio jack and ASoC jack, we modify
+snd_jack_new() with adding two params:
+
+ - @initial_kctl: create kctl if true, also add it to the non-phantom
+	jack kctl list.
+ - @phantom_jack: for phantom jack, only create needed kctl, won't create
+	input device.
+
+For HDA jack, we can use phantom_jack = true for phantom jack creating,
+and set initial_kctl to true to initial kcontrol with the jack id.
+
+For ASoC jack, usually, we create kcontrols after jack is
+created(calling snd_jack_new() with initial_kctl==false), with
+calling snd_hda_jack_add_kctl() for each jack pins. And, the pin name
+will be assigned to the corresponding kcontrol name. So, to make
+userspace understand and recognize it, please assign proper name for
+each jack pin.
+
-- 
1.9.1