[Alsa Document]8, DPCM.txt
本篇来介绍动态PCM——Dynamic PCM，这部分现在还没仔细研究，先译在这里，回头好做引用。
基于4.9.123版本内核 Documentation/sound/alsa/soc/DPCM.txt
Dynamic PCM
===========
1. Description
==============
Dynamic PCM allows an ALSA PCM device to digitally route its PCM audio to
various digital endpoints during the PCM stream runtime. e.g. PCM0 can route
digital audio to I2S DAI0, I2S DAI1 or PDM DAI2. This is useful for on SoC DSP
drivers that expose several ALSA PCMs and can route to multiple DAIs.
动态PCM允许ALSA PCM设备在PCM流运行期间以数字方式将其PCM音频路由到各种数字端
点。 例如 PCM0可以将数字音频路由到I2S DAI0，I2S DAI1或PDM DAI2。 这对于暴露多个
ALSA PCM并可以路由到多个DAI的SoC DSP驱动程序非常有用。
The DPCM runtime routing is determined by the ALSA mixer settings in the same
way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM
graph representing the DSP internal audio paths and uses the mixer settings to
determine the patch used by each ALSA PCM.
动态PCM允许ALSA PCM设备在PCM流运行期间以数字方式将其PCM音频路由到各种数字端
点。 例如 PCM0可以将数字音频路由到I2S DAI0，I2S DAI1或PDM DAI2。 这对于暴露多个
ALSA PCM并可以路由到多个DAI的SoC DSP驱动程序非常有用。
DPCM re-uses all the existing component codec, platform and DAI drivers without
any modifications.
DPCM无需任何修改即可重复使用所有现有的组件编解码器，平台和DAI驱动程序。
Phone Audio System with SoC based DSP
-------------------------------------
Consider the following phone audio subsystem. This will be used in this
document for all examples :-
请参考以下手机音频子系统。 这将在本文档中用于所有示例： -
| Front End PCMs | SoC DSP | Back End DAIs | Audio devices |
*************
PCM0 <------------> * * <----DAI0-----> Codec Headset
* *
PCM1 <------------> * * <----DAI1-----> Codec Speakers
* DSP *
PCM2 <------------> * * <----DAI2-----> MODEM
* *
PCM3 <------------> * * <----DAI3-----> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
This diagram shows a simple smart phone audio subsystem. It supports Bluetooth,
FM digital radio, Speakers, Headset Jack, digital microphones and cellular
modem. This sound card exposes 4 DSP front end (FE) ALSA PCM devices and
supports 6 back end (BE) DAIs. Each FE PCM can digitally route audio data to any
of the BE DAIs. The FE PCM devices can also route audio to more than 1 BE DAI.
此图显示了一个简单的智能手机音频子系统。 它支持蓝牙，FM数字收音机，扬声器，耳机插
孔，数字麦克风和蜂窝调制解调器。 该声卡显示4个DSP前端（FE）ALSA PCM设备，并支持
6个后端（BE）DAI。 每个FE PCM可以将音频数据以数字方式路由到任何BE DAI。 FE PCM
设备还可以将音频路由到超过1 BE DAI。
Example - DPCM Switching playback from DAI0 to DAI1
---------------------------------------------------
Audio is being played to the Headset. After a while the user removes the headset
and audio continues playing on the speakers.
音频正在播放到耳机。 一段时间后，用户移除耳机并继续在扬声器上播放音频。
Playback on PCM0 to Headset would look like :-
PCM0到耳机的播放构成如下： -
*************
PCM0 <============> * * <====DAI0=====> Codec Headset
* *
PCM1 <------------> * * <----DAI1-----> Codec Speakers
* DSP *
PCM2 <------------> * * <----DAI2-----> MODEM
* *
PCM3 <------------> * * <----DAI3-----> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
The headset is removed from the jack by user so the speakers must now be used :-
用户将耳机从插孔中取出，因此现在必须使用扬声器： -
*************
PCM0 <============> * * <----DAI0-----> Codec Headset
* *
PCM1 <------------> * * <====DAI1=====> Codec Speakers
* DSP *
PCM2 <------------> * * <----DAI2-----> MODEM
* *
PCM3 <------------> * * <----DAI3-----> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
The audio driver processes this as follows :-
1) Machine driver receives Jack removal event.
1）机器驱动程序接收Jack移除事件。
2) Machine driver OR audio HAL disables the Headset path.
2）机器驱动程序或音频HAL禁用耳机路径。
3) DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0
for headset since the path is now disabled.
3）DPCM在DAI0上为耳机运行PCM触发（停止），hw_free（），shutdown（）操作，因
为现在路径已被禁用。
4) Machine driver or audio HAL enables the speaker path.
4）机器驱动器或音频HAL启用扬声器路径。
5) DPCM runs the PCM ops for startup(), hw_params(), prepapre() and
trigger(start) for DAI1 Speakers since the path is enabled.
5）由于路径已启用，DPCM为DAI1扬声器运行启动（），hw_params（），prepapre（）
和触发（启动）的PCM操作。
In this example, the machine driver or userspace audio HAL can alter the routing
and then DPCM will take care of managing the DAI PCM operations to either bring
the link up or down. Audio playback does not stop during this transition.
在此示例中，机器驱动程序或用户空间音频HAL可以改变路由，然后DPCM将负责管理DAI
PCM操作以使链接上行或下行。 在此过渡期间，音频播放不会停止。
DPCM machine driver
===================
The DPCM enabled ASoC machine driver is similar to normal machine drivers
except that we also have to :-
启用DPCM的ASoC机器驱动程序与普通机器驱动程序类似，但我们还必须：
1) Define the FE and BE DAI links.
1）定义FE和BE DAI链接。
2) Define any FE/BE PCM operations.
2）定义任何FE / BE PCM操作。
3) Define widget graph connections.
3）定义小部件图形连接。
1 FE and BE DAI links
---------------------
| Front End PCMs | SoC DSP | Back End DAIs | Audio devices |
*************
PCM0 <------------> * * <----DAI0-----> Codec Headset
* *
PCM1 <------------> * * <----DAI1-----> Codec Speakers
* DSP *
PCM2 <------------> * * <----DAI2-----> MODEM
* *
PCM3 <------------> * * <----DAI3-----> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
For the example above we have to define 4 FE DAI links and 6 BE DAI links. The
FE DAI links are defined as follows :-
对于上面的示例，我们必须定义4个FE DAI链接和6个BE DAI链接。 FE DAI链接定义如下： -
static struct snd_soc_dai_link machine_dais[] = {
{
.name = "PCM0 System",
.stream_name = "System Playback",
.cpu_dai_name = "System Pin",
.platform_name = "dsp-audio",
.codec_name = "snd-soc-dummy",
.codec_dai_name = "snd-soc-dummy-dai",
.dynamic = 1,
.trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST},
.dpcm_playback = 1,
},
.....< other FE and BE DAI links here >
};
This FE DAI link is pretty similar to a regular DAI link except that we also
set the DAI link to a DPCM FE with the "dynamic = 1". The supported FE stream
directions should also be set with the "dpcm_playback" and "dpcm_capture"
flags. There is also an option to specify the ordering of the trigger call for
each FE. This allows the ASoC core to trigger the DSP before or after the other
components (as some DSPs have strong requirements for the ordering DAI/DSP
start and stop sequences).
这个FE DAI链接非常类似于常规DAI链接，除了我们还将DAI链接设置为具有“dynamic = 1”的
DPCM FE。 还应使用“dpcm_playback”和“dpcm_capture”标志设置支持的FE流方向。 还可以
选择为每个FE指定触发器调用的顺序。 这允许ASoC内核在其他组件之前或之后触发DSP（因
为某些DSP对订购DAI / DSP启动和停止序列有强烈要求）。
The FE DAI above sets the codec and code DAIs to dummy devices since the BE is
dynamic and will change depending on runtime config.
上面的FE DAI将编解码器和代码DAI设置为虚拟设备，因为BE是动态的，并且将根据运行时配
置而改变。
The BE DAIs are configured as follows :-
BE DAI配置如下： -
static struct snd_soc_dai_link machine_dais[] = {
.....< FE DAI links here >
{
.name = "Codec Headset",
.cpu_dai_name = "ssp-dai.0",
.platform_name = "snd-soc-dummy",
.no_pcm = 1,
.codec_name = "rt5640.0-001c",
.codec_dai_name = "rt5640-aif1",
.ignore_suspend = 1,
.ignore_pmdown_time = 1,
.be_hw_params_fixup = hswult_ssp0_fixup,
.ops = &haswell_ops,
.dpcm_playback = 1,
.dpcm_capture = 1,
},
.....< other BE DAI links here >
};
This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets
the "no_pcm" flag to mark it has a BE and sets flags for supported stream
directions using "dpcm_playback" and "dpcm_capture" above.
此BE DAI链接将DAI0连接到编解码器（在本例中为RT5460 AIF1）。 它设置“no_pcm”标志以
标记它具有BE并使用上面的“dpcm_playback”和“dpcm_capture”为支持的流方向设置标志。
The BE has also flags set for ignoring suspend and PM down time. This allows
the BE to work in a hostless mode where the host CPU is not transferring data
like a BT phone call :-
BE还设置了用于忽略暂停和PM停机时间的标志。 这允许BE在无主机模式下工作，其中主机
CPU不像BT电话那样传输数据： -
*************
PCM0 <------------> * * <----DAI0-----> Codec Headset
* *
PCM1 <------------> * * <----DAI1-----> Codec Speakers
* DSP *
PCM2 <------------> * * <====DAI2=====> MODEM
* *
PCM3 <------------> * * <====DAI3=====> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are
still in operation.
这允许主机CPU在DSP，MODEM DAI和BT DAI仍在运行时休眠。
A BE DAI link can also set the codec to a dummy device if the code is a device
that is managed externally.
如果代码是外部管理的设备，BE DAI链接还可以将编解码器设置为虚拟设备。
Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the
DSP firmware.
同样，如果CPU DAI由DSP固件管理，BE DAI也可以设置虚拟CPU DAI。
2 FE/BE PCM operations
----------------------
The BE above also exports some PCM operations and a "fixup" callback. The fixup
callback is used by the machine driver to (re)configure the DAI based upon the
FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE.
上面的BE还导出了一些PCM操作和一个“fixup”回调。 机器驱动程序使用fixup回调来根据FE
hw参数（重新）配置DAI。 即，DSP可以从FE到BE执行SRC或ASRC。
e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for
DAI0. This means all FE hw_params have to be fixed in the machine driver for
DAI0 so that the DAI is running at desired configuration regardless of the FE
configuration.
例如 DSP将所有FE hw参数转换为固定速率48k，16bit，立体声为DAI0。 这意味着必须在
DAI0的机器驱动程序中修复所有FE hw_params，以便DAI以所需的配置运行，而不管FE配置
如何。
static int dai0_fixup(struct snd_soc_pcm_runtime *rtd,
struct snd_pcm_hw_params *params)
{
struct snd_interval *rate = hw_param_interval(params,
SNDRV_PCM_HW_PARAM_RATE);
struct snd_interval *channels = hw_param_interval(params,
SNDRV_PCM_HW_PARAM_CHANNELS);
/* The DSP will covert the FE rate to 48k, stereo */
rate->min = rate->max = 48000;
channels->min = channels->max = 2;
/* set DAI0 to 16 bit */
snd_mask_set(¶ms->masks[SNDRV_PCM_HW_PARAM_FORMAT -
SNDRV_PCM_HW_PARAM_FIRST_MASK],
SNDRV_PCM_FORMAT_S16_LE);
return 0;
}
The other PCM operation are the same as for regular DAI links. Use as necessary.
其他PCM操作与常规DAI链接相同。 必要时使用。
3 Widget graph connections
--------------------------
The BE DAI links will normally be connected to the graph at initialisation time
by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this
has to be set explicitly in the driver :-
BE DAI链路通常在初始化时由ASoC DAPM内核连接到图形。 但是，如果BE编解码器或BE
DAI是虚拟的，则必须在驱动程序中明确设置： -
/* BE for codec Headset - DAI0 is dummy and managed by DSP FW */
{"DAI0 CODEC IN", NULL, "AIF1 Capture"},
{"AIF1 Playback", NULL, "DAI0 CODEC OUT"},
Writing a DPCM DSP driver
=========================
The DPCM DSP driver looks much like a standard platform class ASoC driver
combined with elements from a codec class driver. A DSP platform driver must
implement :-
DPCM DSP驱动程序看起来很像标准平台级ASoC驱动程序，与编解码器类驱动程序中的元素
相结合。 DSP平台驱动程序必须实现： -
1) Front End PCM DAIs - i.e. struct snd_soc_dai_driver.
1）前端PCM DAI - 即struct snd_soc_dai_driver。
2) DAPM graph showing DSP audio routing from FE DAIs to BEs.
2）DAPM图，显示从FE DAI到BE的DSP音频路由。
3) DAPM widgets from DSP graph.
3）来自DSP图的DAPM小部件。
4) Mixers for gains, routing, etc.
4）用于增益，路由等的混频器
5) DMA configuration.
5）DMA配置。
6) BE AIF widgets.
6）BE AIF小部件。
Items 6 is important for routing the audio outside of the DSP. AIF need to be
defined for each BE and each stream direction. e.g for BE DAI0 above we would
have :-
第6项对于将音频路由到DSP之外非常重要。 需要为每个BE和每个流方向定义AIF。 例如，对
于上面的BE DAI0，我们会：
SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0),
SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0),
The BE AIF are used to connect the DSP graph to the graphs for the other
component drivers (e.g. codec graph).
BE AIF用于将DSP图形连接到其他组件驱动程序的图形（例如编解码器图形）。
Hostless PCM streams
====================
A hostless PCM stream is a stream that is not routed through the host CPU. An
example of this would be a phone call from handset to modem.
无主机PCM流是不通过主机CPU路由的流。 一个例子是从手机到调制解调器的电话。
*************
PCM0 <------------> * * <----DAI0-----> Codec Headset
* *
PCM1 <------------> * * <====DAI1=====> Codec Speakers/Mic
* DSP *
PCM2 <------------> * * <====DAI2=====> MODEM
* *
PCM3 <------------> * * <----DAI3-----> BT
* *
* * <----DAI4-----> DMIC
* *
* * <----DAI5-----> FM
*************
In this case the PCM data is routed via the DSP. The host CPU in this use case
is only used for control and can sleep during the runtime of the stream.
在这种情况下，PCM数据通过DSP路由。 此用例中的主机CPU仅用于控制，并且可以在流的
运行时期间休眠。
The host can control the hostless link either by :-
1) Configuring the link as a CODEC <-> CODEC style link. In this case the link
is enabled or disabled by the state of the DAPM graph. This usually means
there is a mixer control that can be used to connect or disconnect the path
between both DAIs.
1）将链路配置为CODEC < - > CODEC样式链接。 在这种情况下，链接由DAPM图的状态
启用或禁用。 这通常意味着有一个混音器控件可用于连接或断开两个DAI之间的路径。
2) Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM
graph. Control is then carried out by the FE as regular PCM operations.
This method gives more control over the DAI links, but requires much more
userspace code to control the link. Its recommended to use CODEC<->CODEC
unless your HW needs more fine grained sequencing of the PCM ops.
2）无主机FE。 此FE与DAPM图上的BE DAI链接具有虚拟连接。 然后由FE作为常规PCM操
作进行控制。 此方法可以更好地控制DAI链接，但需要更多用户空间代码来控制链接。 建议
使用CODEC < - > CODEC，除非你的硬件需要更精细的PCM操作顺序排序。
CODEC <-> CODEC link
--------------------
This DAI link is enabled when DAPM detects a valid path within the DAPM graph.
The machine driver sets some additional parameters to the DAI link i.e.
当DAPM在DAPM图中检测到有效路径时，将启用此DAI链接。
机器驱动程序为DAI链接设置一些附加参数，即
static const struct snd_soc_pcm_stream dai_params = {
.formats = SNDRV_PCM_FMTBIT_S32_LE,
.rate_min = 8000,
.rate_max = 8000,
.channels_min = 2,
.channels_max = 2,
};
static struct snd_soc_dai_link dais[] = {
< ... more DAI links above ... >
{
.name = "MODEM",
.stream_name = "MODEM",
.cpu_dai_name = "dai2",
.codec_dai_name = "modem-aif1",
.codec_name = "modem",
.dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
| SND_SOC_DAIFMT_CBM_CFM,
.params = &dai_params,
}
< ... more DAI links here ... >
These parameters are used to configure the DAI hw_params() when DAPM detects a
valid path and then calls the PCM operations to start the link. DAPM will also
call the appropriate PCM operations to disable the DAI when the path is no
longer valid.
这些参数用于在DAPM检测到有效路径时配置DAI hw_params（），然后调用PCM操作以启动
链接。 当路径不再有效时，DAPM还将调用适当的PCM操作以禁用DAI。
Hostless FE
-----------
The DAI link(s) are enabled by a FE that does not read or write any PCM data.
This means creating a new FE that is connected with a virtual path to both
DAI links. The DAI links will be started when the FE PCM is started and stopped
when the FE PCM is stopped. Note that the FE PCM cannot read or write data in
this configuration.
DAI链接由不读取或写入任何PCM数据的FE启用。这意味着创建一个与两个DAI链接的虚拟路
径相连的新FE。当FE PCM启动时，DAI链接将启动，当FE PCM停止时，将启动DAI链接。
请注意，FE PCM无法在此配置中读取或写入数据。