ALSA project - the C library reference: Topology Interface

# Topology Interface

## Data Structures
struct | snd_tplg_tlv_template
| Template type for all TLV objects. More...
struct | snd_tplg_tlv_dbscale_template
| Template type for TLV Scale objects. More...
struct | snd_tplg_channel_elem
struct | snd_tplg_channel_map_template
| Template type for channel mapping. More...
struct | snd_tplg_pdata_template
| Template type for private data objects. More...
struct | snd_tplg_io_ops_template
| Template type for object operations mapping. More...
struct | snd_tplg_ctl_template
| Template type for control objects. More...
struct | snd_tplg_mixer_template
| Template type for mixer control objects. More...
struct | snd_tplg_enum_template
| Template type for enumerated control objects. More...
struct | snd_tplg_bytes_template
| Template type for TLV Scale objects. More...
struct | snd_tplg_graph_elem
| Template type for single DAPM graph element. More...
struct | snd_tplg_graph_template
| Template type for array of DAPM graph elements. More...
struct | snd_tplg_widget_template
| Template type for DAPM widget objects. More...
struct | snd_tplg_stream_template
| Stream configurations. More...
struct | snd_tplg_stream_caps_template
| Stream Capabilities. More...
struct | snd_tplg_pcm_template
| Template type for PCM (FE DAI & DAI links). More...
struct | snd_tplg_link_template
| Template type for BE and CC DAI Links. More...
struct | snd_tplg_obj_template_t
struct | snd_tplg_channel_template
| Template type for single channel mapping. More...
struct | snd_tplg_obj_template
| Generic Template Object. More...
## Defines
#define | SND_TPLG_MAX_CHAN 8
## Typedefs
typedef struct snd_tplg | snd_tplg_t
## Enumerations
enum | snd_tplg_type { SND_TPLG_TYPE_TLV = 0, SND_TPLG_TYPE_MIXER, SND_TPLG_TYPE_ENUM, SND_TPLG_TYPE_TEXT, SND_TPLG_TYPE_DATA, SND_TPLG_TYPE_BYTES, SND_TPLG_TYPE_STREAM_CONFIG, SND_TPLG_TYPE_STREAM_CAPS, SND_TPLG_TYPE_PCM, SND_TPLG_TYPE_DAPM_WIDGET, SND_TPLG_TYPE_DAPM_GRAPH, SND_TPLG_TYPE_BE, SND_TPLG_TYPE_CC, SND_TPLG_TYPE_MANIFEST }
## Functions
snd_tplg_t * | snd_tplg_new (void)
| Create a new topology parser instance.
void | snd_tplg_free (snd_tplg_t *tplg)
| Free a topology parser instance.
int | snd_tplg_build_file (snd_tplg_t *tplg, const char *infile, const char *outfile)
| Parse and build topology text file into binary file.
void | snd_tplg_verbose (snd_tplg_t *tplg, int verbose)
| Enable verbose reporting of binary file output.
int | snd_tplg_add_object (snd_tplg_t *tplg, snd_tplg_obj_template_t *t)
| Register topology template object.
int | snd_tplg_build (snd_tplg_t *tplg, const char *outfile)
| Build all registered topology data into binary file.
int | snd_tplg_set_manifest_data (snd_tplg_t *tplg, const void *data, int len)
| Attach private data to topology manifest.
int | snd_tplg_set_version (snd_tplg_t *tplg, unsigned int version)
| Set an optional vendor specific version number.

### ALSA Topology Interface

The topology interface allows developers to define DSP topologies in a text file format and to convert the text topology to a binary topology representation that can be understood by the kernel. The topology core currently recognises the following object types :-

* Controls (mixer, enumerated and byte) including TLV data. * PCMs (FE and BE configurations and capabilities) * DAPM widgets * DAPM graph elements. * Private data for each object type. * Manifest (containing count of each object type)

### Topology File Format

The topology text format uses the standard ALSA configuration file format to describe each topology object type. This allows topology objects to include other topology objects as part of their definition. i.e. a TLV data object can be shared amongst many control objects that use the same TLV data.

#### Controls

Topology audio controls can belong to three different types :- * Mixer control * Enumerated control * Byte control

