Orange Pi5 kernel

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