include/sound/soc-topology.h

   1 /* SPDX-License-Identifier: GPL-2.0
   2  *
   3  * linux/sound/soc-topology.h -- ALSA SoC Firmware Controls and DAPM
   4  *
   5  * Copyright (C) 2012 Texas Instruments Inc.
   6  * Copyright (C) 2015 Intel Corporation.
   7  *
   8  * Simple file API to load FW that includes mixers, coefficients, DAPM graphs,
   9  * algorithms, equalisers, DAIs, widgets, FE caps, BE caps, codec link caps etc.
  10  */
  11
  12 #ifndef __LINUX_SND_SOC_TPLG_H
  13 #define __LINUX_SND_SOC_TPLG_H
  14
  15 #include <sound/asoc.h>
  16 #include <linux/list.h>
  17
  18 struct firmware;
  19 struct snd_kcontrol;
  20 struct snd_soc_tplg_pcm_be;
  21 struct snd_ctl_elem_value;
  22 struct snd_ctl_elem_info;
  23 struct snd_soc_dapm_widget;
  24 struct snd_soc_component;
  25 struct snd_soc_tplg_pcm_fe;
  26 struct snd_soc_dapm_context;
  27 struct snd_soc_card;
  28 struct snd_kcontrol_new;
  29 struct snd_soc_dai_link;
  30 struct snd_soc_dai_driver;
  31 struct snd_soc_dai;
  32 struct snd_soc_dapm_route;
  33
  34 /* object scan be loaded and unloaded in groups with identfying indexes */
  35 #define SND_SOC_TPLG_INDEX_ALL  0       /* ID that matches all FW objects */
  36
  37 /* dynamic object type */
  38 enum snd_soc_dobj_type {
  39         SND_SOC_DOBJ_NONE               = 0,    /* object is not dynamic */
  40         SND_SOC_DOBJ_MIXER,
  41         SND_SOC_DOBJ_BYTES,
  42         SND_SOC_DOBJ_ENUM,
  43         SND_SOC_DOBJ_GRAPH,
  44         SND_SOC_DOBJ_WIDGET,
  45         SND_SOC_DOBJ_DAI_LINK,
  46         SND_SOC_DOBJ_PCM,
  47         SND_SOC_DOBJ_CODEC_LINK,
  48         SND_SOC_DOBJ_BACKEND_LINK,
  49 };
  50
  51 /* dynamic control object */
  52 struct snd_soc_dobj_control {
  53         struct snd_kcontrol *kcontrol;
  54         char **dtexts;
  55         unsigned long *dvalues;
  56 };
  57
  58 /* dynamic widget object */
  59 struct snd_soc_dobj_widget {
  60         unsigned int kcontrol_type;     /* kcontrol type: mixer, enum, bytes */
  61 };
  62
  63 /* generic dynamic object - all dynamic objects belong to this struct */
  64 struct snd_soc_dobj {
  65         enum snd_soc_dobj_type type;
  66         unsigned int index;     /* objects can belong in different groups */
  67         struct list_head list;
  68         struct snd_soc_tplg_ops *ops;
  69         union {
  70                 struct snd_soc_dobj_control control;
  71                 struct snd_soc_dobj_widget widget;
  72         };
  73         void *private; /* core does not touch this */
  74 };
  75
  76 /*
  77  * Kcontrol operations - used to map handlers onto firmware based controls.
  78  */
  79 struct snd_soc_tplg_kcontrol_ops {
  80         u32 id;
  81         int (*get)(struct snd_kcontrol *kcontrol,
  82                         struct snd_ctl_elem_value *ucontrol);
  83         int (*put)(struct snd_kcontrol *kcontrol,
  84                         struct snd_ctl_elem_value *ucontrol);
  85         int (*info)(struct snd_kcontrol *kcontrol,
  86                 struct snd_ctl_elem_info *uinfo);
  87 };
  88
  89 /* Bytes ext operations, for TLV byte controls */
  90 struct snd_soc_tplg_bytes_ext_ops {
  91         u32 id;
  92         int (*get)(struct snd_kcontrol *kcontrol, unsigned int __user *bytes,
  93                                                         unsigned int size);
  94         int (*put)(struct snd_kcontrol *kcontrol,
  95                         const unsigned int __user *bytes, unsigned int size);
  96 };
  97
  98 /*
  99  * DAPM widget event handlers - used to map handlers onto widgets.
 100  */
 101 struct snd_soc_tplg_widget_events {
 102         u16 type;
 103         int (*event_handler)(struct snd_soc_dapm_widget *w,
 104                         struct snd_kcontrol *k, int event);
 105 };
 106
 107 /*
 108  * Public API - Used by component drivers to load and unload dynamic objects
 109  * and their resources.
 110  */
 111 struct snd_soc_tplg_ops {
 112
 113         /* external kcontrol init - used for any driver specific init */
 114         int (*control_load)(struct snd_soc_component *, int index,
 115                 struct snd_kcontrol_new *, struct snd_soc_tplg_ctl_hdr *);
 116         int (*control_unload)(struct snd_soc_component *,
 117                 struct snd_soc_dobj *);
 118
 119         /* DAPM graph route element loading and unloading */
 120         int (*dapm_route_load)(struct snd_soc_component *, int index,
 121                 struct snd_soc_dapm_route *route);
 122         int (*dapm_route_unload)(struct snd_soc_component *,
 123                 struct snd_soc_dobj *);
 124
 125         /* external widget init - used for any driver specific init */
 126         int (*widget_load)(struct snd_soc_component *, int index,
 127                 struct snd_soc_dapm_widget *,
 128                 struct snd_soc_tplg_dapm_widget *);
 129         int (*widget_ready)(struct snd_soc_component *, int index,
 130                 struct snd_soc_dapm_widget *,
 131                 struct snd_soc_tplg_dapm_widget *);
 132         int (*widget_unload)(struct snd_soc_component *,
 133                 struct snd_soc_dobj *);
 134
 135         /* FE DAI - used for any driver specific init */
 136         int (*dai_load)(struct snd_soc_component *, int index,
 137                 struct snd_soc_dai_driver *dai_drv,
 138                 struct snd_soc_tplg_pcm *pcm, struct snd_soc_dai *dai);
 139
 140         int (*dai_unload)(struct snd_soc_component *,
 141                 struct snd_soc_dobj *);
 142
 143         /* DAI link - used for any driver specific init */
 144         int (*link_load)(struct snd_soc_component *, int index,
 145                 struct snd_soc_dai_link *link,
 146                 struct snd_soc_tplg_link_config *cfg);
 147         int (*link_unload)(struct snd_soc_component *,
 148                 struct snd_soc_dobj *);
 149
 150         /* callback to handle vendor bespoke data */
 151         int (*vendor_load)(struct snd_soc_component *, int index,
 152                 struct snd_soc_tplg_hdr *);
 153         int (*vendor_unload)(struct snd_soc_component *,
 154                 struct snd_soc_tplg_hdr *);
 155
 156         /* completion - called at completion of firmware loading */
 157         void (*complete)(struct snd_soc_component *);
 158
 159         /* manifest - optional to inform component of manifest */
 160         int (*manifest)(struct snd_soc_component *, int index,
 161                 struct snd_soc_tplg_manifest *);
 162
 163         /* vendor specific kcontrol handlers available for binding */
 164         const struct snd_soc_tplg_kcontrol_ops *io_ops;
 165         int io_ops_count;
 166
 167         /* vendor specific bytes ext handlers available for binding */
 168         const struct snd_soc_tplg_bytes_ext_ops *bytes_ext_ops;
 169         int bytes_ext_ops_count;
 170 };
 171
 172 #ifdef CONFIG_SND_SOC_TOPOLOGY
 173
 174 /* gets a pointer to data from the firmware block header */
 175 static inline const void *snd_soc_tplg_get_data(struct snd_soc_tplg_hdr *hdr)
 176 {
 177         const void *ptr = hdr;
 178
 179         return ptr + sizeof(*hdr);
 180 }
 181
 182 /* Dynamic Object loading and removal for component drivers */
 183 int snd_soc_tplg_component_load(struct snd_soc_component *comp,
 184         struct snd_soc_tplg_ops *ops, const struct firmware *fw,
 185         u32 index);
 186 int snd_soc_tplg_component_remove(struct snd_soc_component *comp, u32 index);
 187
 188 /* Widget removal - widgets also removed wth component API */
 189 void snd_soc_tplg_widget_remove(struct snd_soc_dapm_widget *w);
 190 void snd_soc_tplg_widget_remove_all(struct snd_soc_dapm_context *dapm,
 191         u32 index);
 192
 193 /* Binds event handlers to dynamic widgets */
 194 int snd_soc_tplg_widget_bind_event(struct snd_soc_dapm_widget *w,
 195         const struct snd_soc_tplg_widget_events *events, int num_events,
 196         u16 event_type);
 197
 198 #else
 199
 200 static inline int snd_soc_tplg_component_remove(struct snd_soc_component *comp,
 201                                                 u32 index)
 202 {
 203         return 0;
 204 }
 205
 206 #endif
 207
 208 #endif