Each control type can contain TLV data, private data, operations and also belong to widget objects.

##### Control Operations

Driver Kcontrol callback info(), get() and put() operations are mapped with the CTL ops section in topology configuration files. The ctl ops section can assign operations using the standard names (listed below) for the standard kcontrol types or use ID numbers (>256) to map to bespoke driver controls.

    	ops."ctl" {
    		info "volsw"
    		get "257"
    		put "257"
    	}

This mapping shows info() using the standard "volsw" info callback whilst the get() and put() are mapped to bespoke driver callbacks.

The Standard operations names for control get(), put() and info calls are :- * volsw * volsw_sx * volsw_xr_sx * enum * bytes * enum_value * range * strobe

##### Control TLV Data

Controls can also use TLV data to represent dB information. This can be done by defining a TLV section and using the TLV section within the control. The TLV data for DBScale types are defined as follows :-

    	scale {
    		min "-9000"
    		step "300"
    		mute "1"
    	}

Where the meanings and values for min, step and mute are exactly the same as defined in driver code.

##### Control Channel Mapping

Controls can also specify which channels they are mapped with. This is useful for userspace as it allows applications to determine the correct control channel for Left and Right etc. Channel maps are defined as follows :-

    	channel."name" {
    		reg "0"
    		shift "0"
    	}

The channel map reg is the register offset for the control, shift is the bit shift within the register for the channel and the section name is the channel name and can be one of the following :-

      * mono		# mono stream
      * fl 		# front left
      * fr		# front right
      * rl		# rear left
      * rr		# rear right
      * fc		# front center
      * lfe		# LFE
      * sl		# side left
      * sr		# side right
      * rc		# rear center
      * flc		# front left center
      * frc		# front right center
      * rlc		# rear left center
      * rrc		# rear right center
      * flw		# front left wide
      * frw		# front right wide
      * flh		# front left high
      * fch		# front center high
      * frh		# front right high
      * tc		# top center
      * tfl		# top front left
      * tfr		# top front right
      * tfc		# top front center
      * trl		# top rear left
      * trr		# top rear right
      * trc		# top rear center
      * tflc		# top front left center
      * tfrc		# top front right center
      * tsl		# top side left
      * tsr		# top side right
      * llfe		# left LFE
      * rlfe		# right LFE
      * bc		# bottom center
      * blc		# bottom left center
      * brc		# bottom right center

##### Control Private Data

Controls can also have private data. This can be done by defining a private data section and including the section within the control. The private data section is defined as follows :-

     SectionData."pdata for EQU1" {
    	file "/path/to/file"
    	bytes "0x12,0x34,0x56,0x78"
    	shorts "0x1122,0x3344,0x5566,0x7788"
    	words "0xaabbccdd,0x11223344,0x66aa77bb,0xefef1234"
     };

The file, bytes, shorts and words keywords are all mutually exclusive as the private data should only be taken from one source. The private data can either be read from a separate file or defined in the topology file using the bytes, shorts or words keywords.

##### Mixer Controls

A mixer control is defined as a new section that can include channel mapping, TLV data, callback operations and private data. The mixer section also includes a few other config options that are shown here :-

     SectionControlMixer."mixer name" {
    	comment "optional comments"

    	index "1"			# Index number

    	channel."name" {		# Channel maps
    	   ....
    	}

    	ops."ctl" {			# Ops callback functions
    	   ....
    	}

    	max "32"			# Max control value
    	invert "0"			# Whether control values are inverted

    	tlv "tld_data"			# optional TLV data

    	data "pdata for mixer1"		# optional private data
     }

The section name is used to define the mixer name. The index number can be used to identify topology objects groups. This allows driver operations on objects with index number N and can be used to add/remove pipelines of objects whilst other objects are unaffected.

##### Byte Controls

A byte control is defined as a new section that can include channel mapping, TLV data, callback operations and private data. The bytes section also includes a few other config options that are shown here :-

     SectionControlBytes."name" {
    	comment "optional comments"

    	index "1"			# Index number

    	channel."name" {		# Channel maps
    	   ....
    	}

    	ops."ctl" {			# Ops callback functions
    	   ....
    	}

    	base "0"			# Register base
    	num_regs "16"			# Number of registers
    	mask "0xff"			# Mask
    	max "255"			# Maximum value

    	tlv "tld_data"			# optional TLV data

    	data "pdata for mixer1"		# optional private data
     }

