Documentation/sound/designs/jack-injection.rst

   1 ============================
   2 ALSA Jack Software Injection
   3 ============================
   4
   5 Simple Introduction On Jack Injection
   6 =====================================
   7
   8 Here jack injection means users could inject plugin or plugout events
   9 to the audio jacks through debugfs interface, it is helpful to
  10 validate ALSA userspace changes. For example, we change the audio
  11 profile switching code in the pulseaudio, and we want to verify if the
  12 change works as expected and if the change introduce the regression,
  13 in this case, we could inject plugin or plugout events to an audio
  14 jack or to some audio jacks, we don't need to physically access the
  15 machine and plug/unplug physical devices to the audio jack.
  16
  17 In this design, an audio jack doesn't equal to a physical audio jack.
  18 Sometimes a physical audio jack contains multi functions, and the
  19 ALSA driver creates multi ``jack_kctl`` for a ``snd_jack``, here the
  20 ``snd_jack`` represents a physical audio jack and the ``jack_kctl``
  21 represents a function, for example a physical jack has two functions:
  22 headphone and mic_in, the ALSA ASoC driver will build 2 ``jack_kctl``
  23 for this jack. The jack injection is implemented based on the
  24 ``jack_kctl`` instead of ``snd_jack``.
  25
  26 To inject events to audio jacks, we need to enable the jack injection
  27 via ``sw_inject_enable`` first, once it is enabled, this jack will not
  28 change the state by hardware events anymore, we could inject plugin or
  29 plugout events via ``jackin_inject`` and check the jack state via
  30 ``status``, after we finish our test, we need to disable the jack
  31 injection via ``sw_inject_enable`` too, once it is disabled, the jack
  32 state will be restored according to the last reported hardware events
  33 and will change by future hardware events.
  34
  35 The Layout of Jack Injection Interface
  36 ======================================
  37
  38 If users enable the SND_JACK_INJECTION_DEBUG in the kernel, the audio
  39 jack 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
  83 The Explanation Of The Nodes
  84 ======================================
  85
  86 kctl_id
  87   read-only, get jack_kctl->kctl's id
  88   ::
  89
  90      sound/card1/Headphone_Jack# cat kctl_id
  91      Headphone Jack
  92
  93 mask_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
 100 status
 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
 117 type
 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
 124 sw_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
 153 jackin_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