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
167