From 8f6fef8b1a7d6bebc7ebbd610bbf9dc04c919a2b Mon Sep 17 00:00:00 2001
From: Jaroslav Kysela <perex@perex.cz>
Date: Wed, 19 Mar 2025 12:05:26 +0100
Subject: [PATCH] ucm: enhance documentation (sys-card + ranges + more)

Signed-off-by: Jaroslav Kysela <perex@perex.cz>
---
 src/ucm/ucm_confdoc.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/ucm/ucm_confdoc.h b/src/ucm/ucm_confdoc.h
index 5002a2dc..bbfbd92f 100644
--- a/src/ucm/ucm_confdoc.h
+++ b/src/ucm/ucm_confdoc.h
@@ -401,6 +401,7 @@ ${CardLongName}        | ALSA card long name (see snd_ctl_card_info_get_longname
 ${CardComponents}      | ALSA card components (see snd_ctl_card_info_get_components())
 ${env:\<str\>}         | Environment variable \<str\>
 ${sys:\<str\>}         | Contents of sysfs file \<str\>
+${sys-card:\<str\>}    | Contents of sysfs file in /sys/class/sound/card? tree [**Syntax 8**]
 ${var:\<str\>}         | UCM parser variable (set using a _Define_ block)
 ${eval:\<str\>}        | Evaluate expression like *($var+2)/3* [**Syntax 5**]
 ${find-card:\<str\>}   | Find a card - see _Find card substitution_ section
@@ -408,6 +409,32 @@ ${find-device:\<str\>} | Find a device - see _Find device substitution_ section
 @@LibraryVersion       | e.g. "1.2.14" [**Syntax 8**]
 @@SyntaxVersion        | e.g. "8" [**Syntax 8**]
 
+General note: If two dollars '$$' instead one dolar '$' are used for the
+substitution identification, the error is ignored (e.g. file does not
+exists in sysfs tree).
+
+Note for *var* substitution: If the first characters is minus ('-') the
+empty string is substituted when the variable is not defined.
+
+Note for *sys* and *sys-card* substitutions: since syntax 8, there is
+also extension to fetch data from given range with the optional conversion
+to hexadecimal format when the source file has binary contents.
+
+Example - fetch bytes from positions 0x10..0x15 (6 bytes):
+
+~~~{.html}
+Define.Bytes1 "${sys-card:[type=hex,pos=0x10,size=6]device/../descriptors}"
+~~~
+
+Example - fetch one byte from position 0x22:
+
+~~~{.html}
+Define.Bytes2 "${sys-card:[type=hex,pos=0x22]device/../descriptors}"
+~~~
+
+Replace *type=hex* with *type=ascii* or omit this variable settings to work with ASCII characters.
+
+
 #### Special whole string substitution
 
 Substituted string   | Value
-- 
2.47.1