1*4882a593Smuzhiyun=================== 2*4882a593SmuzhiyunASoC jack detection 3*4882a593Smuzhiyun=================== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunALSA has a standard API for representing physical jacks to user space, 6*4882a593Smuzhiyunthe kernel side of which can be seen in include/sound/jack.h. ASoC 7*4882a593Smuzhiyunprovides a version of this API adding two additional features: 8*4882a593Smuzhiyun 9*4882a593Smuzhiyun - It allows more than one jack detection method to work together on one 10*4882a593Smuzhiyun user visible jack. In embedded systems it is common for multiple 11*4882a593Smuzhiyun to be present on a single jack but handled by separate bits of 12*4882a593Smuzhiyun hardware. 13*4882a593Smuzhiyun 14*4882a593Smuzhiyun - Integration with DAPM, allowing DAPM endpoints to be updated 15*4882a593Smuzhiyun automatically based on the detected jack status (eg, turning off the 16*4882a593Smuzhiyun headphone outputs if no headphones are present). 17*4882a593Smuzhiyun 18*4882a593SmuzhiyunThis is done by splitting the jacks up into three things working 19*4882a593Smuzhiyuntogether: the jack itself represented by a struct snd_soc_jack, sets of 20*4882a593Smuzhiyunsnd_soc_jack_pins representing DAPM endpoints to update and blocks of 21*4882a593Smuzhiyuncode providing jack reporting mechanisms. 22*4882a593Smuzhiyun 23*4882a593SmuzhiyunFor example, a system may have a stereo headset jack with two reporting 24*4882a593Smuzhiyunmechanisms, one for the headphone and one for the microphone. Some 25*4882a593Smuzhiyunsystems won't be able to use their speaker output while a headphone is 26*4882a593Smuzhiyunconnected and so will want to make sure to update both speaker and 27*4882a593Smuzhiyunheadphone when the headphone jack status changes. 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunThe jack - struct snd_soc_jack 30*4882a593Smuzhiyun============================== 31*4882a593Smuzhiyun 32*4882a593SmuzhiyunThis represents a physical jack on the system and is what is visible to 33*4882a593Smuzhiyunuser space. The jack itself is completely passive, it is set up by the 34*4882a593Smuzhiyunmachine driver and updated by jack detection methods. 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunJacks are created by the machine driver calling snd_soc_jack_new(). 37*4882a593Smuzhiyun 38*4882a593Smuzhiyunsnd_soc_jack_pin 39*4882a593Smuzhiyun================ 40*4882a593Smuzhiyun 41*4882a593SmuzhiyunThese represent a DAPM pin to update depending on some of the status 42*4882a593Smuzhiyunbits supported by the jack. Each snd_soc_jack has zero or more of these 43*4882a593Smuzhiyunwhich are updated automatically. They are created by the machine driver 44*4882a593Smuzhiyunand associated with the jack using snd_soc_jack_add_pins(). The status 45*4882a593Smuzhiyunof the endpoint may configured to be the opposite of the jack status if 46*4882a593Smuzhiyunrequired (eg, enabling a built in microphone if a microphone is not 47*4882a593Smuzhiyunconnected via a jack). 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunJack detection methods 50*4882a593Smuzhiyun====================== 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunActual jack detection is done by code which is able to monitor some 53*4882a593Smuzhiyuninput to the system and update a jack by calling snd_soc_jack_report(), 54*4882a593Smuzhiyunspecifying a subset of bits to update. The jack detection code should 55*4882a593Smuzhiyunbe set up by the machine driver, taking configuration for the jack to 56*4882a593Smuzhiyunupdate and the set of things to report when the jack is connected. 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunOften this is done based on the status of a GPIO - a handler for this is 59*4882a593Smuzhiyunprovided by the snd_soc_jack_add_gpio() function. Other methods are 60*4882a593Smuzhiyunalso available, for example integrated into CODECs. One example of 61*4882a593SmuzhiyunCODEC integrated jack detection can be see in the WM8350 driver. 62*4882a593Smuzhiyun 63*4882a593SmuzhiyunEach jack may have multiple reporting mechanisms, though it will need at 64*4882a593Smuzhiyunleast one to be useful. 65*4882a593Smuzhiyun 66*4882a593SmuzhiyunMachine drivers 67*4882a593Smuzhiyun=============== 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunThese are all hooked together by the machine driver depending on the 70*4882a593Smuzhiyunsystem hardware. The machine driver will set up the snd_soc_jack and 71*4882a593Smuzhiyunthe list of pins to update then set up one or more jack detection 72*4882a593Smuzhiyunmechanisms to update that jack based on their current status. 73