Dynamic PCM

DPCM runtime routing

Dynamic PCM(DPCM)은 ALSA PCM device가 PCM stream 실행 중에 디지털 오디오를 여러 digital endpoint로 route할 수 있게 한다. 예를 들어 PCM0은 I2S DAI0, I2S DAI1 또는 PDM DAI2로 오디오를 보낼 수 있다. 여러 ALSA PCM을 노출하고 여러 DAI로 route할 수 있는 SoC DSP driver에 유용하다.

DPCM runtime route는 ASoC codec driver의 analog signal routing과 마찬가지로 ALSA mixer 설정으로 결정된다. DPCM은 DSP 내부 audio path를 나타내는 DAPM graph를 사용하고, mixer 설정으로 각 ALSA PCM이 사용할 path를 선택한다.

DPCM은 기존 component codec, platform, DAI driver를 수정하지 않고 그대로 재사용한다.

===========
Dynamic PCM
===========

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.

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 path used by each ALSA PCM.

DPCM re-uses all the existing component codec, platform and DAI drivers without
any modifications.

SoC DSP 기반 phone audio system

예제 smartphone audio subsystem은 Bluetooth, FM digital radio, speaker, headset jack, digital microphone, cellular modem을 지원한다. Sound card는 DSP front end(FE) ALSA PCM device 4개와 back end(BE) DAI 6개를 노출한다.

각 FE PCM은 어느 BE DAI로든 digital audio를 route할 수 있으며, 하나의 FE PCM을 둘 이상의 BE 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.



Example - DPCM Switching playback from DAI0 to DAI1

Playback을 DAI0에서 DAI1로 전환

처음에는 PCM0의 오디오가 DAI0을 통해 headset으로 재생된다. 사용자가 headset을 제거하면 재생을 멈추지 않고 DAI1의 speaker로 계속 출력해야 한다.

Machine driver가 jack removal event를 받고 machine driver 또는 audio HAL이 Headset path를 disable한다. DPCM은 비활성화된 DAI0에서 `trigger(stop)`, `hw_free()`, `shutdown()`을 실행한다.

그다음 machine driver 또는 audio HAL이 speaker path를 enable한다. DPCM은 새로 활성화된 DAI1 speaker에서 `startup()`, `hw_params()`, `prepare()`, `trigger(start)`를 실행한다.

Routing 변경 주체는 machine driver 또는 userspace audio HAL이고, DPCM이 link를 올리고 내리는 DAI PCM operation을 관리한다. 이 전환 중 audio playback은 중단되지 않는다.

---------------------------------------------------

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 <============> *           * <====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.

2. Machine driver OR audio HAL disables the Headset path.

3. DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0
   for headset since the path is now disabled.

4. Machine driver or audio HAL enables the speaker path.

5. DPCM runs the PCM ops for startup(), hw_params(), prepare() and
   trigger(start) for DAI1 Speakers since the path is enabled.

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.

DPCM machine driver 요구사항

DPCM을 사용하는 ASoC machine driver는 일반 machine driver와 비슷하지만 FE·BE DAI link, FE·BE PCM operation, widget graph connection을 추가로 정의해야 한다.

DPCM machine driver
===================

The DPCM enabled ASoC machine driver is similar to normal machine drivers
except that we also have to :-

1. Define the FE and BE DAI links.

2. Define any FE/BE PCM operations.

3. Define widget graph connections.

FE와 BE DAI link 설정

예제 topology에는 FE DAI link 4개와 BE DAI link 6개가 필요하다. PCM0 FE는 CPU component `System Pin`, dummy codec, platform `dsp-audio`를 `SND_SOC_DAILINK_DEFS`로 묶는다.

`PCM0 System` link는 stream name `System Playback`을 사용하고 `dynamic = 1`로 DPCM FE임을 표시한다. Playback·capture trigger ordering은 모두 `SND_SOC_DPCM_TRIGGER_POST`다. Trigger ordering을 지정하면 강한 DAI·DSP start/stop 순서 제약이 있는 DSP에서 core가 DSP를 다른 component 전 또는 후에 trigger할 수 있다.

