0001 ===================
0002 ASoC jack detection
0003 ===================
0004
0005 ALSA has a standard API for representing physical jacks to user space,
0006 the kernel side of which can be seen in include/sound/jack.h. ASoC
0007 provides a version of this API adding two additional features:
0008
0009 - It allows more than one jack detection method to work together on one
0010 user visible jack. In embedded systems it is common for multiple
0011 to be present on a single jack but handled by separate bits of
0012 hardware.
0013
0014 - Integration with DAPM, allowing DAPM endpoints to be updated
0015 automatically based on the detected jack status (eg, turning off the
0016 headphone outputs if no headphones are present).
0017
0018 This is done by splitting the jacks up into three things working
0019 together: the jack itself represented by a struct snd_soc_jack, sets of
0020 snd_soc_jack_pins representing DAPM endpoints to update and blocks of
0021 code providing jack reporting mechanisms.
0022
0023 For example, a system may have a stereo headset jack with two reporting
0024 mechanisms, one for the headphone and one for the microphone. Some
0025 systems won't be able to use their speaker output while a headphone is
0026 connected and so will want to make sure to update both speaker and
0027 headphone when the headphone jack status changes.
0028
0029 The jack - struct snd_soc_jack
0030 ==============================
0031
0032 This represents a physical jack on the system and is what is visible to
0033 user space. The jack itself is completely passive, it is set up by the
0034 machine driver and updated by jack detection methods.
0035
0036 Jacks are created by the machine driver calling snd_soc_jack_new().
0037
0038 snd_soc_jack_pin
0039 ================
0040
0041 These represent a DAPM pin to update depending on some of the status
0042 bits supported by the jack. Each snd_soc_jack has zero or more of these
0043 which are updated automatically. They are created by the machine driver
0044 and associated with the jack using snd_soc_jack_add_pins(). The status
0045 of the endpoint may configured to be the opposite of the jack status if
0046 required (eg, enabling a built in microphone if a microphone is not
0047 connected via a jack).
0048
0049 Jack detection methods
0050 ======================
0051
0052 Actual jack detection is done by code which is able to monitor some
0053 input to the system and update a jack by calling snd_soc_jack_report(),
0054 specifying a subset of bits to update. The jack detection code should
0055 be set up by the machine driver, taking configuration for the jack to
0056 update and the set of things to report when the jack is connected.
0057
0058 Often this is done based on the status of a GPIO - a handler for this is
0059 provided by the snd_soc_jack_add_gpio() function. Other methods are
0060 also available, for example integrated into CODECs. One example of
0061 CODEC integrated jack detection can be see in the WM8350 driver.
0062
0063 Each jack may have multiple reporting mechanisms, though it will need at
0064 least one to be useful.
0065
0066 Machine drivers
0067 ===============
0068
0069 These are all hooked together by the machine driver depending on the
0070 system hardware. The machine driver will set up the snd_soc_jack and
0071 the list of pins to update then set up one or more jack detection
0072 mechanisms to update that jack based on their current status.
