fix(ucm): use top-level SectionDevice in HiFi.conf for ALSA parser

Nested SectionVerb caused alsaucm "no use case device defined", so PipeWire
never exposed the HiFi profile. Document alsaucm check and reinstall path.

Made-with: Cursor

docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

@@ -112,6 +112,14 @@ pactl list short sinks
 pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
 ```
 
+**若 `pactl set-card-profile … HiFi` 报「无此实体」**：多半是 **UCM 未成功加载**（WirePlumber 因此注册不出 `HiFi` profile）。先在终端验证 ALSA 能否解析配置：
+
+```bash
+alsaucm -c sof-rt5682 list _verbs
+```
+
+若出现 **`parse_verb_file` / `no use case device defined`** 等，说明 **`HiFi.conf` 结构不符合 UCM2 要求**（已修正为「顶层 `SectionDevice`」写法）；请 **`git pull`** 后重新执行 **`./scripts/install-kaisa-ucm-overlay.sh`**，再 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
+
 **安装（在仓库根目录，需 sudo）**：
 
 ```bash

reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf

@@ -1,86 +1,85 @@
 # Google Kaisa — sof-rt5682 / Intel Kabylake HDMI
-# HDMI 逻辑名与 ALSA device：HDMI1=hw:0,2 HDMI2=hw:0,3 HDMI3=hw:0,4（以本机 aplay -l 为准）
-# 可用性由 JackControl 驱动；IEC958 在 Enable/Disable 时切换。
+# 本文件由 SectionUseCase."HiFi" 引用；须使用顶层 SectionDevice（勿再包一层 SectionVerb），
+# 否则 alsaucm 报「no use case device defined」，PipeWire 不会出现 HiFi profile。
+# HDMI：device 2/3/4；JackControl + IEC958 numid 与本机 amixer 对齐。
 
-SectionVerb."HiFi" {
-    SectionDevice."Port1" {
-        Comment "Analog (Port1)"
+SectionDevice."Port1" {
+    Comment "Analog (Port1)"
 
-        EnableSequence [
-            cset "name='HPOL Playback Switch' 1"
-            cset "name='HPOR Playback Switch' 1"
-            cset "name='Stereo1 DAC MIXL DAC L1 Switch' 1"
-            cset "name='Stereo1 DAC MIXR DAC R1 Switch' 1"
-        ]
+    EnableSequence [
+        cset "name='HPOL Playback Switch' 1"
+        cset "name='HPOR Playback Switch' 1"
+        cset "name='Stereo1 DAC MIXL DAC L1 Switch' 1"
+        cset "name='Stereo1 DAC MIXR DAC R1 Switch' 1"
+    ]
 
-        DisableSequence [
-            cset "name='HPOL Playback Switch' 0"
-            cset "name='HPOR Playback Switch' 0"
-            cset "name='Stereo1 DAC MIXL DAC L1 Switch' 0"
-            cset "name='Stereo1 DAC MIXR DAC R1 Switch' 0"
-        ]
+    DisableSequence [
+        cset "name='HPOL Playback Switch' 0"
+        cset "name='HPOR Playback Switch' 0"
+        cset "name='Stereo1 DAC MIXL DAC L1 Switch' 0"
+        cset "name='Stereo1 DAC MIXR DAC R1 Switch' 0"
+    ]
 
-        Value {
-            PlaybackPriority 100
-            PlaybackPCM "hw:${CardId},0"
-            PlaybackChannels 2
-        }
-    }
-
-    SectionDevice."HDMI1" {
-        Comment "HDMI1"
-
-        EnableSequence [
-            cset "numid=14 1"
-        ]
-
-        DisableSequence [
-            cset "numid=14 0"
-        ]
-
-        Value {
-            PlaybackPriority 200
-            PlaybackPCM "hw:${CardId},2"
-            PlaybackChannels 2
-            JackControl "HDMI/DP,pcm=2 Jack"
-        }
-    }
-
-    SectionDevice."HDMI2" {
-        Comment "HDMI2"
-
-        EnableSequence [
-            cset "numid=20 1"
-        ]
-
-        DisableSequence [
-            cset "numid=20 0"
-        ]
-
-        Value {
-            PlaybackPriority 200
-            PlaybackPCM "hw:${CardId},3"
-            PlaybackChannels 2
-            JackControl "HDMI/DP,pcm=3 Jack"
-        }
-    }
-
-    SectionDevice."HDMI3" {
-        Comment "HDMI3"
-
-        EnableSequence [
-            cset "numid=26 1"
-        ]
-
-        DisableSequence [
-            cset "numid=26 0"
-        ]
-
-        Value {
-            PlaybackPriority 200
-            PlaybackPCM "hw:${CardId},4"
-            PlaybackChannels 2
-            JackControl "HDMI/DP,pcm=4 Jack"
-        }
+    Value {
+        PlaybackPriority 100
+        PlaybackPCM "hw:${CardId},0"
+        PlaybackChannels 2
+    }
+}
+
+SectionDevice."HDMI1" {
+    Comment "HDMI1"
+
+    EnableSequence [
+        cset "numid=14 1"
+    ]
+
+    DisableSequence [
+        cset "numid=14 0"
+    ]
+
+    Value {
+        PlaybackPriority 200
+        PlaybackPCM "hw:${CardId},2"
+        PlaybackChannels 2
+        JackControl "HDMI/DP,pcm=2 Jack"
+    }
+}
+
+SectionDevice."HDMI2" {
+    Comment "HDMI2"
+
+    EnableSequence [
+        cset "numid=20 1"
+    ]
+
+    DisableSequence [
+        cset "numid=20 0"
+    ]
+
+    Value {
+        PlaybackPriority 200
+        PlaybackPCM "hw:${CardId},3"
+        PlaybackChannels 2
+        JackControl "HDMI/DP,pcm=3 Jack"
+    }
+}
+
+SectionDevice."HDMI3" {
+    Comment "HDMI3"
+
+    EnableSequence [
+        cset "numid=26 1"
+    ]
+
+    DisableSequence [
+        cset "numid=26 0"
+    ]
+
+    Value {
+        PlaybackPriority 200
+        PlaybackPCM "hw:${CardId},4"
+        PlaybackChannels 2
+        JackControl "HDMI/DP,pcm=4 Jack"
     }
 }

scripts/install-kaisa-ucm-overlay.sh

@@ -30,4 +30,6 @@ else
 	echo "（无 user 会话，请登录后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）" >&2
 fi
 
-echo "完成。请按 OPERATION「UCM Jack 自动显示/隐藏」一节验收。"
+echo "完成。请先验证 UCM 能解析（应列出 HiFi，不应报 parse 错误）："
+echo "  alsaucm -c sof-rt5682 list _verbs"
+echo "再按 OPERATION「UCM Jack 自动显示/隐藏」验收 pactl / GNOME。"