Unverified Commit 36de8c0e authored by Luca Ceresoli's avatar Luca Ceresoli Committed by Mark Brown
Browse files

ASoC: doc: dapm: describe how widgets and routes are registered 



The small paragraph describing how to register widgets is incomplete (does
not mention routes) and mentions snd_soc_dapm_new_control() which is not
really used. Moreover it appears as a part of the "Virtual Widgets"
subsection.

Replace it with a detailed and current description of how widgets and
routes are registered, mentioning both static declaration and runtime
registration. Also make this a section on its own.

Reviewed-by: default avatarAlexandre Belloni <alexandre.belloni@bootlin.com>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: default avatarLuca Ceresoli <luca.ceresoli@bootlin.com>
Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-8-87b07547eb5b@bootlin.com


Signed-off-by: default avatarMark Brown <broonie@kernel.org>
parent dd5f36e5

Documentation/sound/soc/dapm.rst

+36 −2
Original line number Diff line number Diff line
@@ -250,8 +250,42 @@ a virtual widget - a widget with no control bits e.g. 


This can be used to merge two signal paths together in software.



After all the widgets have been defined, they can then be added to the DAPM

subsystem individually with a call to snd_soc_dapm_new_control().

Registering DAPM controls

=========================



In many cases the DAPM widgets implemented statically in a ``static const

struct snd_soc_dapm_widget`` array and the routes connecting them in a

``static const struct snd_soc_dapm_route`` array in a codec driver, and

simply declared via the ``dapm_widgets`` and ``num_dapm_widgets`` fields of

the ``struct snd_soc_component_driver`` so the driver registration will

take care of populating them::



  static const struct snd_soc_dapm_widget wm2000_dapm_widgets[] = {

  	SND_SOC_DAPM_OUTPUT("SPKN"),

  	SND_SOC_DAPM_OUTPUT("SPKP"),

  	...

  };



  /* Target, Path, Source */

  static const struct snd_soc_dapm_route wm2000_audio_map[] = {

  	{ "SPKN", NULL, "ANC Engine" },

  	{ "SPKP", NULL, "ANC Engine" },

	...

  };



  static const struct snd_soc_component_driver soc_component_dev_wm2000 = {

	...

  	.dapm_widgets		= wm2000_dapm_widgets,

  	.num_dapm_widgets	= ARRAY_SIZE(wm2000_dapm_widgets),

	...

  };



In more complex cases the list of DAPM widgets and/or routes can be only

known at build time. This happens for example when a driver supports

different models having a different set of features. In those cases

separate widgets and routes arrays implementing the case-specific features

can be registered programmatically by calling snd_soc_dapm_new_controls()

and snd_soc_dapm_add_routes().





Codec/DSP Widget Interconnections