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