FE의 codec과 codec DAI는 dummy device다. BE는 runtime 설정에 따라 동적으로 바뀌기 때문이다.

Headset BE는 CPU DAI `ssp-dai.0`과 codec `rt5640.0-001c`의 `rt5640-aif1`을 연결한다. `Codec Headset` link는 `no_pcm = 1`로 BE임을 표시하고 suspend와 PM down time을 무시하며 `be_hw_params_fixup`과 `ops`를 지정한다. 원문 설명의 `RT5460 AIF1` 표기도 원문 블록에 그대로 보존한다.

`ignore_suspend`와 `ignore_pmdown_time`을 사용하면 host CPU가 data를 전송하지 않는 BT phone call 같은 hostless mode에서도 BE가 계속 동작할 수 있다. Codec을 외부에서 관리하면 dummy codec을, CPU DAI를 DSP firmware가 관리하면 dummy CPU DAI를 BE에 둘 수도 있다.

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 :-
::

 SND_SOC_DAILINK_DEFS(pcm0,
	DAILINK_COMP_ARRAY(COMP_CPU("System Pin")),
	DAILINK_COMP_ARRAY(COMP_DUMMY()),
	DAILINK_COMP_ARRAY(COMP_PLATFORM("dsp-audio")));

  static struct snd_soc_dai_link machine_dais[] = {
	{
		.name = "PCM0 System",
		.stream_name = "System Playback",
		SND_SOC_DAILINK_REG(pcm0),
		.dynamic = 1,
		.trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST},
	},
	.....< 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``.
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).

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.

The BE DAIs are configured as follows :-
::

 SND_SOC_DAILINK_DEFS(headset,
	DAILINK_COMP_ARRAY(COMP_CPU("ssp-dai.0")),
	DAILINK_COMP_ARRAY(COMP_CODEC("rt5640.0-001c", "rt5640-aif1")));

  static struct snd_soc_dai_link machine_dais[] = {
	.....< FE DAI links here >
	{
		.name = "Codec Headset",
		SND_SOC_DAILINK_REG(headset),
		.no_pcm = 1,
		.ignore_suspend = 1,
		.ignore_pmdown_time = 1,
		.be_hw_params_fixup = hswult_ssp0_fixup,
		.ops = &haswell_ops,
	},
	.....< 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.

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 :-
::

                      *************
  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 while the DSP, MODEM DAI and the BT DAI are
still in operation.

A BE DAI link can also set the codec to a dummy device if the codec is a device
that is managed externally.

Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the
DSP firmware.


FE/BE PCM operations

FE·BE PCM operation과 fixup

BE는 일반 PCM operation과 함께 `fixup` callback을 내보낼 수 있다. Machine driver는 FE hw parameter를 바탕으로 DAI를 재설정하는 데 fixup을 사용한다. DSP가 FE와 BE 사이에서 SRC 또는 ASRC를 수행할 수 있기 때문이다.

예제에서는 DSP가 모든 FE parameter를 DAI0용 48 kHz, 16-bit, stereo로 변환한다. 따라서 `dai0_fixup()`은 rate interval의 min·max를 48000으로, channel interval의 min·max를 2로 고정하고 `params_set_format()`으로 `SNDRV_PCM_FORMAT_S16_LE`를 설정한다.

그 밖의 PCM operation은 일반 DAI link와 같으며 필요에 따라 사용한다.

--------------------

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.

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.
::

  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 convert the FE rate to 48k, stereo */
	rate->min = rate->max = 48000;
	channels->min = channels->max = 2;

	/* set DAI0 to 16 bit */
	params_set_format(params, SNDRV_PCM_FORMAT_S16_LE);
	return 0;
  }

The other PCM operation are the same as for regular DAI links. Use as necessary.


Widget graph connections

Dummy BE의 widget graph 연결

BE DAI link는 보통 초기화 때 ASoC DAPM core가 graph에 연결한다. 하지만 BE codec 또는 BE DAI가 dummy이면 driver가 명시적으로 route를 설정해야 한다.

