From: Jaroslav Kysela <perex@perex.cz>
Date: Wed, 31 Aug 2022 14:05:58 +0000 (+0200)
Subject: ucm2: add DEBUG.md
X-Git-Tag: v1.2.8~26
X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=f2d467662cfa3fc14ac055410494b7bdca116360;p=alsa-ucm-conf.git

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
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.
+