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 patch 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(), prepapre() 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 static struct snd_soc_dai_link machine_dais[] = { 151 { 152 .name = "PCM0 System", 153 .stream_name = "System Playback", 154 .cpu_dai_name = "System Pin", 155 .platform_name = "dsp-audio", 156 .codec_name = "snd-soc-dummy", 157 .codec_dai_name = "snd-soc-dummy-dai", 158 .dynamic = 1, 159 .trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST}, 160 .dpcm_playback = 1, 161 }, 162 .....< other FE and BE DAI links here > 163 }; 164 165This FE DAI link is pretty similar to a regular DAI link except that we also 166set the DAI link to a DPCM FE with the ``dynamic = 1``. The supported FE stream 167directions should also be set with the ``dpcm_playback`` and ``dpcm_capture`` 168flags. There 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 static struct snd_soc_dai_link machine_dais[] = { 180 .....< FE DAI links here > 181 { 182 .name = "Codec Headset", 183 .cpu_dai_name = "ssp-dai.0", 184 .platform_name = "snd-soc-dummy", 185 .no_pcm = 1, 186 .codec_name = "rt5640.0-001c", 187 .codec_dai_name = "rt5640-aif1", 188 .ignore_suspend = 1, 189 .ignore_pmdown_time = 1, 190 .be_hw_params_fixup = hswult_ssp0_fixup, 191 .ops = &haswell_ops, 192 .dpcm_playback = 1, 193 .dpcm_capture = 1, 194 }, 195 .....< other BE DAI links here > 196 }; 197 198This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets 199the ``no_pcm`` flag to mark it has a BE and sets flags for supported stream 200directions using ``dpcm_playback`` and ``dpcm_capture`` above. 201 202The BE has also flags set for ignoring suspend and PM down time. This allows 203the BE to work in a hostless mode where the host CPU is not transferring data 204like a BT phone call :- 205:: 206 207 ************* 208 PCM0 <------------> * * <----DAI0-----> Codec Headset 209 * * 210 PCM1 <------------> * * <----DAI1-----> Codec Speakers 211 * DSP * 212 PCM2 <------------> * * <====DAI2=====> MODEM 213 * * 214 PCM3 <------------> * * <====DAI3=====> BT 215 * * 216 * * <----DAI4-----> DMIC 217 * * 218 * * <----DAI5-----> FM 219 ************* 220 221This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are 222still in operation. 223 224A BE DAI link can also set the codec to a dummy device if the code is a device 225that is managed externally. 226 227Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the 228DSP firmware. 229 230 231FE/BE PCM operations 232-------------------- 233 234The BE above also exports some PCM operations and a ``fixup`` callback. The fixup 235callback is used by the machine driver to (re)configure the DAI based upon the 236FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE. 237 238e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for 239DAI0. This means all FE hw_params have to be fixed in the machine driver for 240DAI0 so that the DAI is running at desired configuration regardless of the FE 241configuration. 242:: 243 244 static int dai0_fixup(struct snd_soc_pcm_runtime *rtd, 245 struct snd_pcm_hw_params *params) 246 { 247 struct snd_interval *rate = hw_param_interval(params, 248 SNDRV_PCM_HW_PARAM_RATE); 249 struct snd_interval *channels = hw_param_interval(params, 250 SNDRV_PCM_HW_PARAM_CHANNELS); 251 252 /* The DSP will covert the FE rate to 48k, stereo */ 253 rate->min = rate->max = 48000; 254 channels->min = channels->max = 2; 255 256 /* set DAI0 to 16 bit */ 257 snd_mask_set(¶ms->masks[SNDRV_PCM_HW_PARAM_FORMAT - 258 SNDRV_PCM_HW_PARAM_FIRST_MASK], 259 SNDRV_PCM_FORMAT_S16_LE); 260 return 0; 261 } 262 263The other PCM operation are the same as for regular DAI links. Use as necessary. 264 265 266Widget graph connections 267------------------------ 268 269The BE DAI links will normally be connected to the graph at initialisation time 270by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this 271has to be set explicitly in the driver :- 272:: 273 274 /* BE for codec Headset - DAI0 is dummy and managed by DSP FW */ 275 {"DAI0 CODEC IN", NULL, "AIF1 Capture"}, 276 {"AIF1 Playback", NULL, "DAI0 CODEC OUT"}, 277 278 279Writing a DPCM DSP driver 280========================= 281 282The DPCM DSP driver looks much like a standard platform class ASoC driver 283combined with elements from a codec class driver. A DSP platform driver must 284implement :- 285 2861. Front End PCM DAIs - i.e. struct snd_soc_dai_driver. 287 2882. DAPM graph showing DSP audio routing from FE DAIs to BEs. 289 2903. DAPM widgets from DSP graph. 291 2924. Mixers for gains, routing, etc. 293 2945. DMA configuration. 295 2966. BE AIF widgets. 297 298Items 6 is important for routing the audio outside of the DSP. AIF need to be 299defined for each BE and each stream direction. e.g for BE DAI0 above we would 300have :- 301:: 302 303 SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0), 304 SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0), 305 306The BE AIF are used to connect the DSP graph to the graphs for the other 307component drivers (e.g. codec graph). 308 309 310Hostless PCM streams 311==================== 312 313A hostless PCM stream is a stream that is not routed through the host CPU. An 314example of this would be a phone call from handset to modem. 315:: 316 317 ************* 318 PCM0 <------------> * * <----DAI0-----> Codec Headset 319 * * 320 PCM1 <------------> * * <====DAI1=====> Codec Speakers/Mic 321 * DSP * 322 PCM2 <------------> * * <====DAI2=====> MODEM 323 * * 324 PCM3 <------------> * * <----DAI3-----> BT 325 * * 326 * * <----DAI4-----> DMIC 327 * * 328 * * <----DAI5-----> FM 329 ************* 330 331In this case the PCM data is routed via the DSP. The host CPU in this use case 332is only used for control and can sleep during the runtime of the stream. 333 334The host can control the hostless link either by :- 335 336 1. Configuring the link as a CODEC <-> CODEC style link. In this case the link 337 is enabled or disabled by the state of the DAPM graph. This usually means 338 there is a mixer control that can be used to connect or disconnect the path 339 between both DAIs. 340 341 2. Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM 342 graph. Control is then carried out by the FE as regular PCM operations. 343 This method gives more control over the DAI links, but requires much more 344 userspace code to control the link. Its recommended to use CODEC<->CODEC 345 unless your HW needs more fine grained sequencing of the PCM ops. 346 347 348CODEC <-> CODEC link 349-------------------- 350 351This DAI link is enabled when DAPM detects a valid path within the DAPM graph. 352The machine driver sets some additional parameters to the DAI link i.e. 353:: 354 355 static const struct snd_soc_pcm_stream dai_params = { 356 .formats = SNDRV_PCM_FMTBIT_S32_LE, 357 .rate_min = 8000, 358 .rate_max = 8000, 359 .channels_min = 2, 360 .channels_max = 2, 361 }; 362 363 static struct snd_soc_dai_link dais[] = { 364 < ... more DAI links above ... > 365 { 366 .name = "MODEM", 367 .stream_name = "MODEM", 368 .cpu_dai_name = "dai2", 369 .codec_dai_name = "modem-aif1", 370 .codec_name = "modem", 371 .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF 372 | SND_SOC_DAIFMT_CBM_CFM, 373 .params = &dai_params, 374 } 375 < ... more DAI links here ... > 376 377These parameters are used to configure the DAI hw_params() when DAPM detects a 378valid path and then calls the PCM operations to start the link. DAPM will also 379call the appropriate PCM operations to disable the DAI when the path is no 380longer valid. 381 382 383Hostless FE 384----------- 385 386The DAI link(s) are enabled by a FE that does not read or write any PCM data. 387This means creating a new FE that is connected with a virtual path to both 388DAI links. The DAI links will be started when the FE PCM is started and stopped 389when the FE PCM is stopped. Note that the FE PCM cannot read or write data in 390this configuration. 391 392 393