仔细读过前几篇
machine.txt
codec.txt
platform.txt
文档的同学会发现，里面反复出现一个名词——“dapm”，比如：
Platform:
Codec:
本篇来介绍dapm (Dynamic Audio Power Management, 动态音频电源管理)
基于4.9.123版本内核 Documentation/sound/alsa/soc/dapm.txt
Dynamic Audio Power Management for Portable Devices
===================================================
1. Description
==============
Dynamic Audio Power Management (DAPM) is designed to allow portable
Linux devices to use the minimum amount of power within the audio
subsystem at all times. It is independent of other kernel PM and as
such, can easily co-exist with the other PM systems.
动态音频电源管理（DAPM）旨在允许便携式Linux设备始终在音频子系统中使用最少的电
量。 它独立于其他内核PM，因此可以轻松地与其他PM系统共存。
DAPM is also completely transparent to all user space applications as
all power switching is done within the ASoC core. No code changes or
recompiling are required for user space applications. DAPM makes power
switching decisions based upon any audio stream (capture/playback)
activity and audio mixer settings within the device.
DAPM对所有用户空间应用程序也完全透明，因为所有电源切换都在ASoC核心内完成。 用户
空间应用程序不需要更改代码或重新编译。 DAPM根据设备内的任何音频流（捕获/回放）活
动和音频混合器设置做出功率切换决策。
DAPM spans the whole machine. It covers power control within the entire
audio subsystem, this includes internal codec power blocks and machine
level power systems.
DAPM跨越整个机器。 它涵盖整个音频子系统内的电源控制，包括内部编解码器电源块和机器
级电源系统。
There are 4 power domains within DAPM
DAPM中有4个电源域
1. Codec bias domain - VREF, VMID (core codec and audio power)
Usually controlled at codec probe/remove and suspend/resume, although
can be set at stream time if power is not needed for sidetone, etc.
1.编解码器偏置域 - VREF，VMID（核心编解码器和音频功率）
通常在编解码器探测/移除和暂停/恢复时控制，但是如果侧音不需要电源等，则可以在流时间设置。
2. Platform/Machine domain - physically connected inputs and outputs
Is platform/machine and user action specific, is configured by the
machine driver and responds to asynchronous events e.g when HP
are inserted
2. 平台/机器域 - 物理连接的输入和输出是平台/机器和用户操作特定的，由机器驱动程序配
置并响应异步事件，例如插入HP时置并响应异步事件，例如插入HP时
3. Path domain - audio subsystem signal paths
Automatically set when mixer and mux settings are changed by the user.
e.g. alsamixer, amixer.
3.路径域 - 音频子系统信号路径
当用户更改混音器和多路复用器设置时自动设置。 例如 alsamixer，amixer。
4. Stream domain - DACs and ADCs.
Enabled and disabled when stream playback/capture is started and
stopped respectively. e.g. aplay, arecord.
4.流域 - DAC和ADC。
分别启动和停止流播放/捕获时启用和禁用。 例如 aplay，arecord。
All DAPM power switching decisions are made automatically by consulting an audio
routing map of the whole machine. This map is specific to each machine and
consists of the interconnections between every audio component (including
internal codec components). All audio components that effect power are called
widgets hereafter.
所有DAPM电源切换决策都是通过查阅整台机器的音频路由图自动完成的。 此映射特定于每台
计算机，并包含每个音频组件（包括内部编解码器组件）之间的互连。 所有影响力的音频组
件在下文中称为小部件。
2. DAPM Widgets
===============
Audio DAPM widgets fall into a number of types:-
音频DAPM widgets 分为多种类型： -
o Mixer - Mixes several analog signals into a single analog signal. 将多个模拟信号混合为单个模拟信号。
o Mux - An analog switch that outputs only one of many inputs. 模拟开关，仅输出许多输入中的一个。
o PGA - A programmable gain amplifier or attenuation widget. 可编程增益放大器或衰减小部件。
o ADC - Analog to Digital Converter 模数转换器
o DAC - Digital to Analog Converter 数模转换器
o Switch - An analog switch 模拟开关
o Input - A codec input pin Codec输入引脚
o Output - A codec output pin Codec输出引脚
o Headphone - Headphone (and optional Jack) 耳机（和可选插孔）
o Mic - Mic (and optional Jack) 麦克风（和可选插孔）
o Line - Line Input/Output (and optional Jack) 线路输入输出（和可选插孔）
o Speaker - Speaker 扬声器
o Supply - Power or clock supply widget used by other widgets. 其他小部件使用的电源或时钟供应小部件。
o Regulator - External regulator that supplies power to audio components. 外部稳压器，为音频组件供电。
o Clock - External clock that supplies clock to audio components. 外部时钟，为音频组件提供时钟。
o AIF IN - Audio Interface Input (with TDM slot mask). 音频接口输入（带TDM slot掩码）。
o AIF OUT - Audio Interface Output (with TDM slot mask). 音频接口输出（带TDM插槽掩码）。
o Siggen - Signal Generator. 信号发生器。
o DAI IN - Digital Audio Interface Input. 数字音频接口输入。
o DAI OUT - Digital Audio Interface Output. 数字音频接口输出。
o DAI Link - DAI Link between two DAI structures 两个DAI结构之间的DAI链接* /
o Pre - Special PRE widget (exec before all others) 特别的PRE小部件（exec在所有其他之前）
o Post - Special POST widget (exec after all others) 特殊的POST小部件（exec跟随所有其他小部件）
(Widgets are defined in include/sound/soc-dapm.h)
Widgets can be added to the sound card by any of the component driver types.
There are convenience macros defined in soc-dapm.h that can be used to quickly
build a list of widgets of the codecs and machines DAPM widgets.
可以通过任何组件驱动程序类型将小组件添加到声卡。
soc-dapm.h中定义了便利宏，可用于快速构建编解码器和机器DAPM小部件的小部件列表。
Most widgets have a name, register, shift and invert. Some widgets have extra
parameters for stream name and kcontrols.
大多数小部件都有名称，寄存器，移位和反转。 一些小部件有流名称和kcontrols的额外参
数。
2.1 Stream Domain Widgets
-------------------------
Stream Widgets relate to the stream power domain and only consist of ADCs
(analog to digital converters), DACs (digital to analog converters), AIF IN and AIF OUT.
流widgets 与流功率域相关，仅由ADC（模数转换器），DAC（数模转换器），AIF IN和AIF
OUT组成。
Stream widgets have the following format:-
流widgets 使用以下格式： -
SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
NOTE: the stream name must match the corresponding stream name in your codec
snd_soc_codec_dai.
注意：流名称必须与编解码器snd_soc_codec_dai中的相应流名称匹配。
e.g. stream widgets for HiFi playback and capture
例如 用于HiFi播放和录音的流 widgets
SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
e.g. stream widgets for AIF
例如 AIF的流widgets
SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
2.2 Path Domain Widgets
-----------------------
Path domain widgets have a ability to control or affect the audio signal or
audio paths within the audio subsystem. They have the following form:-
路径域小部件具有控制或影响音频子系统内的音频信号或音频路径的能力。 它们具有以下形
式： -
SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
Any widget kcontrols can be set using the controls and num_controls members.
可以使用controls和num_controls成员设置任何窗口小部件kcontrols。
e.g. Mixer widget (the kcontrols are declared first)
例如 混音器widget （首先声明kcontrols）
/* Output Mixer */
static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
};
SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
ARRAY_SIZE(wm8731_output_mixer_controls)),
If you don't want the mixer elements prefixed with the name of the mixer widget,
you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
as for SND_SOC_DAPM_MIXER.
如果您不希望混音器元素以混音器widget的名称为前缀，则可以使用
SND_SOC_DAPM_MIXER_NAMED_CTL。 参数与SND_SOC_DAPM_MIXER相同。
2.3 Machine domain Widgets
--------------------------
Machine widgets are different from codec widgets in that they don't have a
codec register bit associated with them. A machine widget is assigned to each
machine audio component (non codec or DSP) that can be independently
powered. e.g.
machine widgets与codec widgets的不同之处在于它们没有与它们相关联的codec寄存器位。
machine widget被分配给可以独立供电的每个机器音频组件（非编解码器或DSP）。 例如
o Speaker Amp 扬声器放大器
o Microphone Bias 麦克风偏置
o Jack connectors 插头连接器
A machine widget can have an optional call back.
machine widget可以具有可选的回调。
e.g. Jack connector widget for an external Mic that enables Mic Bias
when the Mic is inserted:-
例如 用于外接麦克风的插孔连接器小部件，可在插入麦克风时启用麦克风偏置： -
static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
{
gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
return 0;
}
SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
2.4 Codec (BIAS) Domain
-----------------------
The codec bias power domain has no widgets and is handled by the codecs DAPM
event handler. This handler is called when the codec powerstate is changed wrt
to any stream event or by kernel PM events.
codec偏置电源域没有widgets ，由codec DAPM事件处理程序处理。 当编解码器powerstate
被更改为任何流事件或内核PM事件时，将调用此处理程序。
2.5 Virtual Widgets
-------------------
Sometimes widgets exist in the codec or machine audio map that don't have any
corresponding soft power control. In this case it is necessary to create
a virtual widget - a widget with no control bits e.g.
有时，编解码器或机器音频映射中存在没有任何相应软功率控制的小部件。 在这种情况下，
有必要创建一个虚拟小部件 - 一个没有控制位的小部件，例如
SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
This can be used to merge to signal paths together in software.
这可以用于在软件中合并到信号路径。
After all the widgets have been defined, they can then be added to the DAPM
subsystem individually with a call to snd_soc_dapm_new_control().
在定义了所有小部件之后，可以通过调用snd_soc_dapm_new_control（）将它们单独添加到
DAPM子系统。
3. Codec/DSP Widget Interconnections
====================================
Widgets are connected to each other within the codec, platform and machine by
audio paths (called interconnections). Each interconnection must be defined in
order to create a map of all audio paths between widgets.
小部件通过音频路径（称为互连）在编解码器，平台和机器内相互连接。 必须定义每个互
连，以便创建窗口小部件之间所有音频路径的映射。
This is easiest with a diagram of the codec or DSP (and schematic of the machine
audio system), as it requires joining widgets together via their audio signal
paths.
这对于编解码器或DSP（以及机器音频系统的原理图）的图表来说是最简单的，因为它需要通
过其音频信号路径将小部件连接在一起。
e.g., from the WM8731 output mixer (wm8731.c)
The WM8731 output mixer has 3 inputs (sources)
1. Line Bypass Input
2. DAC (HiFi playback)
3. Mic Sidetone Input
Each input in this example has a kcontrol associated with it (defined in example
above) and is connected to the output mixer via its kcontrol name. We can now
connect the destination widget (wrt audio signal) with its source widgets.
此示例中的每个输入都有一个与之关联的kcontrol（在上面的示例中定义），并通过其kcontrol
名称连接到输出混合器。 我们现在可以将目标窗口小部件（wrt音频信号）与其源窗口小部件
连接起来。
/* output mixer */
{"Output Mixer", "Line Bypass Switch", "Line Input"},
{"Output Mixer", "HiFi Playback Switch", "DAC"},
{"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
So we have :-
Destination Widget <=== Path Name <=== Source Widget
目标Widget <===路径名称 <===源Widget
Or:-
Sink, Path, Source
Or :-
"Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
“输出混音器”通过“HiFi播放开关”连接到“DAC”。
When there is no path name connecting widgets (e.g. a direct connection) we
pass NULL for the path name.
当没有连接小部件的路径名（例如直接连接）时，我们为路径名传递NULL。
Interconnections are created with a call to:-
通过调用以下方式创建互连： -
snd_soc_dapm_connect_input(codec, sink, path, source);
Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
interconnections have been registered with the core. This causes the core to
scan the codec and machine so that the internal DAPM state matches the
physical state of the machine.
最后，必须在向核心注册所有小部件和互连之后调用snd_soc_dapm_new_widgets（编解码
器）。 这会导致核心扫描编解码器和机器，以便内部DAPM状态与机器的物理状态相匹配。
3.1 Machine Widget Interconnections
-----------------------------------
Machine widget interconnections are created in the same way as codec ones and
directly connect the codec pins to machine level widgets.
机器小部件互连的创建方式与编解码器相同，并直接将编解码器引脚连接到机器级小部件。
e.g. connects the speaker out codec pins to the internal speaker.
例如 将扬声器输出编解码器引脚连接到内部扬声器。
/* ext speaker connected to codec pins LOUT2, ROUT2 */
{"Ext Spk", NULL , "ROUT2"},
{"Ext Spk", NULL , "LOUT2"},
This allows the DAPM to power on and off pins that are connected (and in use)
and pins that are NC respectively.
这允许DAPM分别接通和断开连接（和使用中）和NC引脚的引脚。
4 Endpoint Widgets
===================
An endpoint is a start or end point (widget) of an audio signal within the
machine and includes the codec. e.g.
端点是机器内音频信号的起点或终点（小部件），并包括编解码器。 例如
o Headphone Jack 耳机插孔
o Internal Speaker 内部扬声器
o Internal Mic 内部麦克风
o Mic Jack 麦克风插孔
o Codec Pins Codec引脚
Endpoints are added to the DAPM graph so that their usage can be determined in
order to save power. e.g. NC codecs pins will be switched OFF, unconnected
jacks can also be switched OFF.
端点将添加到DAPM图表中，以便确定其使用情况以节省电量。 例如 NC编解码器引脚将关
闭，未连接的插孔也可以关闭。
5 DAPM Widget Events
====================
Some widgets can register their interest with the DAPM core in PM events.
e.g. A Speaker with an amplifier registers a widget so the amplifier can be
powered only when the spk is in use.
一些小部件可以在PM事件中注册他们对DAPM核心的兴趣。 例如 带放大器的扬声器可以注册
小部件，因此放大器只能在spk使用时供电。
/* turn speaker amplifier on/off depending on use */
static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
{
gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
return 0;
}
/* corgi machine dapm widgets */
static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
Please see soc-dapm.h for all other widgets that support events.
有关支持事件的所有其他widgets ，请参阅soc-dapm.h。
5.1 Event types
---------------
The following event types are supported by event widgets.
/* dapm event types */
#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
思维导图如下：
