1===========
2Dynamic PCM
3===========
4
5Description
6===========
7
8Dynamic PCM allows an ALSA PCM device to digitally route its PCM audio to
9various digital endpoints during the PCM stream runtime. e.g. PCM0 can route
10digital audio to I2S DAI0, I2S DAI1 or PDM DAI2. This is useful for on SoC DSP
11drivers that expose several ALSA PCMs and can route to multiple DAIs.
12
13The DPCM runtime routing is determined by the ALSA mixer settings in the same
14way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM
15graph representing the DSP internal audio paths and uses the mixer settings to
16determine the path used by each ALSA PCM.
17
18DPCM re-uses all the existing component codec, platform and DAI drivers without
19any modifications.
20
21
22Phone Audio System with SoC based DSP
23-------------------------------------
24
25Consider the following phone audio subsystem. This will be used in this
26document for all examples :-
27::
28
29  | Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
30
31                      *************
32  PCM0 <------------> *           * <----DAI0-----> Codec Headset
33                      *           *
34  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
35                      *   DSP     *
36  PCM2 <------------> *           * <----DAI2-----> MODEM
37                      *           *
38  PCM3 <------------> *           * <----DAI3-----> BT
39                      *           *
40                      *           * <----DAI4-----> DMIC
41                      *           *
42                      *           * <----DAI5-----> FM
43                      *************
44
45This diagram shows a simple smart phone audio subsystem. It supports Bluetooth,
46FM digital radio, Speakers, Headset Jack, digital microphones and cellular
47modem. This sound card exposes 4 DSP front end (FE) ALSA PCM devices and
48supports 6 back end (BE) DAIs. Each FE PCM can digitally route audio data to any
49of the BE DAIs. The FE PCM devices can also route audio to more than 1 BE DAI.
50
51
52
53Example - DPCM Switching playback from DAI0 to DAI1
54---------------------------------------------------
55
56Audio is being played to the Headset. After a while the user removes the headset
57and audio continues playing on the speakers.
58
59Playback on PCM0 to Headset would look like :-
60::
61
62                      *************
63  PCM0 <============> *           * <====DAI0=====> Codec Headset
64                      *           *
65  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
66                      *   DSP     *
67  PCM2 <------------> *           * <----DAI2-----> MODEM
68                      *           *
69  PCM3 <------------> *           * <----DAI3-----> BT
70                      *           *
71                      *           * <----DAI4-----> DMIC
72                      *           *
73                      *           * <----DAI5-----> FM
74                      *************
75
76The headset is removed from the jack by user so the speakers must now be used :-
77::
78
79                      *************
80  PCM0 <============> *           * <----DAI0-----> Codec Headset
81                      *           *
82  PCM1 <------------> *           * <====DAI1=====> Codec Speakers
83                      *   DSP     *
84  PCM2 <------------> *           * <----DAI2-----> MODEM
85                      *           *
86  PCM3 <------------> *           * <----DAI3-----> BT
87                      *           *
88                      *           * <----DAI4-----> DMIC
89                      *           *
90                      *           * <----DAI5-----> FM
91                      *************
92
93The audio driver processes this as follows :-
94
951. Machine driver receives Jack removal event.
96
972. Machine driver OR audio HAL disables the Headset path.
98
993. DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0
100   for headset since the path is now disabled.
101
1024. Machine driver or audio HAL enables the speaker path.
103
1045. DPCM runs the PCM ops for startup(), hw_params(), prepare() and
105   trigger(start) for DAI1 Speakers since the path is enabled.
106
107In this example, the machine driver or userspace audio HAL can alter the routing
108and then DPCM will take care of managing the DAI PCM operations to either bring
109the link up or down. Audio playback does not stop during this transition.
110
111
112
113DPCM machine driver
114===================
115
116The DPCM enabled ASoC machine driver is similar to normal machine drivers
117except that we also have to :-
118
1191. Define the FE and BE DAI links.
120
1212. Define any FE/BE PCM operations.
122
1233. Define widget graph connections.
124
125
126FE and BE DAI links
127-------------------
128::
129
130  | Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
131
132                      *************
133  PCM0 <------------> *           * <----DAI0-----> Codec Headset
134                      *           *
135  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
136                      *   DSP     *
137  PCM2 <------------> *           * <----DAI2-----> MODEM
138                      *           *
139  PCM3 <------------> *           * <----DAI3-----> BT
140                      *           *
141                      *           * <----DAI4-----> DMIC
142                      *           *
143                      *           * <----DAI5-----> FM
144                      *************
145
146For the example above we have to define 4 FE DAI links and 6 BE DAI links. The
147FE DAI links are defined as follows :-
148::
149
150 SND_SOC_DAILINK_DEFS(pcm0,
151	DAILINK_COMP_ARRAY(COMP_CPU("System Pin")),
152	DAILINK_COMP_ARRAY(COMP_DUMMY()),
153	DAILINK_COMP_ARRAY(COMP_PLATFORM("dsp-audio")));
154
155  static struct snd_soc_dai_link machine_dais[] = {
156	{
157		.name = "PCM0 System",
158		.stream_name = "System Playback",
159		SND_SOC_DAILINK_REG(pcm0),
160		.dynamic = 1,
161		.trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST},
162	},
163	.....< other FE and BE DAI links here >
164  };
165
166This FE DAI link is pretty similar to a regular DAI link except that we also
167set the DAI link to a DPCM FE with the ``dynamic = 1``.
168There is also an option to specify the ordering of the trigger call for
169each FE. This allows the ASoC core to trigger the DSP before or after the other
170components (as some DSPs have strong requirements for the ordering DAI/DSP
171start and stop sequences).
172
173The FE DAI above sets the codec and code DAIs to dummy devices since the BE is
174dynamic and will change depending on runtime config.
175
176The BE DAIs are configured as follows :-
177::
178
179 SND_SOC_DAILINK_DEFS(headset,
180	DAILINK_COMP_ARRAY(COMP_CPU("ssp-dai.0")),
181	DAILINK_COMP_ARRAY(COMP_CODEC("rt5640.0-001c", "rt5640-aif1")));
182
183  static struct snd_soc_dai_link machine_dais[] = {
184	.....< FE DAI links here >
185	{
186		.name = "Codec Headset",
187		SND_SOC_DAILINK_REG(headset),
188		.no_pcm = 1,
189		.ignore_suspend = 1,
190		.ignore_pmdown_time = 1,
191		.be_hw_params_fixup = hswult_ssp0_fixup,
192		.ops = &haswell_ops,
193	},
194	.....< other BE DAI links here >
195  };
196
197This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets
198the ``no_pcm`` flag to mark it has a BE.
199
200The BE has also flags set for ignoring suspend and PM down time. This allows
201the BE to work in a hostless mode where the host CPU is not transferring data
202like a BT phone call :-
203::
204
205                      *************
206  PCM0 <------------> *           * <----DAI0-----> Codec Headset
207                      *           *
208  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
209                      *   DSP     *
210  PCM2 <------------> *           * <====DAI2=====> MODEM
211                      *           *
212  PCM3 <------------> *           * <====DAI3=====> BT
213                      *           *
214                      *           * <----DAI4-----> DMIC
215                      *           *
216                      *           * <----DAI5-----> FM
217                      *************
218
219This allows the host CPU to sleep while the DSP, MODEM DAI and the BT DAI are
220still in operation.
221
222A BE DAI link can also set the codec to a dummy device if the codec is a device
223that is managed externally.
224
225Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the
226DSP firmware.
227
228
229FE/BE PCM operations
230--------------------
231
232The BE above also exports some PCM operations and a ``fixup`` callback. The fixup
233callback is used by the machine driver to (re)configure the DAI based upon the
234FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE.
235
236e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for
237DAI0. This means all FE hw_params have to be fixed in the machine driver for
238DAI0 so that the DAI is running at desired configuration regardless of the FE
239configuration.
240::
241
242  static int dai0_fixup(struct snd_soc_pcm_runtime *rtd,
243			struct snd_pcm_hw_params *params)
244  {
245	struct snd_interval *rate = hw_param_interval(params,
246			SNDRV_PCM_HW_PARAM_RATE);
247	struct snd_interval *channels = hw_param_interval(params,
248						SNDRV_PCM_HW_PARAM_CHANNELS);
249
250	/* The DSP will convert the FE rate to 48k, stereo */
251	rate->min = rate->max = 48000;
252	channels->min = channels->max = 2;
253
254	/* set DAI0 to 16 bit */
255	params_set_format(params, SNDRV_PCM_FORMAT_S16_LE);
256	return 0;
257  }
258
259The other PCM operation are the same as for regular DAI links. Use as necessary.
260
261
262Widget graph connections
263------------------------
264
265The BE DAI links will normally be connected to the graph at initialisation time
266by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this
267has to be set explicitly in the driver :-
268::
269
270  /* BE for codec Headset -  DAI0 is dummy and managed by DSP FW */
271  {"DAI0 CODEC IN", NULL, "AIF1 Capture"},
272  {"AIF1 Playback", NULL, "DAI0 CODEC OUT"},
273
274
275Writing a DPCM DSP driver
276=========================
277
278The DPCM DSP driver looks much like a standard platform class ASoC driver
279combined with elements from a codec class driver. A DSP platform driver must
280implement :-
281
2821. Front End PCM DAIs - i.e. struct snd_soc_dai_driver.
283
2842. DAPM graph showing DSP audio routing from FE DAIs to BEs.
285
2863. DAPM widgets from DSP graph.
287
2884. Mixers for gains, routing, etc.
289
2905. DMA configuration.
291
2926. BE AIF widgets.
293
294Items 6 is important for routing the audio outside of the DSP. AIF need to be
295defined for each BE and each stream direction. e.g for BE DAI0 above we would
296have :-
297::
298
299  SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0),
300  SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0),
301
302The BE AIF are used to connect the DSP graph to the graphs for the other
303component drivers (e.g. codec graph).
304
305
306Hostless PCM streams
307====================
308
309A hostless PCM stream is a stream that is not routed through the host CPU. An
310example of this would be a phone call from handset to modem.
311::
312
313                      *************
314  PCM0 <------------> *           * <----DAI0-----> Codec Headset
315                      *           *
316  PCM1 <------------> *           * <====DAI1=====> Codec Speakers/Mic
317                      *   DSP     *
318  PCM2 <------------> *           * <====DAI2=====> MODEM
319                      *           *
320  PCM3 <------------> *           * <----DAI3-----> BT
321                      *           *
322                      *           * <----DAI4-----> DMIC
323                      *           *
324                      *           * <----DAI5-----> FM
325                      *************
326
327In this case the PCM data is routed via the DSP. The host CPU in this use case
328is only used for control and can sleep during the runtime of the stream.
329
330The host can control the hostless link either by :-
331
332 1. Configuring the link as a CODEC <-> CODEC style link. In this case the link
333    is enabled or disabled by the state of the DAPM graph. This usually means
334    there is a mixer control that can be used to connect or disconnect the path
335    between both DAIs.
336
337 2. Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM
338    graph. Control is then carried out by the FE as regular PCM operations.
339    This method gives more control over the DAI links, but requires much more
340    userspace code to control the link. Its recommended to use CODEC<->CODEC
341    unless your HW needs more fine grained sequencing of the PCM ops.
342
343
344CODEC <-> CODEC link
345--------------------
346
347This DAI link is enabled when DAPM detects a valid path within the DAPM graph.
348The machine driver sets some additional parameters to the DAI link i.e.
349::
350
351  static const struct snd_soc_pcm_stream dai_params = {
352	.formats = SNDRV_PCM_FMTBIT_S32_LE,
353	.rate_min = 8000,
354	.rate_max = 8000,
355	.channels_min = 2,
356	.channels_max = 2,
357  };
358
359  static struct snd_soc_dai_link dais[] = {
360	< ... more DAI links above ... >
361	{
362		.name = "MODEM",
363		.stream_name = "MODEM",
364		.cpu_dai_name = "dai2",
365		.codec_dai_name = "modem-aif1",
366		.codec_name = "modem",
367		.dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
368				| SND_SOC_DAIFMT_CBP_CFP,
369		.c2c_params = &dai_params,
370		.num_c2c_params = 1,
371	}
372	< ... more DAI links here ... >
373
374These parameters are used to configure the DAI hw_params() when DAPM detects a
375valid path and then calls the PCM operations to start the link. DAPM will also
376call the appropriate PCM operations to disable the DAI when the path is no
377longer valid.
378
379
380Hostless FE
381-----------
382
383The DAI link(s) are enabled by a FE that does not read or write any PCM data.
384This means creating a new FE that is connected with a virtual path to both
385DAI links. The DAI links will be started when the FE PCM is started and stopped
386when the FE PCM is stopped. Note that the FE PCM cannot read or write data in
387this configuration.
388