Documentation/sound/soc/dpcm.rst

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