diff options
author | Mark Brown <broonie@opensource.wolfsonmicro.com> | 2009-03-27 13:14:52 -0400 |
---|---|---|
committer | Mark Brown <broonie@opensource.wolfsonmicro.com> | 2009-04-02 11:34:20 -0400 |
commit | a7808331f1ea6c7f89a14d1d94eafc62615b997b (patch) | |
tree | dec6cc87f8b9995bd79bc07a0df0ab8d09d3bb5d /Documentation/sound/alsa | |
parent | 6984992bf0520a07b931124d33f46b46437f6e1c (diff) |
ASoC: Add some documentation for the ASoC jack API
A brief overview of how the components of the API fit together.
Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
Diffstat (limited to 'Documentation/sound/alsa')
-rw-r--r-- | Documentation/sound/alsa/soc/jack.txt | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/soc/jack.txt b/Documentation/sound/alsa/soc/jack.txt new file mode 100644 index 000000000000..fcf82a417293 --- /dev/null +++ b/Documentation/sound/alsa/soc/jack.txt | |||
@@ -0,0 +1,71 @@ | |||
1 | ASoC jack detection | ||
2 | =================== | ||
3 | |||
4 | ALSA has a standard API for representing physical jacks to user space, | ||
5 | the kernel side of which can be seen in include/sound/jack.h. ASoC | ||
6 | provides a version of this API adding two additional features: | ||
7 | |||
8 | - It allows more than one jack detection method to work together on one | ||
9 | user visible jack. In embedded systems it is common for multiple | ||
10 | to be present on a single jack but handled by separate bits of | ||
11 | hardware. | ||
12 | |||
13 | - Integration with DAPM, allowing DAPM endpoints to be updated | ||
14 | automatically based on the detected jack status (eg, turning off the | ||
15 | headphone outputs if no headphones are present). | ||
16 | |||
17 | This is done by splitting the jacks up into three things working | ||
18 | together: the jack itself represented by a struct snd_soc_jack, sets of | ||
19 | snd_soc_jack_pins representing DAPM endpoints to update and blocks of | ||
20 | code providing jack reporting mechanisms. | ||
21 | |||
22 | For example, a system may have a stereo headset jack with two reporting | ||
23 | mechanisms, one for the headphone and one for the microphone. Some | ||
24 | systems won't be able to use their speaker output while a headphone is | ||
25 | connected and so will want to make sure to update both speaker and | ||
26 | headphone when the headphone jack status changes. | ||
27 | |||
28 | The jack - struct snd_soc_jack | ||
29 | ============================== | ||
30 | |||
31 | This represents a physical jack on the system and is what is visible to | ||
32 | user space. The jack itself is completely passive, it is set up by the | ||
33 | machine driver and updated by jack detection methods. | ||
34 | |||
35 | Jacks are created by the machine driver calling snd_soc_jack_new(). | ||
36 | |||
37 | snd_soc_jack_pin | ||
38 | ================ | ||
39 | |||
40 | These represent a DAPM pin to update depending on some of the status | ||
41 | bits supported by the jack. Each snd_soc_jack has zero or more of these | ||
42 | which are updated automatically. They are created by the machine driver | ||
43 | and associated with the jack using snd_soc_jack_add_pins(). The status | ||
44 | of the endpoint may configured to be the opposite of the jack status if | ||
45 | required (eg, enabling a built in microphone if a microphone is not | ||
46 | connected via a jack). | ||
47 | |||
48 | Jack detection methods | ||
49 | ====================== | ||
50 | |||
51 | Actual jack detection is done by code which is able to monitor some | ||
52 | input to the system and update a jack by calling snd_soc_jack_report(), | ||
53 | specifying a subset of bits to update. The jack detection code should | ||
54 | be set up by the machine driver, taking configuration for the jack to | ||
55 | update and the set of things to report when the jack is connected. | ||
56 | |||
57 | Often this is done based on the status of a GPIO - a handler for this is | ||
58 | provided by the snd_soc_jack_add_gpio() function. Other methods are | ||
59 | also available, for example integrated into CODECs. One example of | ||
60 | CODEC integrated jack detection can be see in the WM8350 driver. | ||
61 | |||
62 | Each jack may have multiple reporting mechanisms, though it will need at | ||
63 | least one to be useful. | ||
64 | |||
65 | Machine drivers | ||
66 | =============== | ||
67 | |||
68 | These are all hooked together by the machine driver depending on the | ||
69 | system hardware. The machine driver will set up the snd_soc_jack and | ||
70 | the list of pins to update then set up one or more jack detection | ||
71 | mechanisms to update that jack based on their current status. | ||