jack-injection.rst

  1============================
  2ALSA Jack Software Injection
  3============================
  4
  5Simple Introduction On Jack Injection
  6=====================================
  7
  8Here jack injection means users could inject plugin or plugout events
  9to the audio jacks through debugfs interface, it is helpful to
 10validate ALSA userspace changes. For example, we change the audio
 11profile switching code in the pulseaudio, and we want to verify if the
 12change works as expected and if the change introduce the regression,
 13in this case, we could inject plugin or plugout events to an audio
 14jack or to some audio jacks, we don't need to physically access the
 15machine and plug/unplug physical devices to the audio jack.
 16
 17In this design, an audio jack doesn't equal to a physical audio jack.
 18Sometimes a physical audio jack contains multi functions, and the
 19ALSA driver creates multi ``jack_kctl`` for a ``snd_jack``, here the
 20``snd_jack`` represents a physical audio jack and the ``jack_kctl``
 21represents a function, for example a physical jack has two functions:
 22headphone and mic_in, the ALSA ASoC driver will build 2 ``jack_kctl``
 23for this jack. The jack injection is implemented based on the
 24``jack_kctl`` instead of ``snd_jack``.
 25
 26To inject events to audio jacks, we need to enable the jack injection
 27via ``sw_inject_enable`` first, once it is enabled, this jack will not
 28change the state by hardware events anymore, we could inject plugin or
 29plugout events via ``jackin_inject`` and check the jack state via
 30``status``, after we finish our test, we need to disable the jack
 31injection via ``sw_inject_enable`` too, once it is disabled, the jack
 32state will be restored according to the last reported hardware events
 33and will change by future hardware events.
 34
 35The Layout of Jack Injection Interface
 36======================================
 37
 38If users enable the SND_JACK_INJECTION_DEBUG in the kernel, the audio
 39jack injection interface will be created as below:
 40::
 41
 42   $debugfs_mount_dir/sound
 43   |-- card0
 44   |-- |-- HDMI_DP_pcm_10_Jack
 45   |-- |-- |-- jackin_inject
 46   |-- |-- |-- kctl_id
 47   |-- |-- |-- mask_bits
 48   |-- |-- |-- status
 49   |-- |-- |-- sw_inject_enable
 50   |-- |-- |-- type
 51   ...
 52   |-- |-- HDMI_DP_pcm_9_Jack
 53   |--     |-- jackin_inject
 54   |--     |-- kctl_id
 55   |--     |-- mask_bits
 56   |--     |-- status
 57   |--     |-- sw_inject_enable
 58   |--     |-- type
 59   |-- card1
 60       |-- HDMI_DP_pcm_5_Jack
 61       |-- |-- jackin_inject
 62       |-- |-- kctl_id
 63       |-- |-- mask_bits
 64       |-- |-- status
 65       |-- |-- sw_inject_enable
 66       |-- |-- type
 67       ...
 68       |-- Headphone_Jack
 69       |-- |-- jackin_inject
 70       |-- |-- kctl_id
 71       |-- |-- mask_bits
 72       |-- |-- status
 73       |-- |-- sw_inject_enable
 74       |-- |-- type
 75       |-- Headset_Mic_Jack
 76           |-- jackin_inject
 77           |-- kctl_id
 78           |-- mask_bits
 79           |-- status
 80           |-- sw_inject_enable
 81           |-- type
 82
 83The Explanation Of The Nodes
 84======================================
 85
 86kctl_id
 87  read-only, get jack_kctl->kctl's id
 88  ::
 89
 90     sound/card1/Headphone_Jack# cat kctl_id
 91     Headphone Jack
 92
 93mask_bits
 94  read-only, get jack_kctl's supported events mask_bits
 95  ::
 96
 97     sound/card1/Headphone_Jack# cat mask_bits
 98     0x0001 HEADPHONE(0x0001)
 99
100status
101  read-only, get jack_kctl's current status
102
103- headphone unplugged:
104
105  ::
106
107     sound/card1/Headphone_Jack# cat status
108     Unplugged
109
110- headphone plugged:
111
112  ::
113
114     sound/card1/Headphone_Jack# cat status
115     Plugged
116
117type
118  read-only, get snd_jack's supported events from type (all supported events on the physical audio jack)
119  ::
120
121     sound/card1/Headphone_Jack# cat type
122     0x7803 HEADPHONE(0x0001) MICROPHONE(0x0002) BTN_3(0x0800) BTN_2(0x1000) BTN_1(0x2000) BTN_0(0x4000)
123
124sw_inject_enable
125  read-write, enable or disable injection
126
127- injection disabled:
128
129  ::
130
131     sound/card1/Headphone_Jack# cat sw_inject_enable
132     Jack: Headphone Jack		Inject Enabled: 0
133
134- injection enabled:
135
136  ::
137
138     sound/card1/Headphone_Jack# cat sw_inject_enable
139     Jack: Headphone Jack		Inject Enabled: 1
140
141- to enable jack injection:
142
143  ::
144
145     sound/card1/Headphone_Jack# echo 1 > sw_inject_enable
146
147- to disable jack injection:
148
149  ::
150
151     sound/card1/Headphone_Jack# echo 0 > sw_inject_enable
152
153jackin_inject
154  write-only, inject plugin or plugout
155
156- to inject plugin:
157
158  ::
159
160     sound/card1/Headphone_Jack# echo 1 > jackin_inject
161
162- to inject plugout:
163
164  ::
165
166     sound/card1/Headphone_Jack# echo 0 > jackin_inject