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_ENUM,
  42         SND_SOC_DOBJ_BYTES,
  43         SND_SOC_DOBJ_PCM,
  44         SND_SOC_DOBJ_DAI_LINK,
  45         SND_SOC_DOBJ_CODEC_LINK,
  46         SND_SOC_DOBJ_WIDGET,
  47 };
  48
  49 /* dynamic control object */
  50 struct snd_soc_dobj_control {
  51         struct snd_kcontrol *kcontrol;
  52         char **dtexts;
  53         unsigned long *dvalues;
  54 };
  55
  56 /* dynamic widget object */
  57 struct snd_soc_dobj_widget {
  58         unsigned int kcontrol_type;     /* kcontrol type: mixer, enum, bytes */
  59 };
  60
  61 /* generic dynamic object - all dynamic objects belong to this struct */
  62 struct snd_soc_dobj {
  63         enum snd_soc_dobj_type type;
  64         unsigned int index;     /* objects can belong in different groups */
  65         struct list_head list;
  66         struct snd_soc_tplg_ops *ops;
  67         union {
  68                 struct snd_soc_dobj_control control;
  69                 struct snd_soc_dobj_widget widget;
  70         };
  71         void *private; /* core does not touch this */
  72 };
  73
  74 /*
  75  * Kcontrol operations - used to map handlers onto firmware based controls.
  76  */
  77 struct snd_soc_tplg_kcontrol_ops {
  78         u32 id;
  79         int (*get)(struct snd_kcontrol *kcontrol,
  80                         struct snd_ctl_elem_value *ucontrol);
  81         int (*put)(struct snd_kcontrol *kcontrol,
  82                         struct snd_ctl_elem_value *ucontrol);
  83         int (*info)(struct snd_kcontrol *kcontrol,
  84                 struct snd_ctl_elem_info *uinfo);
  85 };
  86
  87 /* Bytes ext operations, for TLV byte controls */
  88 struct snd_soc_tplg_bytes_ext_ops {
  89         u32 id;
  90         int (*get)(struct snd_kcontrol *kcontrol, unsigned int __user *bytes,
  91                                                         unsigned int size);
  92         int (*put)(struct snd_kcontrol *kcontrol,
  93                         const unsigned int __user *bytes, unsigned int size);
  94 };
  95
  96 /*
  97  * DAPM widget event handlers - used to map handlers onto widgets.
  98  */
  99 struct snd_soc_tplg_widget_events {
 100         u16 type;
 101         int (*event_handler)(struct snd_soc_dapm_widget *w,
 102                         struct snd_kcontrol *k, int event);
 103 };
 104
 105 /*
 106  * Public API - Used by component drivers to load and unload dynamic objects
 107  * and their resources.
 108  */
 109 struct snd_soc_tplg_ops {
 110
 111         /* external kcontrol init - used for any driver specific init */
 112         int (*control_load)(struct snd_soc_component *, int index,
 113                 struct snd_kcontrol_new *, struct snd_soc_tplg_ctl_hdr *);
 114         int (*control_unload)(struct snd_soc_component *,
 115                 struct snd_soc_dobj *);
 116
 117         /* DAPM graph route element loading and unloading */
 118         int (*dapm_route_load)(struct snd_soc_component *, int index,
 119                 struct snd_soc_dapm_route *route);
 120         int (*dapm_route_unload)(struct snd_soc_component *,
 121                 struct snd_soc_dobj *);
 122
 123         /* external widget init - used for any driver specific init */
 124         int (*widget_load)(struct snd_soc_component *, int index,
 125                 struct snd_soc_dapm_widget *,
 126                 struct snd_soc_tplg_dapm_widget *);
 127         int (*widget_ready)(struct snd_soc_component *, int index,
 128                 struct snd_soc_dapm_widget *,
 129                 struct snd_soc_tplg_dapm_widget *);
 130         int (*widget_unload)(struct snd_soc_component *,
 131                 struct snd_soc_dobj *);
 132
 133         /* FE DAI - used for any driver specific init */
 134         int (*dai_load)(struct snd_soc_component *, int index,
 135                 struct snd_soc_dai_driver *dai_drv,
 136                 struct snd_soc_tplg_pcm *pcm, struct snd_soc_dai *dai);
 137
 138         int (*dai_unload)(struct snd_soc_component *,
 139                 struct snd_soc_dobj *);
 140
 141         /* DAI link - used for any driver specific init */
 142         int (*link_load)(struct snd_soc_component *, int index,
 143                 struct snd_soc_dai_link *link,
 144                 struct snd_soc_tplg_link_config *cfg);
 145         int (*link_unload)(struct snd_soc_component *,
 146                 struct snd_soc_dobj *);
 147
 148         /* callback to handle vendor bespoke data */
 149         int (*vendor_load)(struct snd_soc_component *, int index,
 150                 struct snd_soc_tplg_hdr *);
 151         int (*vendor_unload)(struct snd_soc_component *,
 152                 struct snd_soc_tplg_hdr *);
 153
 154         /* completion - called at completion of firmware loading */
 155         void (*complete)(struct snd_soc_component *);
 156
 157         /* manifest - optional to inform component of manifest */
 158         int (*manifest)(struct snd_soc_component *, int index,
 159                 struct snd_soc_tplg_manifest *);
 160
 161         /* vendor specific kcontrol handlers available for binding */
 162         const struct snd_soc_tplg_kcontrol_ops *io_ops;
 163         int io_ops_count;
 164
 165         /* vendor specific bytes ext handlers available for binding */
 166         const struct snd_soc_tplg_bytes_ext_ops *bytes_ext_ops;
 167         int bytes_ext_ops_count;
 168 };
 169
 170 #ifdef CONFIG_SND_SOC_TOPOLOGY
 171
 172 /* gets a pointer to data from the firmware block header */
 173 static inline const void *snd_soc_tplg_get_data(struct snd_soc_tplg_hdr *hdr)
 174 {
 175         const void *ptr = hdr;
 176
 177         return ptr + sizeof(*hdr);
 178 }
 179
 180 /* Dynamic Object loading and removal for component drivers */
 181 int snd_soc_tplg_component_load(struct snd_soc_component *comp,
 182         struct snd_soc_tplg_ops *ops, const struct firmware *fw,
 183         u32 index);
 184 int snd_soc_tplg_component_remove(struct snd_soc_component *comp, u32 index);
 185
 186 /* Widget removal - widgets also removed wth component API */
 187 void snd_soc_tplg_widget_remove(struct snd_soc_dapm_widget *w);
 188 void snd_soc_tplg_widget_remove_all(struct snd_soc_dapm_context *dapm,
 189         u32 index);
 190
 191 /* Binds event handlers to dynamic widgets */
 192 int snd_soc_tplg_widget_bind_event(struct snd_soc_dapm_widget *w,
 193         const struct snd_soc_tplg_widget_events *events, int num_events,
 194         u16 event_type);
 195
 196 #else
 197
 198 static inline int snd_soc_tplg_component_remove(struct snd_soc_component *comp,
 199                                                 u32 index)
 200 {
 201         return 0;
 202 }
 203
 204 #endif
 205
 206 #endif