第二章：UCM配置文件结构——语法基础、Section分类与文件命名规则

好，咱们今天来聊聊UCM配置文件的骨架。说白了，你要想用好UCM，就得先看懂它的配置文件长什么样。我刚开始接触UCM那会儿，对着一个几百行的配置文件发懵，后来摸清了门道，才发现这东西其实挺有规律的。

2.1 语法基础：UCM配置文件的“普通话”

UCM配置文件用的是ALSA的语法体系，但你别怕，它没那么复杂。核心就几个规则：

• 键值对：最基本的单元，比如 EnableSequence [ 这种，方括号里放具体命令。
• Section定义：用 SectionDevice."名称" { ... } 这种格式包裹一块配置。
• 注释：用 # 开头，整行都是注释。我习惯在关键配置前加一行注释，方便回头查。
• 字符串引用：路径或者设备名用双引号括起来，比如 "hw:0,0"。

嗯，这里要注意：UCM的语法对空格和换行比较敏感。我曾经在项目里因为多了一个空格，导致整个配置文件解析失败，查了半天才发现是格式问题。所以，写的时候尽量保持整洁，缩进对齐。

2.2 Section分类：三大核心模块

UCM配置文件里，Section是主角。主要分三类，我一个个说。

2.2.1 SectionDevice

这个Section描述的是具体的音频设备，比如扬声器、耳机、麦克风。每个设备都有自己的配置块。

SectionDevice."Speaker" {
    Comment "Speaker output device"
    EnableSequence [
        cdev "hw:0,0"
        cset "name='Speaker Switch' on"
    ]
    DisableSequence [
        cset "name='Speaker Switch' off"
    ]
    Value {
        PlaybackPriority 100
        PlaybackVolume "name='Speaker Playback Volume'"
    }
}

你看，EnableSequence 和 DisableSequence 定义了设备启用和禁用时要执行的ALSA控制命令。Value 块里放的是设备的属性，比如音量控制的名字。我个人习惯把设备名写得直观一点，比如 SectionDevice."Headphone"，别用缩写，不然过两个月自己都看不懂。

2.2.2 SectionVerb

这个Section定义的是“动词”，也就是音频场景。比如播放音乐、通话、录音。每个Verb对应一个使用场景。

SectionVerb."Playback" {
    EnableSequence [
        cdev "hw:0,0"
        cset "name='Master Playback Volume' 80%"
    ]
    DisableSequence [
        cset "name='Master Playback Volume' 0%"
    ]
    Value {
        TQ "HiFi"
    }
}

这里 TQ "HiFi" 表示这个场景的音质目标是高保真。我记得有一次做车载音频项目，客户要求通话场景和音乐场景用不同的音频路由，就是靠不同的SectionVerb来实现的。你想想看，如果没有这个分层，你得在驱动里写多少if-else？

2.2.3 SectionModifier

这个Section是“修饰器”，用来在已有场景上叠加效果。比如在播放音乐时开启音效、均衡器。

SectionModifier."EQ" {
    Comment "Enable equalizer for music playback"
    EnableSequence [
        cset "name='EQ Enable' on"
        cset "name='EQ Preset' 1"
    ]
    DisableSequence [
        cset "name='EQ Enable' off"
    ]
    SupportedDevice [
        "Speaker"
        "Headphone"
    ]
}

注意 SupportedDevice 字段，它指定了这个Modifier可以作用于哪些设备。说白了，你不能在麦克风上开均衡器，对吧？

2.3 文件命名规则：别让名字坑了你

UCM配置文件的名字不是随便起的。它有一套约定，你得遵守。

文件类型	命名规则	示例
主配置文件	ucm/<声卡名>.conf	ucm/sof-hda-dsp.conf
设备配置文件	ucm/<声卡名>/<设备名>.conf	ucm/sof-hda-dsp/HiFi.conf
Verb配置文件	ucm/<声卡名>/<Verb名>.conf	ucm/sof-hda-dsp/Playback.conf

这里有个坑：声卡名必须和ALSA的声卡名称完全一致。我遇到过有人把 sof-hda-dsp 写成了 sof_hda_dsp，结果UCM死活加载不上。为什么？因为ALSA用连字符，不是下划线。这种小细节，查起来真要命。

2.4 实战建议：从零搭建一个UCM配置

好了，理论说完了，咱们来点实际的。如果你要从头写一个UCM配置，我建议按这个步骤来：

1. 先确定声卡名：用 aplay -l 或者 cat /proc/asound/cards 查看。
2. 创建目录结构：在 /usr/share/alsa/ucm/ 下建一个以声卡名命名的文件夹。
3. 写主配置文件：引用各个子配置文件。
4. 定义SectionDevice：把硬件设备都列出来，写好Enable/Disable序列。
5. 定义SectionVerb：根据使用场景创建Verb，比如Playback、Capture、VoiceCall。
6. 添加SectionModifier：如果需要特殊效果，再加Modifier。

嗯，这里要注意：别一上来就想写全。我习惯先写一个最小可用的配置，比如只支持播放和录音，然后逐步加功能。这样调试起来方便，出了问题也容易定位。

下一章，咱们会深入SectionDevice的细节，讲讲怎么写好EnableSequence和DisableSequence。到时候我会分享一些我在项目中踩过的坑，保证实用。