##### Enumerated Controls

A enumerated control is defined as a new section (like mixer and byte) that can include channel mapping, callback operations, private data and text strings to represent the enumerated control options.

The text strings for the enumerated controls are defined in a separate section as follows :-

     SectionText."name" {

    		Values [
    			"value1"
    			"value2"
    			"value3"
    		]
     }

All the enumerated text values are listed in the values list.
The enumerated control is similar to the other controls and defined as follows :-

     SectionControlMixer."name" {
    	comment "optional comments"

    	index "1"			# Index number

    	texts "EQU1"			# Enumerated text items

    	channel."name" {		# Channel maps
    	   ....
    	}

    	ops."ctl" {			# Ops callback functions
    	   ....
    	}

    	data "pdata for mixer1"		# optional private data
     }

#### DAPM Graph

DAPM graphs can easily be defined using the topology file. The format is very similar to the DAPM graph kernel format. :-

     SectionGraph."dsp" {
    	index "1"			# Index number

    	lines [
    		"sink1, control, source1"
    		"sink2, , source2"
    	]
     }

The lines in the graph are defined as a variable size list of sinks, controls and sources. The control name is optional as some graph lines have no associated controls. The section name can be used to differentiate the graph with other graphs, it's not used by the kernel atm.

#### DAPM Widgets

DAPM widgets are similar to controls in that they can include many other objects. Widgets can contain private data, mixer controls and enum controls.

The following widget types are supported and match the driver types :-

* input * output * mux * mixer * pga * out_drv * adc * dac * switch * pre * post * aif_in * aif_out * dai_in * dai_out * dai_link

Widgets are defined as follows :-

     SectionWidget."name" {

    	index "1"			# Index number

    	type "aif_in"			# Widget type - detailed above

    	no_pm "true"			# No PM control bit.
    	reg "20"			# PM bit register offset
    	shift "0"			# PM bit register shift
    	invert "1			# PM bit is inverted
    	subseq "8			# subsequence number

    	event_type "1"			# DAPM widget event type
    	event_flags "1"			# DAPM widget event flags

    	mixer "name"			# Optional Mixer Control
    	enum "name"			# Optional Enum Control

    	data "name"			# optional private data
     }

The section name is the widget name. The mixer and enum fields are mutually exclusive and used to include controls into the widget. The index and data fields are the same for widgets as they are for controls whilst the other fields map on very closely to the driver widget fields.

#### PCM Capabilities

Topology can also define the capabilities of FE and BE PCMs. Capabilities can be defined with the following section :-

     SectionPCMCapabilities."name" {

    	formats "S24_LE,S16_LE"		# Supported formats
    	rate_min "48000"		# Max supported sample rate
    	rate_max "48000"		# Min supported sample rate
    	channels_min "2"		# Min number of channels
    	channels_max "2"		# max number of channels
     }

The supported formats use the same naming convention as the driver macros. The PCM capabilities name can be referred to and included by BE, PCM and Codec <-> codec topology sections.

#### PCM Configurations

PCM runtime configurations can be defined for playback and capture stream directions with the following section :-

     SectionPCMConfig."name" {

    	config."playback" {		# playback config
    		format "S16_LE"		# playback format
    		rate "48000"		# playback sample rate
    		channels "2"		# playback channels
    		tdm_slot "0xf"		# playback TDM slot
    	}

    	config."capture" {		# capture config
    		format "S16_LE"		# capture format
    		rate "48000"		# capture sample rate
    		channels "2"		# capture channels
    		tdm_slot "0xf"		# capture TDM slot
    	}
     }

The supported formats use the same naming convention as the driver macros. The PCM configuration name can be referred to and included by BE, PCM and Codec <-> codec topology sections.

#### PCM Configurations

PCM, BE and Codec to Codec link sections define the supported capabilities and configurations for supported playback and capture streams. The definitions and content for PCMs, BE and Codec links are the same with the exception of the section type :-

     SectionPCM."name" {
    	....
     }
     SectionBE."name" {
    	....
     }
     SectionCC."name" {
    	....
     }

