3 * This library is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU Lesser General Public License as
5 * published by the Free Software Foundation; either version 2.1 of
6 * the License, or (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 * Copyright (C) 2015 Intel Corporation
21 #ifndef __ALSA_TOPOLOGY_H
22 #define __ALSA_TOPOLOGY_H
31 * \defgroup topology Topology Interface
35 /*! \page topology ALSA Topology Interface
37 * The topology interface allows developers to define DSP topologies in a text
38 * file format and to convert the text topology to a binary topology
39 * representation that can be understood by the kernel. The topology core
40 * currently recognises the following object types :-
42 * * Controls (mixer, enumerated and byte) including TLV data.
43 * * PCMs (FE and BE configurations and capabilities)
45 * * DAPM graph elements.
46 * * Private data for each object type.
47 * * Manifest (containing count of each object type)
49 * <h3>Topology File Format</h3>
51 * The topology text format uses the standard ALSA configuration file format to
52 * describe each topology object type. This allows topology objects to include
53 * other topology objects as part of their definition. i.e. a TLV data object
54 * can be shared amongst many control objects that use the same TLV data.
58 * Topology audio controls can belong to three different types :-
60 * * Enumerated control
63 * Each control type can contain TLV data, private data, operations and also
64 * belong to widget objects.<br>
66 * <h5>Control Operations</h5>
67 * Driver Kcontrol callback info(), get() and put() operations are mapped with
68 * the CTL ops section in topology configuration files. The ctl ops section can
69 * assign operations using the standard names (listed below) for the standard
70 * kcontrol types or use ID numbers (>256) to map to bespoke driver controls.<br>
82 * This mapping shows info() using the standard "volsw" info callback whilst
83 * the get() and put() are mapped to bespoke driver callbacks. <br>
85 * The Standard operations names for control get(), put() and info calls
96 * <h5>Control TLV Data</h5>
97 * Controls can also use TLV data to represent dB information. This can be done
98 * by defining a TLV section and using the TLV section within the control.
99 * The TLV data for DBScale types are defined as follows :-
109 * Where the meanings and values for min, step and mute are exactly the same
110 * as defined in driver code.
112 * <h5>Control Channel Mapping</h5>
113 * Controls can also specify which channels they are mapped with. This is useful
114 * for userspace as it allows applications to determine the correct control
115 * channel for Left and Right etc. Channel maps are defined as follows :-
124 * The channel map reg is the register offset for the control, shift is the
125 * bit shift within the register for the channel and the section name is the
126 * channel name and can be one of the following :-
129 * * mono # mono stream
134 * * fc # front center
139 * * flc # front left center
140 * * frc # front right center
141 * * rlc # rear left center
142 * * rrc # rear right center
143 * * flw # front left wide
144 * * frw # front right wide
145 * * flh # front left high
146 * * fch # front center high
147 * * frh # front right high
149 * * tfl # top front left
150 * * tfr # top front right
151 * * tfc # top front center
152 * * trl # top rear left
153 * * trr # top rear right
154 * * trc # top rear center
155 * * tflc # top front left center
156 * * tfrc # top front right center
157 * * tsl # top side left
158 * * tsr # top side right
161 * * bc # bottom center
162 * * blc # bottom left center
163 * * brc # bottom right center
166 * <h5>Control Private Data</h5>
167 * Controls can also have private data. This can be done by defining a private
168 * data section and including the section within the control. The private data
169 * section is defined as follows :-
172 * SectionData."pdata for EQU1" {
173 * file "/path/to/file"
174 * bytes "0x12,0x34,0x56,0x78"
175 * shorts "0x1122,0x3344,0x5566,0x7788"
176 * words "0xaabbccdd,0x11223344,0x66aa77bb,0xefef1234"
179 * The file, bytes, shorts and words keywords are all mutually exclusive as
180 * the private data should only be taken from one source. The private data can
181 * either be read from a separate file or defined in the topology file using
182 * the bytes, shorts or words keywords.
184 * <h5>Mixer Controls</h5>
185 * A mixer control is defined as a new section that can include channel mapping,
186 * TLV data, callback operations and private data. The mixer section also
187 * includes a few other config options that are shown here :-
190 * SectionControlMixer."mixer name" {
191 * comment "optional comments"
193 * index "1" # Index number
195 * channel."name" { # Channel maps
199 * ops."ctl" { # Ops callback functions
203 * max "32" # Max control value
204 * invert "0" # Whether control values are inverted
206 * tlv "tld_data" # optional TLV data
208 * data "pdata for mixer1" # optional private data
212 * The section name is used to define the mixer name. The index number can be
213 * used to identify topology objects groups. This allows driver operations on
214 * objects with index number N and can be used to add/remove pipelines of
215 * objects whilst other objects are unaffected.
217 * <h5>Byte Controls</h5>
218 * A byte control is defined as a new section that can include channel mapping,
219 * TLV data, callback operations and private data. The bytes section also
220 * includes a few other config options that are shown here :-
223 * SectionControlBytes."name" {
224 * comment "optional comments"
226 * index "1" # Index number
228 * channel."name" { # Channel maps
232 * ops."ctl" { # Ops callback functions
236 * base "0" # Register base
237 * num_regs "16" # Number of registers
239 * max "255" # Maximum value
241 * tlv "tld_data" # optional TLV data
243 * data "pdata for mixer1" # optional private data
247 * <h5>Enumerated Controls</h5>
248 * A enumerated control is defined as a new section (like mixer and byte) that
249 * can include channel mapping, callback operations, private data and
250 * text strings to represent the enumerated control options.<br>
252 * The text strings for the enumerated controls are defined in a separate
253 * section as follows :-
256 * SectionText."name" {
266 * All the enumerated text values are listed in the values list.<br>
267 * The enumerated control is similar to the other controls and defined as
271 * SectionControlMixer."name" {
272 * comment "optional comments"
274 * index "1" # Index number
276 * texts "EQU1" # Enumerated text items
278 * channel."name" { # Channel maps
282 * ops."ctl" { # Ops callback functions
286 * data "pdata for mixer1" # optional private data
290 * <h4>DAPM Graph</h4>
291 * DAPM graphs can easily be defined using the topology file. The format is
292 * very similar to the DAPM graph kernel format. :-
295 * SectionGraph."dsp" {
296 * index "1" # Index number
299 * "sink1, control, source1"
305 * The lines in the graph are defined as a variable size list of sinks,
306 * controls and sources. The control name is optional as some graph lines have
307 * no associated controls. The section name can be used to differentiate the
308 * graph with other graphs, it's not used by the kernel atm.
310 * <h4>DAPM Widgets</h4>
311 * DAPM widgets are similar to controls in that they can include many other
312 * objects. Widgets can contain private data, mixer controls and enum controls.
314 * The following widget types are supported and match the driver types :-
333 * Widgets are defined as follows :-
336 * SectionWidget."name" {
338 * index "1" # Index number
340 * type "aif_in" # Widget type - detailed above
342 * no_pm "true" # No PM control bit.
343 * reg "20" # PM bit register offset
344 * shift "0" # PM bit register shift
345 * invert "1 # PM bit is inverted
346 * subseq "8" # subsequence number
348 * event_type "1" # DAPM widget event type
349 * event_flags "1" # DAPM widget event flags
351 * mixer "name" # Optional Mixer Control
352 * enum "name" # Optional Enum Control
354 * data "name" # optional private data
358 * The section name is the widget name. The mixer and enum fields are mutually
359 * exclusive and used to include controls into the widget. The index and data
360 * fields are the same for widgets as they are for controls whilst the other
361 * fields map on very closely to the driver widget fields.
363 * <h4>PCM Capabilities</h4>
364 * Topology can also define the capabilities of FE and BE PCMs. Capabilities
365 * can be defined with the following section :-
368 * SectionPCMCapabilities."name" {
370 * formats "S24_LE,S16_LE" # Supported formats
371 * rate_min "48000" # Max supported sample rate
372 * rate_max "48000" # Min supported sample rate
373 * channels_min "2" # Min number of channels
374 * channels_max "2" # max number of channels
377 * The supported formats use the same naming convention as the driver macros.
378 * The PCM capabilities name can be referred to and included by BE, PCM and
379 * Codec <-> codec topology sections.
381 * <h4>PCM Configurations</h4>
382 * PCM runtime configurations can be defined for playback and capture stream
383 * directions with the following section :-
386 * SectionPCMConfig."name" {
388 * config."playback" { # playback config
389 * format "S16_LE" # playback format
390 * rate "48000" # playback sample rate
391 * channels "2" # playback channels
392 * tdm_slot "0xf" # playback TDM slot
395 * config."capture" { # capture config
396 * format "S16_LE" # capture format
397 * rate "48000" # capture sample rate
398 * channels "2" # capture channels
399 * tdm_slot "0xf" # capture TDM slot
404 * The supported formats use the same naming convention as the driver macros.
405 * The PCM configuration name can be referred to and included by BE, PCM and
406 * Codec <-> codec topology sections.
408 * <h4>PCM Configurations</h4>
409 * PCM, BE and Codec to Codec link sections define the supported capabilities
410 * and configurations for supported playback and capture streams. The
411 * definitions and content for PCMs, BE and Codec links are the same with the
412 * exception of the section type :-
415 * SectionPCM."name" {
426 * The section types above should be used for PCMs, Back Ends and Codec to Codec
427 * links respectively.<br>
429 * The data for each section is defined as follows :-
432 * SectionPCM."name" {
434 * index "1" # Index number
436 * id "0" # used for binding to the PCM
439 * capabilities "capabilities1" # capabilities for playback
441 * configs [ # supported configs for playback
448 * capabilities "capabilities2" # capabilities for capture
450 * configs [ # supported configs for capture
461 /** Maximum number of channels supported in one control */
462 #define SND_TPLG_MAX_CHAN 8
464 /** Topology context */
465 typedef struct snd_tplg snd_tplg_t;
467 /** Topology object types */
469 SND_TPLG_TYPE_TLV = 0, /*!< TLV Data */
470 SND_TPLG_TYPE_MIXER, /*!< Mixer control*/
471 SND_TPLG_TYPE_ENUM, /*!< Enumerated control */
472 SND_TPLG_TYPE_TEXT, /*!< Text data */
473 SND_TPLG_TYPE_DATA, /*!< Private data */
474 SND_TPLG_TYPE_BYTES, /*!< Byte control */
475 SND_TPLG_TYPE_STREAM_CONFIG, /*!< PCM Stream configuration */
476 SND_TPLG_TYPE_STREAM_CAPS, /*!< PCM Stream capabilities */
477 SND_TPLG_TYPE_PCM, /*!< PCM stream device */
478 SND_TPLG_TYPE_DAPM_WIDGET, /*!< DAPM widget */
479 SND_TPLG_TYPE_DAPM_GRAPH, /*!< DAPM graph elements */
480 SND_TPLG_TYPE_BE, /*!< BE DAI link */
481 SND_TPLG_TYPE_CC, /*!< Hostless codec <-> codec link */
482 SND_TPLG_TYPE_MANIFEST, /*!< Topology manifest */
486 * \brief Create a new topology parser instance.
487 * \return New topology parser instance
489 snd_tplg_t *snd_tplg_new(void);
492 * \brief Free a topology parser instance.
493 * \param tplg Topology parser instance
495 void snd_tplg_free(snd_tplg_t *tplg);
498 * \brief Parse and build topology text file into binary file.
499 * \param tplg Topology instance.
500 * \param infile Topology text input file to be parsed
501 * \param outfile Binary topology output file.
502 * \return Zero on success, otherwise a negative error code
504 int snd_tplg_build_file(snd_tplg_t *tplg, const char *infile,
505 const char *outfile);
508 * \brief Enable verbose reporting of binary file output
509 * \param tplg Topology Instance
510 * \param verbose Enable verbose output level if non zero
512 void snd_tplg_verbose(snd_tplg_t *tplg, int verbose);
514 /** \struct snd_tplg_tlv_template
515 * \brief Template type for all TLV objects.
517 struct snd_tplg_tlv_template {
518 int type; /*!< TLV type SNDRV_CTL_TLVT_ */
521 /** \struct snd_tplg_tlv_dbscale_template
522 * \brief Template type for TLV Scale objects.
524 struct snd_tplg_tlv_dbscale_template {
525 struct snd_tplg_tlv_template hdr; /*!< TLV type header */
526 int min; /*!< dB minimum value in 0.1dB */
527 int step; /*!< dB step size in 0.1dB */
528 int mute; /*!< is min dB value mute ? */
531 /** \struct snd_tplg_channel_template
532 * \brief Template type for single channel mapping.
534 struct snd_tplg_channel_elem {
535 int size; /*!< size in bytes of this structure */
536 int reg; /*!< channel control register */
537 int shift; /*!< channel shift for control bits */
538 int id; /*!< ID maps to Left, Right, LFE etc */
541 /** \struct snd_tplg_channel_map_template
542 * \brief Template type for channel mapping.
544 struct snd_tplg_channel_map_template {
545 int num_channels; /*!< number of channel mappings */
546 struct snd_tplg_channel_elem channel[SND_TPLG_MAX_CHAN]; /*!< mapping */
549 /** \struct snd_tplg_pdata_template
550 * \brief Template type for private data objects.
552 struct snd_tplg_pdata_template {
553 unsigned int length; /*!< data length */
554 const void *data; /*!< data */
557 /** \struct snd_tplg_io_ops_template
558 * \brief Template type for object operations mapping.
560 struct snd_tplg_io_ops_template {
561 int get; /*!< get callback ID */
562 int put; /*!< put callback ID */
563 int info; /*!< info callback ID */
566 /** \struct snd_tplg_ctl_template
567 * \brief Template type for control objects.
569 struct snd_tplg_ctl_template {
570 int type; /*!< Control type */
571 const char *name; /*!< Control name */
572 int access; /*!< Control access */
573 struct snd_tplg_io_ops_template ops; /*!< operations */
574 struct snd_tplg_tlv_template *tlv; /*!< non NULL means we have TLV data */
577 /** \struct snd_tplg_mixer_template
578 * \brief Template type for mixer control objects.
580 struct snd_tplg_mixer_template {
581 struct snd_tplg_ctl_template hdr; /*!< control type header */
582 struct snd_tplg_channel_map_template *map; /*!< channel map */
583 int min; /*!< min value for mixer */
584 int max; /*!< max value for mixer */
585 int platform_max; /*!< max value for platform control */
586 int invert; /*!< whether controls bits are inverted */
587 struct snd_soc_tplg_private *priv; /*!< control private data */
590 /** \struct snd_tplg_enum_template
591 * \brief Template type for enumerated control objects.
593 struct snd_tplg_enum_template {
594 struct snd_tplg_ctl_template hdr; /*!< control type header */
595 struct snd_tplg_channel_map_template *map; /*!< channel map */
596 int items; /*!< number of enumerated items in control */
597 int mask; /*!< register mask size */
598 const char **texts; /*!< control text items */
599 const int **values; /*!< control value items */
600 struct snd_soc_tplg_private *priv; /*!< control private data */
603 /** \struct snd_tplg_bytes_template
604 * \brief Template type for TLV Scale objects.
606 struct snd_tplg_bytes_template {
607 struct snd_tplg_ctl_template hdr; /*!< control type header */
608 int max; /*!< max byte control value */
609 int mask; /*!< byte control mask */
610 int base; /*!< base register */
611 int num_regs; /*!< number of registers */
612 struct snd_tplg_io_ops_template ext_ops; /*!< ops mapping */
613 struct snd_soc_tplg_private *priv; /*!< control private data */
616 /** \struct snd_tplg_graph_elem
617 * \brief Template type for single DAPM graph element.
619 struct snd_tplg_graph_elem {
620 const char *src; /*!< source widget name */
621 const char *ctl; /*!< control name or NULL if no control */
622 const char *sink; /*!< sink widget name */
625 /** \struct snd_tplg_graph_template
626 * \brief Template type for array of DAPM graph elements.
628 struct snd_tplg_graph_template {
629 int count; /*!< Number of graph elements */
630 struct snd_tplg_graph_elem elem[0]; /*!< graph elements */
633 /** \struct snd_tplg_widget_template
634 * \brief Template type for DAPM widget objects.
636 struct snd_tplg_widget_template {
637 int id; /*!< SND_SOC_DAPM_CTL */
638 const char *name; /*!< widget name */
639 const char *sname; /*!< stream name (certain widgets only) */
640 int reg; /*!< negative reg = no direct dapm */
641 int shift; /*!< bits to shift */
642 int mask; /*!< non-shifted mask */
643 int subseq; /*!< sort within widget type */
644 unsigned int invert; /*!< invert the power bit */
645 unsigned int ignore_suspend; /*!< kept enabled over suspend */
646 unsigned short event_flags; /*!< PM event sequence flags */
647 unsigned short event_type; /*!< PM event sequence type */
648 struct snd_soc_tplg_private *priv; /*!< widget private data */
649 int num_ctls; /*!< Number of controls used by widget */
650 struct snd_tplg_ctl_template *ctl[0]; /*!< array of widget controls */
653 /** \struct snd_tplg_stream_template
654 * \brief Stream configurations.
656 struct snd_tplg_stream_template {
657 const char *name; /*!< name of the stream config */
658 int format; /*!< SNDRV_PCM_FMTBIT_* */
659 int rate; /*!< SNDRV_PCM_RATE_* */
660 int period_bytes; /*!< size of period in bytes */
661 int buffer_bytes; /*!< size of buffer in bytes. */
662 int channels; /*!< number of channels */
665 /** \struct snd_tplg_stream_caps_template
666 * \brief Stream Capabilities.
668 struct snd_tplg_stream_caps_template {
669 const char *name; /*!< name of the stream caps */
670 uint64_t formats; /*!< supported formats SNDRV_PCM_FMTBIT_* */
671 unsigned int rates; /*!< supported rates SNDRV_PCM_RATE_* */
672 unsigned int rate_min; /*!< min rate */
673 unsigned int rate_max; /*!< max rate */
674 unsigned int channels_min; /*!< min channels */
675 unsigned int channels_max; /*!< max channels */
676 unsigned int periods_min; /*!< min number of periods */
677 unsigned int periods_max; /*!< max number of periods */
678 unsigned int period_size_min; /*!< min period size bytes */
679 unsigned int period_size_max; /*!< max period size bytes */
680 unsigned int buffer_size_min; /*!< min buffer size bytes */
681 unsigned int buffer_size_max; /*!< max buffer size bytes */
684 /** \struct snd_tplg_pcm_template
685 * \brief Template type for PCM (FE DAI & DAI links).
687 struct snd_tplg_pcm_template {
688 const char *pcm_name; /*!< PCM stream name */
689 const char *dai_name; /*!< DAI name */
690 unsigned int pcm_id; /*!< unique ID - used to match */
691 unsigned int dai_id; /*!< unique ID - used to match */
692 unsigned int playback; /*!< supports playback mode */
693 unsigned int capture; /*!< supports capture mode */
694 unsigned int compress; /*!< 1 = compressed; 0 = PCM */
695 struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */
696 int num_streams; /*!< number of supported configs */
697 struct snd_tplg_stream_template stream[0]; /*!< supported configs */
700 /** \struct snd_tplg_link_template
701 * \brief Template type for BE and CC DAI Links.
703 struct snd_tplg_link_template {
704 const char *name; /*!< link name */
705 int id; /*!< unique ID - used to match with existing BE and CC links */
706 int num_streams; /*!< number of configs */
707 struct snd_tplg_stream_template stream[0]; /*!< supported configs */
710 /** \struct snd_tplg_obj_template
711 * \brief Generic Template Object
713 typedef struct snd_tplg_obj_template {
714 enum snd_tplg_type type; /*!< template object type */
715 int index; /*!< group index for object */
716 int version; /*!< optional vendor specific version details */
717 int vendor_type; /*!< optional vendor specific type info */
719 struct snd_tplg_widget_template *widget; /*!< DAPM widget */
720 struct snd_tplg_mixer_template *mixer; /*!< Mixer control */
721 struct snd_tplg_bytes_template *bytes_ctl; /*!< Bytes control */
722 struct snd_tplg_enum_template *enum_ctl; /*!< Enum control */
723 struct snd_tplg_graph_template *graph; /*!< Graph elements */
724 struct snd_tplg_pcm_template *pcm; /*!< PCM elements */
725 struct snd_tplg_link_template *link; /*!< BE and CC Links */
727 } snd_tplg_obj_template_t;
730 * \brief Register topology template object.
731 * \param tplg Topology instance.
732 * \param t Template object.
733 * \return Zero on success, otherwise a negative error code
735 int snd_tplg_add_object(snd_tplg_t *tplg, snd_tplg_obj_template_t *t);
738 * \brief Build all registered topology data into binary file.
739 * \param tplg Topology instance.
740 * \param outfile Binary topology output file.
741 * \return Zero on success, otherwise a negative error code
743 int snd_tplg_build(snd_tplg_t *tplg, const char *outfile);
746 * \brief Attach private data to topology manifest.
747 * \param tplg Topology instance.
748 * \param data Private data.
749 * \param len Length of data in bytes.
750 * \return Zero on success, otherwise a negative error code
752 int snd_tplg_set_manifest_data(snd_tplg_t *tplg, const void *data, int len);
755 * \brief Set an optional vendor specific version number.
756 * \param tplg Topology instance.
757 * \param version Vendor specific version number.
758 * \return Zero on success, otherwise a negative error code
760 int snd_tplg_set_version(snd_tplg_t *tplg, unsigned int version);
768 #endif /* __ALSA_TOPOLOGY_H */