ALSA topology

From AlsaProject
Jump to: navigation, search

ALSA Topology provides a method for audio drivers to load their mixers, routing, PCMs and capabilities from user space at runtime without changing any driver source code. The intention is to write the driver once and do the differentiation in topology.


Why we need topology?

Current audio drivers typically hard code topology information in the driver sources: This tightly couples the audio driver to the development board making it time consuming to modify a driver to work on a different devices. The driver is also tightly coupled to the DSP firmware version meaning extra care is needed to keep the driver and firmware version in sync. New firmware features also mean driver updates.

The ALSA topology project removes the need for re-writing or porting audio drivers to different devices or different firmwares: Drivers have no hard coded topology data meaning a single driver can be used on different devices by updating the topology data from the file system. Firmware updates can be pushed without having to update the drivers. The new firmware just needs to include an updated topology file describing the update.

Topology Objects

The topology objects that can be configured by user space include: controls, widgets, routes, PCMs and configurations for physical DAI & DAI links.

Here is an example.


Topology Architecture


User space

The topology library is part of alsa-lib. Users can define topology objects that describe the topology of a customer firmware, e.g. for an ADSP embedded in SOC or an off-SOC codec. These topology objects can be defined either in a text configuration file or added via C API. And the topology library will parse them and generate a binary file for kernel. Please see the source code in directory src/topology of alsa-lib.

The generated topology binary file consists of a manifest and a list of blocks. The manifest data provides overall info of the topology object types in the file, i.e. number of controls, widgets, routes, PCMs, physical DAI and physical DAI links. Each block consists of a blocker header and a specific type of topology objects. For the layout of file and topology object, please see the ABI file in alsa-lib include/sound/asoc.h and tlv.h

How to generate the topology binary file

Users can define topology objects in a text configuration file. The syntax is based on alsaconf syntax, please see alsa-lib/include/alsa/topology.h Then users can use alsatplg, the topology tool in alsa-utils, to covert the topology text configuration file to the binary, via command "alsatplg -c <path-of-input-text-configuration-file> -o <path-of-output-binary-file>". Please see the alsatplg code in directory topology of alsa-utils, and Intel Broadwell and Skylake configurations in alsa-lib/src/conf/topology as examples of the text configuration file.

Users can also write their own application and call topology library API to add objects and generate the binary file. Please see alsa-lib/include/alsa/topology.h for the API definition.


The topology kernel driver provides API for device drivers to load the topology binary file from the user space, then it will parse the ABI objects in the file, create controls, widgets, routes, front end DAI and DAI links (PCMs) and configure existing physical DAI and DAI links. It will also let the device driver do platform specific initialization on these objects via topology ops registered by the device driver. Please see code of sound/soc/soc-topology.c in kernel.

How device drivers use topology

Intel Skylake platform driver is an example how device drivers use topology, please see code of sound/soc/intel/skylake/skl-topology.c in kernel.

Custom Search
Personal tools