The section types above should be used for PCMs, Back Ends and Codec to Codec links respectively.

The data for each section is defined as follows :-

     SectionPCM."name" {

    	index "1"			# Index number

    	id "0"				# used for binding to the PCM

    	pcm."playback" {
    		capabilities "capabilities1"	# capabilities for playback

    		configs [		# supported configs for playback
    			"config1"
    			"config2"
    		]
    	}

    	pcm."capture" {
    		capabilities "capabilities2"	# capabilities for capture

    		configs [		# supported configs for capture
    			"config1"
    			"config2"
    			"config3"
    		]
    	}
     }

## Define Documentation

#define SND_TPLG_MAX_CHAN 8

Maximum number of channels supported in one control

## Typedef Documentation

typedef struct snd_tplg snd_tplg_t

Topology context

## Enumeration Type Documentation

enum snd_tplg_type

Topology object types

Enumerator:

  SND_TPLG_TYPE_TLV | TLV Data
  SND_TPLG_TYPE_MIXER | Mixer control
  SND_TPLG_TYPE_ENUM | Enumerated control
  SND_TPLG_TYPE_TEXT | Text data
  SND_TPLG_TYPE_DATA | Private data
  SND_TPLG_TYPE_BYTES | Byte control
  SND_TPLG_TYPE_STREAM_CONFIG | PCM Stream configuration
  SND_TPLG_TYPE_STREAM_CAPS | PCM Stream capabilities
  SND_TPLG_TYPE_PCM | PCM stream device
  SND_TPLG_TYPE_DAPM_WIDGET | DAPM widget
  SND_TPLG_TYPE_DAPM_GRAPH | DAPM graph elements
  SND_TPLG_TYPE_BE | BE DAI link
  SND_TPLG_TYPE_CC | Hostless codec <-> codec link
  SND_TPLG_TYPE_MANIFEST | Topology manifest

## Function Documentation

int snd_tplg_add_object | ( | snd_tplg_t * | tplg,
|  | snd_tplg_obj_template_t * | t |
| ) |  |  |

Register topology template object.

Parameters:

  | tplg | Topology instance.
  | t | Template object.

Returns:
  Zero on success, otherwise a negative error code

int snd_tplg_build | ( | snd_tplg_t * | tplg,
|  | const char * | outfile |
| ) |  |  |

Build all registered topology data into binary file.

Parameters:

  | tplg | Topology instance.
  | outfile | Binary topology output file.

Returns:
  Zero on success, otherwise a negative error code

int snd_tplg_build_file | ( | snd_tplg_t * | tplg,
|  | const char * | infile,
|  | const char * | outfile |
| ) |  |  |

Parse and build topology text file into binary file.

Parameters:

  | tplg | Topology instance.
  | infile | Topology text input file to be parsed
  | outfile | Binary topology output file.

Returns:
  Zero on success, otherwise a negative error code

void snd_tplg_free | ( | snd_tplg_t * | tplg | ) |

Free a topology parser instance.

Parameters:

  | tplg | Topology parser instance

snd_tplg_t* snd_tplg_new | ( | void |  | ) |

Create a new topology parser instance.

Returns:
  New topology parser instance

int snd_tplg_set_manifest_data | ( | snd_tplg_t * | tplg,
|  | const void * | data,
|  | int | len |
| ) |  |  |

Attach private data to topology manifest.

Parameters:

  | tplg | Topology instance.
  | data | Private data.
  | len | Length of data in bytes.

Returns:
  Zero on success, otherwise a negative error code

int snd_tplg_set_version | ( | snd_tplg_t * | tplg,
|  | unsigned int | version |
| ) |  |  |

Set an optional vendor specific version number.

Parameters:

  | tplg | Topology instance.
  | version | Vendor specific version number.

Returns:
  Zero on success, otherwise a negative error code

void snd_tplg_verbose | ( | snd_tplg_t * | tplg,
|  | int | verbose |
| ) |  |  |

Enable verbose reporting of binary file output.

Parameters:

  | tplg | Topology Instance
  | verbose | Enable verbose output level if non zero

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines