ucm2: add DEBUG.md

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

diff --git a/ucm2/DEBUG.md b/ucm2/DEBUG.md
new file mode 100644 (file)
index 0000000..97a949a
--- /dev/null
+++ b/ucm2/DEBUG.md
@@ -0,0 +1,95 @@
+Overview
+--------
+
+UCM works on top of the standard ALSA subsystem. If there is something
+missing or non-working, it usually means that UCM describes the devices
+and required control sequences in an incomplete or a wrong way.
+
+It is not required to be a developer to test your hardware.
+
+Useful commands and tools
+-------------------------
+
+````
+alsa-info.sh --no-upload       # dump the system / ALSA state information
+aplay -l                       # dump playback ALSA cards and PCM devices
+arecord -l                     # dump capture ALSA cards and PCM devices
+amixer -c 0 contents           # dump all controls for the ALSA card (zero = card number)
+amixer -c 0 events             # dump events for controls (zero = card number)
+                               # useful for Jack detection
+amixer -c 0 scontents          # dump simple mixer controls for the ALSA card (zero = card number)
+alsamixer -c 0                 # set native ALSA mixer (zero = card number) 
+speaker-test -c hw:CARD=0,DEV=0                         # playback test
+arecord -D hw:CARD=0,DEV=0 -f dat -vvv a.wav     # capture test
+alsaucm -c hw:0 dump text      # dump the UCM configuration (zero = card number)
+spa-acp-tool -vvv -c 0         # pipewire audio profile test tool (zero = card number)
+````
+
+The components for the UCM device
+---------------------------------
+
+1) ALSA PCM device
+2) ALSA Jack control name (optional, if available - for the presence detection)
+3) Simple mixer control name (optional, if available - for the hardware volume control)
+
+Example of the UCM configuration:
+
+````
+Value {
+       PlaybackPCM "hw:${CardId},0"    # equivalent to hw:0,0 (for the first sound card)
+       JackControl "Speakers Jack"     # should be in 'amixer -c 0 contents' dump
+       PlaybackMixerElem "Speaker"     # Speaker bar should be in 'alsamixer -c 0'
+}
+````
+
+Checking of the corresponding ALSA PCM device
+---------------------------------------------
+
+Use `aplay -l` or `capture -l` to list the PCM devices in the system. Pick
+the device numbers for the tested ALSA soundcard and substitute those values
+for the playback test (`speaker-test -c hw:CARD=0,DEV=0`) and capture test
+(`arecord -D hw:CARD=0,DEV=0 -f dat -vvv a.wav`) commands.
+
+Note: If a sound server is running, it should be suspended (see
+`man pasuspender` for an example or manage appropriate services or
+sockets using systemd - systemctl).
+
+Checking of the corresponding ALSA Jack control
+-----------------------------------------------
+
+Use `amixer -c 0 events` (replace zero with the corresponding ALSA card
+number) command and watch '??? Jack' control changes when you plug and
+unplug the correspoding sound equipment to the tested physical jack.
+
+Checking of the corresponding simple mixer name
+-----------------------------------------------
+
+Use `alsamixer -c 0` (replace zero with the corresponding ALSA card
+number) command and try to find the corresponding bar which controls the
+volume when the PCM device is active. It is recommended to open the
+alsamixer tool in a separate terminal window and do the PCM tests in
+another.
+
+Testing changes in the UCM configuration
+----------------------------------------
+
+The sound server must be reloaded to reload the UCM configuration.
+
+To check the configuration syntax, use `alsaucm -c hw:0 dump text` command 
+(replace zero with the corresponding ALSA card number). This command should
+not return an error.
+
+Notes
+-----
+
+Some special hardware (mostly from the ASoC /ALSA SoC/ tree) may require
+special ALSA control initialization sequences. In this case, the driver
+developers should provide the hints.
+
+The `_ucmXXXX.` prefixes in the UCM dumps are referring the private
+ALSA device names - to test those devices, just remove this prefix. It
+will not work for special devices defined only in UCM configuration files.
+If you like to test this special alsa-lib configuration, you may dump the
+alsa-lib configuration using `alsaucm -c hw:0 get _alibcfg` and put the
+configuration to `~/.asoundrc` for example.
+