1 =================== 1 ===================
2 ASoC jack detection 2 ASoC jack detection
3 =================== 3 ===================
4 4
5 ALSA has a standard API for representing physi 5 ALSA has a standard API for representing physical jacks to user space,
6 the kernel side of which can be seen in includ 6 the kernel side of which can be seen in include/sound/jack.h. ASoC
7 provides a version of this API adding two addi 7 provides a version of this API adding two additional features:
8 8
9 - It allows more than one jack detection meth 9 - It allows more than one jack detection method to work together on one
10 user visible jack. In embedded systems it 10 user visible jack. In embedded systems it is common for multiple
11 to be present on a single jack but handled 11 to be present on a single jack but handled by separate bits of
12 hardware. 12 hardware.
13 13
14 - Integration with DAPM, allowing DAPM endpoi 14 - Integration with DAPM, allowing DAPM endpoints to be updated
15 automatically based on the detected jack st 15 automatically based on the detected jack status (eg, turning off the
16 headphone outputs if no headphones are pres 16 headphone outputs if no headphones are present).
17 17
18 This is done by splitting the jacks up into th 18 This is done by splitting the jacks up into three things working
19 together: the jack itself represented by a str 19 together: the jack itself represented by a struct snd_soc_jack, sets of
20 snd_soc_jack_pins representing DAPM endpoints 20 snd_soc_jack_pins representing DAPM endpoints to update and blocks of
21 code providing jack reporting mechanisms. 21 code providing jack reporting mechanisms.
22 22
23 For example, a system may have a stereo headse 23 For example, a system may have a stereo headset jack with two reporting
24 mechanisms, one for the headphone and one for 24 mechanisms, one for the headphone and one for the microphone. Some
25 systems won't be able to use their speaker out 25 systems won't be able to use their speaker output while a headphone is
26 connected and so will want to make sure to upd 26 connected and so will want to make sure to update both speaker and
27 headphone when the headphone jack status chang 27 headphone when the headphone jack status changes.
28 28
29 The jack - struct snd_soc_jack 29 The jack - struct snd_soc_jack
30 ============================== 30 ==============================
31 31
32 This represents a physical jack on the system 32 This represents a physical jack on the system and is what is visible to
33 user space. The jack itself is completely pas 33 user space. The jack itself is completely passive, it is set up by the
34 machine driver and updated by jack detection m 34 machine driver and updated by jack detection methods.
35 35
36 Jacks are created by the machine driver callin 36 Jacks are created by the machine driver calling snd_soc_jack_new().
37 37
38 snd_soc_jack_pin 38 snd_soc_jack_pin
39 ================ 39 ================
40 40
41 These represent a DAPM pin to update depending 41 These represent a DAPM pin to update depending on some of the status
42 bits supported by the jack. Each snd_soc_jack 42 bits supported by the jack. Each snd_soc_jack has zero or more of these
43 which are updated automatically. They are cre 43 which are updated automatically. They are created by the machine driver
44 and associated with the jack using snd_soc_jac 44 and associated with the jack using snd_soc_jack_add_pins(). The status
45 of the endpoint may configured to be the oppos 45 of the endpoint may configured to be the opposite of the jack status if
46 required (eg, enabling a built in microphone i 46 required (eg, enabling a built in microphone if a microphone is not
47 connected via a jack). 47 connected via a jack).
48 48
49 Jack detection methods 49 Jack detection methods
50 ====================== 50 ======================
51 51
52 Actual jack detection is done by code which is 52 Actual jack detection is done by code which is able to monitor some
53 input to the system and update a jack by calli 53 input to the system and update a jack by calling snd_soc_jack_report(),
54 specifying a subset of bits to update. The ja 54 specifying a subset of bits to update. The jack detection code should
55 be set up by the machine driver, taking config 55 be set up by the machine driver, taking configuration for the jack to
56 update and the set of things to report when th 56 update and the set of things to report when the jack is connected.
57 57
58 Often this is done based on the status of a GP 58 Often this is done based on the status of a GPIO - a handler for this is
59 provided by the snd_soc_jack_add_gpio() functi 59 provided by the snd_soc_jack_add_gpio() function. Other methods are
60 also available, for example integrated into CO 60 also available, for example integrated into CODECs. One example of
61 CODEC integrated jack detection can be see in 61 CODEC integrated jack detection can be see in the WM8350 driver.
62 62
63 Each jack may have multiple reporting mechanis 63 Each jack may have multiple reporting mechanisms, though it will need at
64 least one to be useful. 64 least one to be useful.
65 65
66 Machine drivers 66 Machine drivers
67 =============== 67 ===============
68 68
69 These are all hooked together by the machine d 69 These are all hooked together by the machine driver depending on the
70 system hardware. The machine driver will set 70 system hardware. The machine driver will set up the snd_soc_jack and
71 the list of pins to update then set up one or 71 the list of pins to update then set up one or more jack detection
72 mechanisms to update that jack based on their 72 mechanisms to update that jack based on their current status.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.