include/sound/soc-dai.h

   1 /* SPDX-License-Identifier: GPL-2.0
   2  *
   3  * linux/sound/soc-dai.h -- ALSA SoC Layer
   4  *
   5  * Copyright:   2005-2008 Wolfson Microelectronics. PLC.
   6  *
   7  * Digital Audio Interface (DAI) API.
   8  */
   9
  10 #ifndef __LINUX_SND_SOC_DAI_H
  11 #define __LINUX_SND_SOC_DAI_H
  12
  13
  14 #include <linux/list.h>
  15 #include <sound/asoc.h>
  16
  17 struct snd_pcm_substream;
  18 struct snd_soc_dapm_widget;
  19 struct snd_compr_stream;
  20
  21 /*
  22  * DAI hardware audio formats.
  23  *
  24  * Describes the physical PCM data formating and clocking. Add new formats
  25  * to the end.
  26  */
  27 #define SND_SOC_DAIFMT_I2S              SND_SOC_DAI_FORMAT_I2S
  28 #define SND_SOC_DAIFMT_RIGHT_J          SND_SOC_DAI_FORMAT_RIGHT_J
  29 #define SND_SOC_DAIFMT_LEFT_J           SND_SOC_DAI_FORMAT_LEFT_J
  30 #define SND_SOC_DAIFMT_DSP_A            SND_SOC_DAI_FORMAT_DSP_A
  31 #define SND_SOC_DAIFMT_DSP_B            SND_SOC_DAI_FORMAT_DSP_B
  32 #define SND_SOC_DAIFMT_AC97             SND_SOC_DAI_FORMAT_AC97
  33 #define SND_SOC_DAIFMT_PDM              SND_SOC_DAI_FORMAT_PDM
  34
  35 /* left and right justified also known as MSB and LSB respectively */
  36 #define SND_SOC_DAIFMT_MSB              SND_SOC_DAIFMT_LEFT_J
  37 #define SND_SOC_DAIFMT_LSB              SND_SOC_DAIFMT_RIGHT_J
  38
  39 /*
  40  * DAI Clock gating.
  41  *
  42  * DAI bit clocks can be gated (disabled) when the DAI is not
  43  * sending or receiving PCM data in a frame. This can be used to save power.
  44  */
  45 #define SND_SOC_DAIFMT_CONT             (1 << 4) /* continuous clock */
  46 #define SND_SOC_DAIFMT_GATED            (0 << 4) /* clock is gated */
  47
  48 /*
  49  * DAI hardware signal polarity.
  50  *
  51  * Specifies whether the DAI can also support inverted clocks for the specified
  52  * format.
  53  *
  54  * BCLK:
  55  * - "normal" polarity means signal is available at rising edge of BCLK
  56  * - "inverted" polarity means signal is available at falling edge of BCLK
  57  *
  58  * FSYNC "normal" polarity depends on the frame format:
  59  * - I2S: frame consists of left then right channel data. Left channel starts
  60  *      with falling FSYNC edge, right channel starts with rising FSYNC edge.
  61  * - Left/Right Justified: frame consists of left then right channel data.
  62  *      Left channel starts with rising FSYNC edge, right channel starts with
  63  *      falling FSYNC edge.
  64  * - DSP A/B: Frame starts with rising FSYNC edge.
  65  * - AC97: Frame starts with rising FSYNC edge.
  66  *
  67  * "Negative" FSYNC polarity is the one opposite of "normal" polarity.
  68  */
  69 #define SND_SOC_DAIFMT_NB_NF            (0 << 8) /* normal bit clock + frame */
  70 #define SND_SOC_DAIFMT_NB_IF            (2 << 8) /* normal BCLK + inv FRM */
  71 #define SND_SOC_DAIFMT_IB_NF            (3 << 8) /* invert BCLK + nor FRM */
  72 #define SND_SOC_DAIFMT_IB_IF            (4 << 8) /* invert BCLK + FRM */
  73
  74 /*
  75  * DAI hardware clock providers/consumers
  76  *
  77  * This is wrt the codec, the inverse is true for the interface
  78  * i.e. if the codec is clk and FRM provider then the interface is
  79  * clk and frame consumer.
  80  */
  81 #define SND_SOC_DAIFMT_CBP_CFP          (1 << 12) /* codec clk provider & frame provider */
  82 #define SND_SOC_DAIFMT_CBC_CFP          (2 << 12) /* codec clk consumer & frame provider */
  83 #define SND_SOC_DAIFMT_CBP_CFC          (3 << 12) /* codec clk provider & frame consumer */
  84 #define SND_SOC_DAIFMT_CBC_CFC          (4 << 12) /* codec clk consumer & frame follower */
  85
  86 /* previous definitions kept for backwards-compatibility, do not use in new contributions */
  87 #define SND_SOC_DAIFMT_CBM_CFM          SND_SOC_DAIFMT_CBP_CFP
  88 #define SND_SOC_DAIFMT_CBS_CFM          SND_SOC_DAIFMT_CBC_CFP
  89 #define SND_SOC_DAIFMT_CBM_CFS          SND_SOC_DAIFMT_CBP_CFC
  90 #define SND_SOC_DAIFMT_CBS_CFS          SND_SOC_DAIFMT_CBC_CFC
  91
  92 #define SND_SOC_DAIFMT_FORMAT_MASK              0x000f
  93 #define SND_SOC_DAIFMT_CLOCK_MASK               0x00f0
  94 #define SND_SOC_DAIFMT_INV_MASK                 0x0f00
  95 #define SND_SOC_DAIFMT_CLOCK_PROVIDER_MASK      0xf000
  96
  97 #define SND_SOC_DAIFMT_MASTER_MASK      SND_SOC_DAIFMT_CLOCK_PROVIDER_MASK
  98
  99 /*
 100  * Master Clock Directions
 101  */
 102 #define SND_SOC_CLOCK_IN                0
 103 #define SND_SOC_CLOCK_OUT               1
 104
 105 #define SND_SOC_STD_AC97_FMTS (SNDRV_PCM_FMTBIT_S8 |\
 106                                SNDRV_PCM_FMTBIT_S16_LE |\
 107                                SNDRV_PCM_FMTBIT_S16_BE |\
 108                                SNDRV_PCM_FMTBIT_S20_3LE |\
 109                                SNDRV_PCM_FMTBIT_S20_3BE |\
 110                                SNDRV_PCM_FMTBIT_S20_LE |\
 111                                SNDRV_PCM_FMTBIT_S20_BE |\
 112                                SNDRV_PCM_FMTBIT_S24_3LE |\
 113                                SNDRV_PCM_FMTBIT_S24_3BE |\
 114                                SNDRV_PCM_FMTBIT_S32_LE |\
 115                                SNDRV_PCM_FMTBIT_S32_BE)
 116
 117 struct snd_soc_dai_driver;
 118 struct snd_soc_dai;
 119 struct snd_ac97_bus_ops;
 120
 121 /* Digital Audio Interface clocking API.*/
 122 int snd_soc_dai_set_sysclk(struct snd_soc_dai *dai, int clk_id,
 123         unsigned int freq, int dir);
 124
 125 int snd_soc_dai_set_clkdiv(struct snd_soc_dai *dai,
 126         int div_id, int div);
 127
 128 int snd_soc_dai_set_pll(struct snd_soc_dai *dai,
 129         int pll_id, int source, unsigned int freq_in, unsigned int freq_out);
 130
 131 int snd_soc_dai_set_bclk_ratio(struct snd_soc_dai *dai, unsigned int ratio);
 132
 133 /* Digital Audio interface formatting */
 134 int snd_soc_dai_set_fmt(struct snd_soc_dai *dai, unsigned int fmt);
 135
 136 int snd_soc_dai_set_tdm_slot(struct snd_soc_dai *dai,
 137         unsigned int tx_mask, unsigned int rx_mask, int slots, int slot_width);
 138
 139 int snd_soc_dai_set_channel_map(struct snd_soc_dai *dai,
 140         unsigned int tx_num, unsigned int *tx_slot,
 141         unsigned int rx_num, unsigned int *rx_slot);
 142
 143 int snd_soc_dai_set_tristate(struct snd_soc_dai *dai, int tristate);
 144
 145 /* Digital Audio Interface mute */
 146 int snd_soc_dai_digital_mute(struct snd_soc_dai *dai, int mute,
 147                              int direction);
 148
 149
 150 int snd_soc_dai_get_channel_map(struct snd_soc_dai *dai,
 151                 unsigned int *tx_num, unsigned int *tx_slot,
 152                 unsigned int *rx_num, unsigned int *rx_slot);
 153
 154 int snd_soc_dai_is_dummy(struct snd_soc_dai *dai);
 155
 156 int snd_soc_dai_hw_params(struct snd_soc_dai *dai,
 157                           struct snd_pcm_substream *substream,
 158                           struct snd_pcm_hw_params *params);
 159 void snd_soc_dai_hw_free(struct snd_soc_dai *dai,
 160                          struct snd_pcm_substream *substream,
 161                          int rollback);
 162 int snd_soc_dai_startup(struct snd_soc_dai *dai,
 163                         struct snd_pcm_substream *substream);
 164 void snd_soc_dai_shutdown(struct snd_soc_dai *dai,
 165                           struct snd_pcm_substream *substream, int rollback);
 166 snd_pcm_sframes_t snd_soc_dai_delay(struct snd_soc_dai *dai,
 167                                     struct snd_pcm_substream *substream);
 168 void snd_soc_dai_suspend(struct snd_soc_dai *dai);
 169 void snd_soc_dai_resume(struct snd_soc_dai *dai);
 170 int snd_soc_dai_compress_new(struct snd_soc_dai *dai,
 171                              struct snd_soc_pcm_runtime *rtd, int num);
 172 bool snd_soc_dai_stream_valid(struct snd_soc_dai *dai, int stream);
 173 void snd_soc_dai_link_set_capabilities(struct snd_soc_dai_link *dai_link);
 174 void snd_soc_dai_action(struct snd_soc_dai *dai,
 175                         int stream, int action);
 176 static inline void snd_soc_dai_activate(struct snd_soc_dai *dai,
 177                                         int stream)
 178 {
 179         snd_soc_dai_action(dai, stream,  1);
 180 }
 181 static inline void snd_soc_dai_deactivate(struct snd_soc_dai *dai,
 182                                           int stream)
 183 {
 184         snd_soc_dai_action(dai, stream, -1);
 185 }
 186 int snd_soc_dai_active(struct snd_soc_dai *dai);
 187
 188 int snd_soc_pcm_dai_probe(struct snd_soc_pcm_runtime *rtd, int order);
 189 int snd_soc_pcm_dai_remove(struct snd_soc_pcm_runtime *rtd, int order);
 190 int snd_soc_pcm_dai_new(struct snd_soc_pcm_runtime *rtd);
 191 int snd_soc_pcm_dai_prepare(struct snd_pcm_substream *substream);
 192 int snd_soc_pcm_dai_trigger(struct snd_pcm_substream *substream, int cmd,
 193                             int rollback);
 194 int snd_soc_pcm_dai_bespoke_trigger(struct snd_pcm_substream *substream,
 195                                     int cmd);
 196
 197 int snd_soc_dai_compr_startup(struct snd_soc_dai *dai,
 198                               struct snd_compr_stream *cstream);
 199 void snd_soc_dai_compr_shutdown(struct snd_soc_dai *dai,
 200                                 struct snd_compr_stream *cstream,
 201                                 int rollback);
 202 int snd_soc_dai_compr_trigger(struct snd_soc_dai *dai,
 203                               struct snd_compr_stream *cstream, int cmd);
 204 int snd_soc_dai_compr_set_params(struct snd_soc_dai *dai,
 205                                  struct snd_compr_stream *cstream,
 206                                  struct snd_compr_params *params);
 207 int snd_soc_dai_compr_get_params(struct snd_soc_dai *dai,
 208                                  struct snd_compr_stream *cstream,
 209                                  struct snd_codec *params);
 210 int snd_soc_dai_compr_ack(struct snd_soc_dai *dai,
 211                           struct snd_compr_stream *cstream,
 212                           size_t bytes);
 213 int snd_soc_dai_compr_pointer(struct snd_soc_dai *dai,
 214                               struct snd_compr_stream *cstream,
 215                               struct snd_compr_tstamp *tstamp);
 216 int snd_soc_dai_compr_set_metadata(struct snd_soc_dai *dai,
 217                                    struct snd_compr_stream *cstream,
 218                                    struct snd_compr_metadata *metadata);
 219 int snd_soc_dai_compr_get_metadata(struct snd_soc_dai *dai,
 220                                    struct snd_compr_stream *cstream,
 221                                    struct snd_compr_metadata *metadata);
 222
 223 struct snd_soc_dai_ops {
 224         /*
 225          * DAI clocking configuration, all optional.
 226          * Called by soc_card drivers, normally in their hw_params.
 227          */
 228         int (*set_sysclk)(struct snd_soc_dai *dai,
 229                 int clk_id, unsigned int freq, int dir);
 230         int (*set_pll)(struct snd_soc_dai *dai, int pll_id, int source,
 231                 unsigned int freq_in, unsigned int freq_out);
 232         int (*set_clkdiv)(struct snd_soc_dai *dai, int div_id, int div);
 233         int (*set_bclk_ratio)(struct snd_soc_dai *dai, unsigned int ratio);
 234
 235         /*
 236          * DAI format configuration
 237          * Called by soc_card drivers, normally in their hw_params.
 238          */
 239         int (*set_fmt)(struct snd_soc_dai *dai, unsigned int fmt);
 240         int (*xlate_tdm_slot_mask)(unsigned int slots,
 241                 unsigned int *tx_mask, unsigned int *rx_mask);
 242         int (*set_tdm_slot)(struct snd_soc_dai *dai,
 243                 unsigned int tx_mask, unsigned int rx_mask,
 244                 int slots, int slot_width);
 245         int (*set_channel_map)(struct snd_soc_dai *dai,
 246                 unsigned int tx_num, unsigned int *tx_slot,
 247                 unsigned int rx_num, unsigned int *rx_slot);
 248         int (*get_channel_map)(struct snd_soc_dai *dai,
 249                         unsigned int *tx_num, unsigned int *tx_slot,
 250                         unsigned int *rx_num, unsigned int *rx_slot);
 251         int (*set_tristate)(struct snd_soc_dai *dai, int tristate);
 252
 253         int (*set_sdw_stream)(struct snd_soc_dai *dai,
 254                         void *stream, int direction);
 255         void *(*get_sdw_stream)(struct snd_soc_dai *dai, int direction);
 256
 257         /*
 258          * DAI digital mute - optional.
 259          * Called by soc-core to minimise any pops.
 260          */
 261         int (*mute_stream)(struct snd_soc_dai *dai, int mute, int stream);
 262
 263         /*
 264          * ALSA PCM audio operations - all optional.
 265          * Called by soc-core during audio PCM operations.
 266          */
 267         int (*startup)(struct snd_pcm_substream *,
 268                 struct snd_soc_dai *);
 269         void (*shutdown)(struct snd_pcm_substream *,
 270                 struct snd_soc_dai *);
 271         int (*hw_params)(struct snd_pcm_substream *,
 272                 struct snd_pcm_hw_params *, struct snd_soc_dai *);
 273         int (*hw_free)(struct snd_pcm_substream *,
 274                 struct snd_soc_dai *);
 275         int (*prepare)(struct snd_pcm_substream *,
 276                 struct snd_soc_dai *);
 277         /*
 278          * NOTE: Commands passed to the trigger function are not necessarily
 279          * compatible with the current state of the dai. For example this
 280          * sequence of commands is possible: START STOP STOP.
 281          * So do not unconditionally use refcounting functions in the trigger
 282          * function, e.g. clk_enable/disable.
 283          */
 284         int (*trigger)(struct snd_pcm_substream *, int,
 285                 struct snd_soc_dai *);
 286         int (*bespoke_trigger)(struct snd_pcm_substream *, int,
 287                 struct snd_soc_dai *);
 288         /*
 289          * For hardware based FIFO caused delay reporting.
 290          * Optional.
 291          */
 292         snd_pcm_sframes_t (*delay)(struct snd_pcm_substream *,
 293                 struct snd_soc_dai *);
 294
 295         /* bit field */
 296         unsigned int no_capture_mute:1;
 297 };
 298
 299 struct snd_soc_cdai_ops {
 300         /*
 301          * for compress ops
 302          */
 303         int (*startup)(struct snd_compr_stream *,
 304                         struct snd_soc_dai *);
 305         int (*shutdown)(struct snd_compr_stream *,
 306                         struct snd_soc_dai *);
 307         int (*set_params)(struct snd_compr_stream *,
 308                         struct snd_compr_params *, struct snd_soc_dai *);
 309         int (*get_params)(struct snd_compr_stream *,
 310                         struct snd_codec *, struct snd_soc_dai *);
 311         int (*set_metadata)(struct snd_compr_stream *,
 312                         struct snd_compr_metadata *, struct snd_soc_dai *);
 313         int (*get_metadata)(struct snd_compr_stream *,
 314                         struct snd_compr_metadata *, struct snd_soc_dai *);
 315         int (*trigger)(struct snd_compr_stream *, int,
 316                         struct snd_soc_dai *);
 317         int (*pointer)(struct snd_compr_stream *,
 318                         struct snd_compr_tstamp *, struct snd_soc_dai *);
 319         int (*ack)(struct snd_compr_stream *, size_t,
 320                         struct snd_soc_dai *);
 321 };
 322
 323 /*
 324  * Digital Audio Interface Driver.
 325  *
 326  * Describes the Digital Audio Interface in terms of its ALSA, DAI and AC97
 327  * operations and capabilities. Codec and platform drivers will register this
 328  * structure for every DAI they have.
 329  *
 330  * This structure covers the clocking, formating and ALSA operations for each
 331  * interface.
 332  */
 333 struct snd_soc_dai_driver {
 334         /* DAI description */
 335         const char *name;
 336         unsigned int id;
 337         unsigned int base;
 338         struct snd_soc_dobj dobj;
 339
 340         /* DAI driver callbacks */
 341         int (*probe)(struct snd_soc_dai *dai);
 342         int (*remove)(struct snd_soc_dai *dai);
 343         /* compress dai */
 344         int (*compress_new)(struct snd_soc_pcm_runtime *rtd, int num);
 345         /* Optional Callback used at pcm creation*/
 346         int (*pcm_new)(struct snd_soc_pcm_runtime *rtd,
 347                        struct snd_soc_dai *dai);
 348
 349         /* ops */
 350         const struct snd_soc_dai_ops *ops;
 351         const struct snd_soc_cdai_ops *cops;
 352
 353         /* DAI capabilities */
 354         struct snd_soc_pcm_stream capture;
 355         struct snd_soc_pcm_stream playback;
 356         unsigned int symmetric_rate:1;
 357         unsigned int symmetric_channels:1;
 358         unsigned int symmetric_sample_bits:1;
 359
 360         /* probe ordering - for components with runtime dependencies */
 361         int probe_order;
 362         int remove_order;
 363 };
 364
 365 /*
 366  * Digital Audio Interface runtime data.
 367  *
 368  * Holds runtime data for a DAI.
 369  */
 370 struct snd_soc_dai {
 371         const char *name;
 372         int id;
 373         struct device *dev;
 374
 375         /* driver ops */
 376         struct snd_soc_dai_driver *driver;
 377
 378         /* DAI runtime info */
 379         unsigned int stream_active[SNDRV_PCM_STREAM_LAST + 1]; /* usage count */
 380
 381         struct snd_soc_dapm_widget *playback_widget;
 382         struct snd_soc_dapm_widget *capture_widget;
 383
 384         /* DAI DMA data */
 385         void *playback_dma_data;
 386         void *capture_dma_data;
 387
 388         /* Symmetry data - only valid if symmetry is being enforced */
 389         unsigned int rate;
 390         unsigned int channels;
 391         unsigned int sample_bits;
 392
 393         /* parent platform/codec */
 394         struct snd_soc_component *component;
 395
 396         /* CODEC TDM slot masks and params (for fixup) */
 397         unsigned int tx_mask;
 398         unsigned int rx_mask;
 399
 400         struct list_head list;
 401
 402         /* function mark */
 403         struct snd_pcm_substream *mark_startup;
 404         struct snd_pcm_substream *mark_hw_params;
 405         struct snd_pcm_substream *mark_trigger;
 406         struct snd_compr_stream  *mark_compr_startup;
 407
 408         /* bit field */
 409         unsigned int probed:1;
 410 };
 411
 412 static inline struct snd_soc_pcm_stream *
 413 snd_soc_dai_get_pcm_stream(const struct snd_soc_dai *dai, int stream)
 414 {
 415         return (stream == SNDRV_PCM_STREAM_PLAYBACK) ?
 416                 &dai->driver->playback : &dai->driver->capture;
 417 }
 418
 419 static inline
 420 struct snd_soc_dapm_widget *snd_soc_dai_get_widget(
 421         struct snd_soc_dai *dai, int stream)
 422 {
 423         return (stream == SNDRV_PCM_STREAM_PLAYBACK) ?
 424                 dai->playback_widget : dai->capture_widget;
 425 }
 426
 427 static inline void *snd_soc_dai_get_dma_data(const struct snd_soc_dai *dai,
 428                                              const struct snd_pcm_substream *ss)
 429 {
 430         return (ss->stream == SNDRV_PCM_STREAM_PLAYBACK) ?
 431                 dai->playback_dma_data : dai->capture_dma_data;
 432 }
 433
 434 static inline void snd_soc_dai_set_dma_data(struct snd_soc_dai *dai,
 435                                             const struct snd_pcm_substream *ss,
 436                                             void *data)
 437 {
 438         if (ss->stream == SNDRV_PCM_STREAM_PLAYBACK)
 439                 dai->playback_dma_data = data;
 440         else
 441                 dai->capture_dma_data = data;
 442 }
 443
 444 static inline void snd_soc_dai_init_dma_data(struct snd_soc_dai *dai,
 445                                              void *playback, void *capture)
 446 {
 447         dai->playback_dma_data = playback;
 448         dai->capture_dma_data = capture;
 449 }
 450
 451 static inline void snd_soc_dai_set_drvdata(struct snd_soc_dai *dai,
 452                 void *data)
 453 {
 454         dev_set_drvdata(dai->dev, data);
 455 }
 456
 457 static inline void *snd_soc_dai_get_drvdata(struct snd_soc_dai *dai)
 458 {
 459         return dev_get_drvdata(dai->dev);
 460 }
 461
 462 /**
 463  * snd_soc_dai_set_sdw_stream() - Configures a DAI for SDW stream operation
 464  * @dai: DAI
 465  * @stream: STREAM
 466  * @direction: Stream direction(Playback/Capture)
 467  * SoundWire subsystem doesn't have a notion of direction and we reuse
 468  * the ASoC stream direction to configure sink/source ports.
 469  * Playback maps to source ports and Capture for sink ports.
 470  *
 471  * This should be invoked with NULL to clear the stream set previously.
 472  * Returns 0 on success, a negative error code otherwise.
 473  */
 474 static inline int snd_soc_dai_set_sdw_stream(struct snd_soc_dai *dai,
 475                                 void *stream, int direction)
 476 {
 477         if (dai->driver->ops->set_sdw_stream)
 478                 return dai->driver->ops->set_sdw_stream(dai, stream, direction);
 479         else
 480                 return -ENOTSUPP;
 481 }
 482
 483 /**
 484  * snd_soc_dai_get_sdw_stream() - Retrieves SDW stream from DAI
 485  * @dai: DAI
 486  * @direction: Stream direction(Playback/Capture)
 487  *
 488  * This routine only retrieves that was previously configured
 489  * with snd_soc_dai_get_sdw_stream()
 490  *
 491  * Returns pointer to stream or an ERR_PTR value, e.g.
 492  * ERR_PTR(-ENOTSUPP) if callback is not supported;
 493  */
 494 static inline void *snd_soc_dai_get_sdw_stream(struct snd_soc_dai *dai,
 495                                                int direction)
 496 {
 497         if (dai->driver->ops->get_sdw_stream)
 498                 return dai->driver->ops->get_sdw_stream(dai, direction);
 499         else
 500                 return ERR_PTR(-ENOTSUPP);
 501 }
 502
 503 static inline unsigned int
 504 snd_soc_dai_stream_active(struct snd_soc_dai *dai, int stream)
 505 {
 506         return dai->stream_active[stream];
 507 }
 508
 509 #endif