Headset BE 예제에서는 DSP firmware가 관리하는 dummy DAI0을 codec AIF1에 연결한다. Capture route는 `AIF1 Capture`에서 `DAI0 CODEC IN`으로, playback route는 `DAI0 CODEC OUT`에서 `AIF1 Playback`으로 직접 이어진다.

------------------------

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 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

DPCM DSP driver 작성

DPCM DSP driver는 표준 platform class ASoC driver에 codec class driver의 요소를 결합한 형태다.

DSP platform driver는 `struct snd_soc_dai_driver`로 FE PCM DAI를 제공하고, FE에서 BE까지의 DSP audio route를 보여 주는 DAPM graph와 widget, gain·routing mixer, DMA 설정, BE AIF widget을 구현해야 한다.

BE AIF widget은 DSP 밖으로 audio를 route하는 데 특히 중요하다. 각 BE와 각 stream 방향마다 정의해야 한다. DAI0 예제는 `SND_SOC_DAPM_AIF_IN`으로 `DAI0 RX`, `SND_SOC_DAPM_AIF_OUT`으로 `DAI0 TX`를 만든다. 이 BE AIF가 DSP graph를 codec graph 같은 다른 component driver graph에 연결한다.

=========================

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 :-

1. Front End PCM DAIs - i.e. struct snd_soc_dai_driver.

2. DAPM graph showing DSP audio routing from FE DAIs to BEs.

3. DAPM widgets from DSP graph.

4. Mixers for gains, routing, etc.

5. DMA configuration.

6. BE AIF widgets.

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 :-
::

  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).

Hostless PCM stream

Hostless PCM stream은 host CPU를 통과하지 않는 stream이다. Handset과 modem 사이의 phone call이 예다. PCM data는 DSP를 통해 route되고 host CPU는 control에만 사용되므로 stream 실행 중 sleep할 수 있다.

Host는 두 방식으로 hostless link를 제어한다. 첫째, CODEC↔CODEC style link로 구성하면 DAPM graph 상태가 link를 enable·disable한다. 보통 mixer control이 두 DAI 사이 path를 연결하거나 끊는다.

둘째, hostless FE를 사용하면 FE가 DAPM graph에서 BE DAI link에 virtual connection을 갖고 일반 PCM operation으로 제어한다. 이 방법은 DAI link를 더 세밀하게 제어하지만 userspace 코드가 훨씬 많이 필요하다. Hardware가 PCM operation의 더 세밀한 sequencing을 요구하지 않으면 CODEC↔CODEC 방식이 권장된다.

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.
::

                      *************
  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.

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.

 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.

CODEC↔CODEC link

DAPM graph에서 유효한 path를 감지하면 CODEC↔CODEC DAI link가 enable된다. Machine driver는 link에 추가 stream parameter를 설정한다.

예제 `dai_params`는 `SNDRV_PCM_FMTBIT_S32_LE`, 8 kHz 고정 rate, 2 channel 고정 조건이다. `MODEM` DAI link는 CPU DAI `dai2`, codec DAI `modem-aif1`, codec `modem`을 I2S·NB_NF·CBP_CFP format으로 연결하고 `.c2c_params = &dai_params`, `.num_c2c_params = 1`을 지정한다.

DAPM이 유효한 path를 찾으면 이 parameter로 DAI `hw_params()`를 구성한 뒤 PCM operation을 호출해 link를 시작한다. Path가 더는 유효하지 않으면 적절한 PCM operation을 호출해 DAI를 disable한다.

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.
::

  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_CBP_CFP,
		.c2c_params = &dai_params,
		.num_c2c_params = 1,
	}
	< ... 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.

Hostless FE

Hostless FE는 PCM data를 읽거나 쓰지 않는 FE가 DAI link를 enable하는 방식이다. 새 FE를 만들고 DAPM graph에서 두 DAI link에 virtual path로 연결한다.

FE PCM을 시작하면 DAI link가 시작되고 FE PCM을 정지하면 link도 정지한다. 이 구성의 FE PCM은 data를 read하거나 write할 수 없다.

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.