From 534e0cd89baf74c22ca55b442fb4add8d844e272 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:34 +0200 Subject: ASoC: doc: dapm: fix typos Fix various typos. Reviewed-by: Alexandre Belloni Reviewed-by: Bagas Sanjaya Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-1-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index c3154ce6e1b2..59f65b181828 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -50,7 +50,7 @@ Stream domain All DAPM power switching decisions are made automatically by consulting an audio routing map of the whole machine. This map is specific to each machine and consists of the interconnections between every audio component (including -internal codec components). All audio components that effect power are called +internal codec components). All audio components that affect power are called widgets hereafter. @@ -221,7 +221,7 @@ when the Mic is inserted:-:: Codec (BIAS) Domain ------------------- -The codec bias power domain has no widgets and is handled by the codecs DAPM +The codec bias power domain has no widgets and is handled by the codec DAPM event handler. This handler is called when the codec powerstate is changed wrt to any stream event or by kernel PM events. @@ -236,7 +236,7 @@ a virtual widget - a widget with no control bits e.g. SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_NOPM, 0, 0, NULL, 0), -This can be used to merge to signal paths together in software. +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(). -- cgit v1.2.3 From eaf84bda623e0a034fe03b871addf7dc4f70dfff Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:35 +0200 Subject: ASoC: doc: dapm: fix struct name struct snd_soc_codec_dai does not exist. Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-2-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 59f65b181828..68ef79f539f2 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -148,7 +148,7 @@ Stream widgets have the following format:- SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert) NOTE: the stream name must match the corresponding stream name in your codec -snd_soc_codec_dai. +snd_soc_dai_driver. e.g. stream widgets for HiFi playback and capture :: -- cgit v1.2.3 From 610277caa77f07997857ab2e31a073d8ad7ed090 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:36 +0200 Subject: ASoC: doc: dapm: minor rewording Slightly reword for better readability: replace "PM" -> "power management frameworks", add missing comma. Reviewed-by: Alexandre Belloni Reviewed-by: Bagas Sanjaya Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-3-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 68ef79f539f2..479c010d2dac 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -7,8 +7,8 @@ Description Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices to use the minimum amount of power within the audio -subsystem at all times. It is independent of other kernel PM and as -such, can easily co-exist with the other PM systems. +subsystem at all times. It is independent of other kernel power +management frameworks and, as such, can easily co-exist with them. DAPM is also completely transparent to all user space applications as all power switching is done within the ASoC core. No code changes or -- cgit v1.2.3 From 3233a68fcb216a2d8615862841c1fca7a940fc5c Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:37 +0200 Subject: ASoC: doc: dapm: remove dash after colon There is no need for a dash after colons. Also fix an incorrect ":-::" sequence. Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-4-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 479c010d2dac..be849879274d 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -20,7 +20,7 @@ DAPM spans the whole machine. It covers power control within the entire audio subsystem, this includes internal codec power blocks and machine level power systems. -There are 4 power domains within DAPM +There are 4 power domains within DAPM: Codec bias domain VREF, VMID (core codec and audio power) @@ -57,7 +57,7 @@ widgets hereafter. DAPM Widgets ============ -Audio DAPM widgets fall into a number of types:- +Audio DAPM widgets fall into a number of types: Mixer Mixes several analog signals into a single analog signal. @@ -141,7 +141,7 @@ Stream Widgets relate to the stream power domain and only consist of ADCs (analog to digital converters), DACs (digital to analog converters), AIF IN and AIF OUT. -Stream widgets have the following format:- +Stream widgets have the following format: :: SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), @@ -167,7 +167,7 @@ Path Domain Widgets ------------------- Path domain widgets have a ability to control or affect the audio signal or -audio paths within the audio subsystem. They have the following form:- +audio paths within the audio subsystem. They have the following form: :: SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) @@ -207,7 +207,7 @@ powered. e.g. A machine widget can have an optional call back. e.g. Jack connector widget for an external Mic that enables Mic Bias -when the Mic is inserted:-:: +when the Mic is inserted:: static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) { @@ -271,7 +271,7 @@ connect the destination widget (wrt audio signal) with its source widgets. {"Output Mixer", "HiFi Playback Switch", "DAC"}, {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"}, -So we have :- +So we have : * Destination Widget <=== Path Name <=== Source Widget, or * Sink, Path, Source, or @@ -280,7 +280,7 @@ So we have :- When there is no path name connecting widgets (e.g. a direct connection) we pass NULL for the path name. -Interconnections are created with a call to:- +Interconnections are created with a call to: :: snd_soc_dapm_connect_input(codec, sink, path, source); -- cgit v1.2.3 From 7d0e76107894377a14f211c85a821a53416d5ab2 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:39 +0200 Subject: ASoC: doc: dapm: replace "map" with "graph" DAPM is actually based on a graph, so use this specific term instead of the more generic "map". Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-6-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index be849879274d..eb50400fa321 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -48,7 +48,7 @@ Stream domain stopped respectively. e.g. aplay, arecord. All DAPM power switching decisions are made automatically by consulting an audio -routing map of the whole machine. This map is specific to each machine and +routing graph of the whole machine. This graph is specific to each machine and consists of the interconnections between every audio component (including internal codec components). All audio components that affect power are called widgets hereafter. @@ -229,7 +229,7 @@ to any stream event or by kernel PM events. Virtual Widgets --------------- -Sometimes widgets exist in the codec or machine audio map that don't have any +Sometimes widgets exist in the codec or machine audio graph that don't have any corresponding soft power control. In this case it is necessary to create a virtual widget - a widget with no control bits e.g. :: @@ -247,7 +247,7 @@ Codec/DSP Widget Interconnections Widgets are connected to each other within the codec, platform and machine by audio paths (called interconnections). Each interconnection must be defined in -order to create a map of all audio paths between widgets. +order to create a graph of all audio paths between widgets. This is easiest with a diagram of the codec or DSP (and schematic of the machine audio system), as it requires joining widgets together via their audio signal -- cgit v1.2.3 From dd5f36e59134654f9fd7b39d4d66327a1a2db82d Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:40 +0200 Subject: ASoC: doc: dapm: extend initial descrption Extend the initial description providing clearer definitions of "widget" and "route", and to stop using the word "component" to mean "widget". Give more details and clarify wording and add a picture representing a real DAPM graph. Group all the introductory paragraphs before the "DAPM power domains", and split the latter to a specific section. Reviewed-by: Alexandre Belloni Reviewed-by: Bagas Sanjaya Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-7-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm-graph.svg | 375 +++++++++++++++++++++++++++++++++ Documentation/sound/soc/dapm.rst | 30 ++- 2 files changed, 396 insertions(+), 9 deletions(-) create mode 100644 Documentation/sound/soc/dapm-graph.svg (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm-graph.svg b/Documentation/sound/soc/dapm-graph.svg new file mode 100644 index 000000000000..d783672db815 --- /dev/null +++ b/Documentation/sound/soc/dapm-graph.svg @@ -0,0 +1,375 @@ + + + + + + +G + + +ROOT + +ROOT + + +4000b000.audio-controller + +4000b000.audio-controller + + +cs42l51.0-004a + +cs42l51.0-004a + + +hdmi-audio-codec.1.auto + +hdmi-audio-codec.1.auto + + + +ROOT_Amplifier + +Amplifier +[out_drv] + + + +4000b000.audio-controller_capture + +capture +[dai_out] + + + +4000b000.audio-controller_playback + +playback +[dai_in] + + + +hdmi-audio-codec.1.auto_I2S Playback + +I2S Playback +[dai_in] + + + +4000b000.audio-controller_playback->hdmi-audio-codec.1.auto_I2S Playback + + + + + +hdmi-audio-codec.1.auto_Capture + +Capture +[dai_out] + + + +hdmi-audio-codec.1.auto_Capture->4000b000.audio-controller_capture + + + + + +cs42l51.0-004a_AIN1L + +AIN1L +[input] + + + +cs42l51.0-004a_PGA-ADC Mux Left + +PGA-ADC Mux Left +[mux] + + + +cs42l51.0-004a_AIN1L->cs42l51.0-004a_PGA-ADC Mux Left + + + + + +cs42l51.0-004a_AIN1R + +AIN1R +[input] + + + +cs42l51.0-004a_PGA-ADC Mux Right + +PGA-ADC Mux Right +[mux] + + + +cs42l51.0-004a_AIN1R->cs42l51.0-004a_PGA-ADC Mux Right + + + + + +cs42l51.0-004a_AIN2L + +AIN2L +[input] + + + +cs42l51.0-004a_AIN2R + +AIN2R +[input] + + + +cs42l51.0-004a_Capture + +Capture +[dai_out] + + + +cs42l51.0-004a_DAC Mux + +DAC Mux +[mux] + + + +cs42l51.0-004a_Left DAC + +Left DAC +[dac] + + + +cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Left DAC + + + + + +cs42l51.0-004a_Right DAC + +Right DAC +[dac] + + + +cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Right DAC + + + + + +cs42l51.0-004a_HPL + +HPL +[output] + + + +cs42l51.0-004a_HPR + +HPR +[output] + + + +cs42l51.0-004a_Left ADC + +Left ADC +[adc] + + + +cs42l51.0-004a_Left ADC->cs42l51.0-004a_Capture + + + + + +cs42l51.0-004a_Left DAC->cs42l51.0-004a_HPL + + + + + +cs42l51.0-004a_Left PGA + +Left PGA +[pga] + + + +cs42l51.0-004a_Left PGA->cs42l51.0-004a_Left ADC + + + + + +cs42l51.0-004a_MCLK + +MCLK +[supply] + + + +cs42l51.0-004a_MCLK->cs42l51.0-004a_Capture + + + + + +cs42l51.0-004a_Playback + +Playback +[dai_in] + + + +cs42l51.0-004a_MCLK->cs42l51.0-004a_Playback + + + + + +cs42l51.0-004a_MICL + +MICL +[input] + + + +cs42l51.0-004a_Mic Preamp Left + +Mic Preamp Left +[mixer] + + + +cs42l51.0-004a_MICL->cs42l51.0-004a_Mic Preamp Left + + + + + +cs42l51.0-004a_MICR + +MICR +[input] + + + +cs42l51.0-004a_Mic Preamp Right + +Mic Preamp Right +[mixer] + + + +cs42l51.0-004a_MICR->cs42l51.0-004a_Mic Preamp Right + + + + + +cs42l51.0-004a_Mic Bias + +Mic Bias +[supply] + + + +cs42l51.0-004a_Mic Bias->cs42l51.0-004a_MICL + + + + + +cs42l51.0-004a_PGA-ADC Mux Left->cs42l51.0-004a_Left PGA + + + + + +cs42l51.0-004a_Right PGA + +Right PGA +[pga] + + + +cs42l51.0-004a_PGA-ADC Mux Right->cs42l51.0-004a_Right PGA + + + + + +cs42l51.0-004a_Playback->cs42l51.0-004a_DAC Mux + + + + + +cs42l51.0-004a_Right ADC + +Right ADC +[adc] + + + +cs42l51.0-004a_Right ADC->cs42l51.0-004a_Capture + + + + + +cs42l51.0-004a_Right DAC->cs42l51.0-004a_HPR + + + + + +cs42l51.0-004a_Right PGA->cs42l51.0-004a_Right ADC + + + + + +hdmi-audio-codec.1.auto_TX + +TX +[output] + + + +hdmi-audio-codec.1.auto_I2S Playback->hdmi-audio-codec.1.auto_TX + + + + + +hdmi-audio-codec.1.auto_RX + +RX +[output] + + + +hdmi-audio-codec.1.auto_RX->hdmi-audio-codec.1.auto_Capture + + + + + diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index eb50400fa321..8d741295fc40 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -16,9 +16,27 @@ recompiling are required for user space applications. DAPM makes power switching decisions based upon any audio stream (capture/playback) activity and audio mixer settings within the device. -DAPM spans the whole machine. It covers power control within the entire -audio subsystem, this includes internal codec power blocks and machine -level power systems. +DAPM is based on two basic elements, called widgets and routes: + + * a **widget** is every part of the audio hardware that can be enabled by + software when in use and disabled to save power when not in use + * a **route** is an interconnection between widgets that exists when sound + can flow from one widget to the other + +All DAPM power switching decisions are made automatically by consulting an +audio routing graph. This graph is specific to each sound card and spans +the whole sound card, so some DAPM routes connect two widgets belonging to +different components (e.g. the LINE OUT pin of a CODEC and the input pin of +an amplifier). + +The graph for the STM32MP1-DK1 sound card is shown in picture: + +.. kernel-figure:: dapm-graph.svg + :alt: Example DAPM graph + :align: center + +DAPM power domains +================== There are 4 power domains within DAPM: @@ -47,12 +65,6 @@ Stream domain Enabled and disabled when stream playback/capture is started and stopped respectively. e.g. aplay, arecord. -All DAPM power switching decisions are made automatically by consulting an audio -routing graph of the whole machine. This graph is specific to each machine and -consists of the interconnections between every audio component (including -internal codec components). All audio components that affect power are called -widgets hereafter. - DAPM Widgets ============ -- cgit v1.2.3 From 36de8c0e26793beeda1d6a7592f44b4551271469 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:41 +0200 Subject: 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: Alexandre Belloni Reviewed-by: Bagas Sanjaya Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-8-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 8d741295fc40..57d96a39f124 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -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 -- cgit v1.2.3 From d40e82194423c9d058bdeff863373b7da9f7045b Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:42 +0200 Subject: ASoC: doc: dapm: fix and improve section "Registering DAPM controls" Extend the first paragraph to mention the {,num_}dapm_routes fields just like the widget conterparts. Mention the route fields also in the code example. Fix "at build time", this really means "at probe time". Reviewed-by: Alexandre Belloni Reviewed-by: Bagas Sanjaya Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-9-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 57d96a39f124..50f908f4e8ed 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -253,12 +253,17 @@ This can be used to merge two signal paths together in software. 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:: +In many cases the DAPM widgets are implemented statically in a ``static +const struct snd_soc_dapm_widget`` array in a codec driver, and simply +declared via the ``dapm_widgets`` and ``num_dapm_widgets`` fields of the +``struct snd_soc_component_driver``. + +Similarly, routes connecting them are implemented statically in a ``static +const struct snd_soc_dapm_route`` array and declared via the +``dapm_routes`` and ``num_dapm_routes`` fields of the same struct. + +With the above declared, the driver registration will take care of +populating them:: static const struct snd_soc_dapm_widget wm2000_dapm_widgets[] = { SND_SOC_DAPM_OUTPUT("SPKN"), @@ -277,11 +282,13 @@ take care of populating them:: ... .dapm_widgets = wm2000_dapm_widgets, .num_dapm_widgets = ARRAY_SIZE(wm2000_dapm_widgets), + .dapm_routes = wm2000_audio_map, + .num_dapm_routes = ARRAY_SIZE(wm2000_audio_map), ... }; 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 +known at probe 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() -- cgit v1.2.3 From 057acfb460d6792c7d3ec088f57c411fb0e4d395 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:43 +0200 Subject: ASoC: doc: dapm: improve section "Codec/DSP Widget Interconnections" Improve wording in a few places, cleanup ReST colon syntax, remove space before colon, and remove the "codec" parameter in the parentheses of snd_soc_dapm_new_widgets() (there should be no parameters in the docs, and that function takes a card, not a codec). Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-10-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 50f908f4e8ed..8fccdb0d6454 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -306,25 +306,23 @@ This is easiest with a diagram of the codec or DSP (and schematic of the machine audio system), as it requires joining widgets together via their audio signal paths. -e.g., from the WM8731 output mixer (wm8731.c) - -The WM8731 output mixer has 3 inputs (sources) +For example the WM8731 output mixer (wm8731.c) has 3 inputs (sources): 1. Line Bypass Input 2. DAC (HiFi playback) 3. Mic Sidetone Input -Each input in this example has a kcontrol associated with it (defined in example -above) and is connected to the output mixer via its kcontrol name. We can now -connect the destination widget (wrt audio signal) with its source widgets. -:: +Each input in this example has a kcontrol associated with it (defined in +the example above) and is connected to the output mixer via its kcontrol +name. We can now connect the destination widget (wrt audio signal) with its +source widgets. :: /* output mixer */ {"Output Mixer", "Line Bypass Switch", "Line Input"}, {"Output Mixer", "HiFi Playback Switch", "DAC"}, {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"}, -So we have : +So we have: * Destination Widget <=== Path Name <=== Source Widget, or * Sink, Path, Source, or @@ -333,12 +331,11 @@ So we have : When there is no path name connecting widgets (e.g. a direct connection) we pass NULL for the path name. -Interconnections are created with a call to: -:: +Interconnections are created with a call to:: snd_soc_dapm_connect_input(codec, sink, path, source); -Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and +Finally, snd_soc_dapm_new_widgets() must be called after all widgets and interconnections have been registered with the core. This causes the core to scan the codec and machine so that the internal DAPM state matches the physical state of the machine. -- cgit v1.2.3 From ce5a4f101cd0dfbda391d4f1815222d82a9d8a5a Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:44 +0200 Subject: ASoC: doc: dapm: update section "DAPM Widget Events" The example in this section is not in the kernel sources anymore. Replace it with an up to date code fragment. Reword the initial paragraph. Remove "Please" which is not standard practice in documentation. Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-11-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 8fccdb0d6454..2a1cfa2eca83 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -376,23 +376,29 @@ jacks can also be switched OFF. DAPM Widget Events ================== -Some widgets can register their interest with the DAPM core in PM events. -e.g. A Speaker with an amplifier registers a widget so the amplifier can be -powered only when the spk is in use. -:: +Widgets needing to implement a more complex behaviour than what DAPM can do +can set a custom "event handler" by setting a function pointer. An example +is a power supply needing to enable a GPIO:: - /* turn speaker amplifier on/off depending on use */ - static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) + static int sof_es8316_speaker_power_event(struct snd_soc_dapm_widget *w, + struct snd_kcontrol *kcontrol, int event) { - gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event)); - return 0; + if (SND_SOC_DAPM_EVENT_ON(event)) + gpiod_set_value_cansleep(gpio_pa, true); + else + gpiod_set_value_cansleep(gpio_pa, false); + + return 0; } - /* corgi machine dapm widgets */ - static const struct snd_soc_dapm_widget wm8731_dapm_widgets = - SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); + static const struct snd_soc_dapm_widget st_widgets[] = { + ... + SND_SOC_DAPM_SUPPLY("Speaker Power", SND_SOC_NOPM, 0, 0, + sof_es8316_speaker_power_event, + SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMU), + }; -Please see soc-dapm.h for all other widgets that support events. +See soc-dapm.h for all other widgets that support events. Event types -- cgit v1.2.3 From 4155a82f6af8068473cd66b55da56fd379835fb0 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 26 Apr 2024 18:56:45 +0200 Subject: ASoC: doc: dapm: update event types Some new event types now exist, so update the code fragment. Reviewed-by: Alexandre Belloni Signed-off-by: Luca Ceresoli Link: https://lore.kernel.org/r/20240426-dapm-docs-v2-12-87b07547eb5b@bootlin.com Signed-off-by: Mark Brown --- Documentation/sound/soc/dapm.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) (limited to 'Documentation/sound') diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 2a1cfa2eca83..14c4dc026e6b 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -404,13 +404,16 @@ See soc-dapm.h for all other widgets that support events. Event types ----------- -The following event types are supported by event widgets. -:: +The following event types are supported by event widgets:: /* dapm event types */ - #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ - #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ - #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ - #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ - #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ - #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ + #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ + #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ + #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ + #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ + #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ + #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ + #define SND_SOC_DAPM_WILL_PMU 0x40 /* called at start of sequence */ + #define SND_SOC_DAPM_WILL_PMD 0x80 /* called at start of sequence */ + #define SND_SOC_DAPM_PRE_POST_PMD (SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMD) + #define SND_SOC_DAPM_PRE_POST_PMU (SND_SOC_DAPM_PRE_PMU | SND_SOC_DAPM_POST_PMU) -- cgit v1.2.3