📚 课程目录第2章 DAPM核心数据结构

2. DAPM核心数据结构：snd_soc_dapm_widget、snd_soc_dapm_path、snd_soc_dapm_route的结构与字段详解

DAPM（Dynamic Audio Power Management）是ALSA子系统中负责音频路径动态电源管理的核心机制。理解DAPM的三大核心数据结构——widget（控件）、path（路径）和route（路由），是掌握DAPM路由调试的基础。本章将逐一剖析这三个结构体的字段含义、作用以及它们之间的关联关系。

学习提示： widget是DAPM图中的节点，path是节点之间的连接线，route则是驱动开发者用来声明这些连接的静态描述。调试时，你看到的/sys/kernel/debug/asoc/*/dapm/* 目录下的内容，正是这些数据结构在运行时的映射。

2.1 snd_soc_dapm_widget：DAPM图中的节点

snd_soc_dapm_widget 是DAPM图中最基本的组成单元，代表一个音频处理或传输的实体，例如：音频接口（AIF）、DAC、ADC、混音器（Mixer）、MUX、输出引脚（OUTPUT）、输入引脚（INPUT）、电源域（Supply）等。每个widget都包含描述其类型、名称、连接状态、电源状态以及回调函数的信息。

2.1.1 核心字段解析

字段名	类型	描述
`name`	`const char *`	widget的唯一名称，用于在路由表中匹配。通常格式为“组件名:widget名”，例如“SSP0 DAC”。
`id`	`enum snd_soc_dapm_type`	widget的类型枚举，如 `snd_soc_dapm_dac`、`snd_soc_dapm_mixer`、`snd_soc_dapm_output` 等。类型决定了widget的行为和电源管理策略。
`reg` / `shift`	`unsigned int`	控制该widget电源状态的硬件寄存器地址和位偏移。对于某些虚拟widget（如Supply），此字段可能为0。
`on_val` / `off_val`	`unsigned int`	写入寄存器以开启或关闭widget电源的掩码值。通常 `on_val` 为 `0x2`（对应位为1），`off_val` 为 `0x0`。
`power`	`int`	运行时状态标志，表示当前widget是否上电（1）或下电（0）。这是DAPM算法计算后的结果。
`connected`	`int`	运行时状态标志，表示widget是否处于有效音频路径中。用于快速判断是否需要上电。
`event_flags`	`unsigned int`	事件标志位，指示widget在电源状态变化时是否需要调用回调函数。例如 `SND_SOC_DAPM_PRE_PMU`（上电前）、`SND_SOC_DAPM_POST_PMD`（下电后）。
`event`	`int (event)(struct snd_soc_dapm_widget , struct snd_kcontrol *, int)`	事件回调函数指针。当widget的电源状态发生变化时，如果 `event_flags` 设置了相应标志，此函数会被调用，用于执行额外的硬件初始化或去初始化。
`num_kcontrols` / `kcontrol_news`	`int` / `const struct snd_kcontrol_new *`	与该widget关联的控件数量及控件数组。例如，一个Mixer widget会包含多个音量控制或开关控制。
`priv`	`void *`	私有数据指针，驱动开发者可以在此挂载自定义的结构体，用于存储与widget相关的额外硬件信息。
`sname`	`const char *`	Stream名称，用于与PCM流进行绑定。当PCM流打开时，DAPM会根据 `sname` 自动上电对应的widget。

2.1.2 Widget类型枚举

enum snd_soc_dapm_type 定义了所有可能的widget类型，常见类型如下：

输入/输出类： snd_soc_dapm_input（物理输入引脚）、snd_soc_dapm_output（物理输出引脚）、snd_soc_dapm_mic（麦克风）、snd_soc_dapm_hp（耳机）、snd_soc_dapm_spk（扬声器）。
转换类： snd_soc_dapm_adc（模数转换器）、snd_soc_dapm_dac（数模转换器）、snd_soc_dapm_aif_in（数字音频接口输入）、snd_soc_dapm_aif_out（数字音频接口输出）。
混音/选择类： snd_soc_dapm_mixer（混音器）、snd_soc_dapm_mixer_named_ctl（命名控件混音器）、snd_soc_dapm_mux（多路选择器）、snd_soc_dapm_demux（多路分配器）。
电源/虚拟类： snd_soc_dapm_supply（电源域）、snd_soc_dapm_regulator_supply（稳压器电源）、snd_soc_dapm_clock_supply（时钟电源）、snd_soc_dapm_kcontrol（虚拟控件）。
前置/后置类： snd_soc_dapm_pre（前置处理）、snd_soc_dapm_post（后置处理）。

  调试要点： 在 /sys/kernel/debug/asoc/codec_name/dapm 目录下，你可以看到所有widget的运行时状态。使用 cat 命令查看每个widget文件，输出格式为 widget_name: power_state connected_state，例如 SSP0 DAC: Off 或 HPOUT: On connected。

2.1.3 Widget关系SVG图

下图展示了一个典型的音频Codec内部widget之间的连接关系，以及widget与外部引脚、DMA引擎的交互：

2.2 snd_soc_dapm_path：连接widget的边

snd_soc_dapm_path 结构体代表DAPM图中两个widget之间的连接关系。它描述了音频数据流的方向、连接强度以及运行时状态。DAPM算法正是通过遍历这些path来构建完整的音频路径，并决定哪些widget需要上电。

2.2.1 核心字段解析

字段名	类型	描述
`source`	`struct snd_soc_dapm_widget *`	指向源widget的指针，即音频数据流的起点。
`sink`	`struct snd_soc_dapm_widget *`	指向目标widget的指针，即音频数据流的终点。
`connect`	`int`	运行时连接状态。1表示路径当前处于连接状态，0表示断开。此状态受混音器控件、MUX选择器或外部事件影响。
`connected`	`int`	运行时路径有效性标志。由DAPM算法在遍历时设置，表示该路径是否属于当前活动的音频路径。
`walked`	`int`	遍历标志，用于DAPM算法在递归搜索时标记已访问的路径，防止死循环。
`weak`	`int`	弱连接标志。如果设置为1，表示该路径不会强制其源或目标widget上电，通常用于Supply类型的widget。
`name`	`const char *`	路径名称，通常与关联的混音器控件名称相同，用于调试和匹配。
`list_source` / `list_sink`	`struct list_head`	链表节点，分别用于将path挂入source widget的 `sources` 链表和sink widget的 `sinks` 链表。
`list`	`struct list_head`	全局链表节点，用于将path挂入整个DAPM上下文的 `path_list`。

2.2.2 Path的创建与连接

Path的创建通常发生在DAPM初始化阶段，由 snd_soc_dapm_add_path() 函数完成。该函数接收源widget、目标widget、控件名称（可选）和连接状态等参数，分配并初始化一个 snd_soc_dapm_path 结构体，并将其插入到相应的链表中。

static int snd_soc_dapm_add_path(struct snd_soc_dapm_context *dapm,
    struct snd_soc_dapm_widget *source,
    struct snd_soc_dapm_widget *sink,
    const char *name, int connected, int weak)
{
    struct snd_soc_dapm_path *path;
    // 1. 分配path结构体
    path = kzalloc(sizeof(struct snd_soc_dapm_path), GFP_KERNEL);
    if (!path)
        return -ENOMEM;

    // 2. 初始化字段
    path->source = source;
    path->sink = sink;
    path->name = name;
    path->connect = connected;
    path->weak = weak;

    // 3. 将path挂入source和sink的链表
    list_add(&path->list_source, &source->sources);
    list_add(&path->list_sink, &sink->sinks);
    list_add(&path->list, &dapm->path_list);

    return 0;
}

调试陷阱： 在调试无声问题时，经常遇到 connect 状态为0的情况。这通常是因为混音器控件被用户空间错误地设置为静音，或者MUX选择了错误的输入。使用 amixer 命令检查并调整控件状态，可以恢复路径连接。

2.2.3 Path连接状态SVG图

下图展示了三个widget之间通过path连接，以及 connect 状态如何影响音频路径的连通性：

2.3 snd_soc_dapm_route：静态路由描述

snd_soc_dapm_route 是驱动开发者用来声明widget之间连接关系的静态结构体。它不参与运行时动态变化，而是作为“蓝图”在初始化阶段被解析，用于创建对应的 snd_soc_dapm_path 实例。每个route定义了一条从源widget到目标widget的潜在连接。

2.3.1 结构体定义与字段

struct snd_soc_dapm_route {
    const char *sink;       // 目标widget的名称
    const char *control;    // 关联的控件名称（可选，用于Mixer/MUX）
    const char *source;     // 源widget的名称
    int connected;          // 初始连接状态（通常为1表示默认连接）
};

字段名	描述
`sink`	目标widget的名称字符串。必须与某个已注册widget的 `name` 字段完全匹配。
`control`	控件名称字符串。对于Mixer或MUX类型的widget，此字段指定了控制该路径通断的控件名称。如果为NULL，表示该路径不受控件影响，始终连接。
`source`	源widget的名称字符串。同样必须与已注册widget的 `name` 字段完全匹配。
`connected`	初始连接状态。通常设置为1，表示在没有任何控件干预的情况下，该路径是默认连通的。对于受控件控制的路径，此值会被控件的初始状态覆盖。

2.3.2 Route的注册与解析

驱动开发者通过调用 snd_soc_dapm_add_routes() 函数，将一个 snd_soc_dapm_route 数组注册到DAPM上下文中。内核会遍历该数组，对每个route执行以下操作：

查找widget： 根据 source 和 sink 名称，在DAPM上下文中查找对应的widget实例。如果找不到，会打印错误信息并跳过该route。
创建path： 调用 snd_soc_dapm_add_path() 函数，在源widget和目标widget之间创建一个新的path。
关联控件： 如果 control 字段不为空，则查找目标widget（或源widget）上同名的kcontrol，并将该kcontrol与新建的path绑定。这样，当用户空间通过 amixer 调整该控件时，path的 connect 状态会同步更新。

  调试要点： 在调试路由问题时，首先检查route定义是否正确。常见的错误包括：widget名称拼写错误、大小写不匹配、或者引用了不存在的widget。内核日志中会输出类似 ASoC: no sink widget found for ... 的提示，这是定位route问题的关键线索。

2.3.3 Route到Path的映射SVG图

下图展示了静态route数组如何被解析为动态的path图，以及控件如何影响path的连接状态：