[PATCH V3] ALSA: machine: update documentation

[PATCH V3] ALSA: machine: update documentation

[anish kumar]

1. Added clocking details.
2. Updated ways to register the dai's
3. Bit more detail about card registration details.

Signed-off-by: anish kumar <yesanishhere@gmail.com>
---
V3:
 fixed reported warning and html machine output which
 was not formatting 'clocking controls' properly. 

V2:
 took care of comments from bagas related to underline
 and making macros as literal code block

 Documentation/sound/soc/machine.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
index 515c9444deaf..9db132bc0070 100644
--- a/Documentation/sound/soc/machine.rst
+++ b/Documentation/sound/soc/machine.rst
@@ -71,6 +71,18 @@ struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
 	.ops = &corgi_ops,
   };
 
+In the above struct, dai’s are registered using names but you can pass
+either dai name or device tree node but not both. Also, names used here
+for cpu/codec/platform dais should be globally unique.
+
+Additionaly below example macro can be used to register cpu, codec and
+platform dai::
+
+  SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp,
+	DAILINK_COMP_ARRAY(COMP_CPU("samsung-i2s.0")),
+	DAILINK_COMP_ARRAY(COMP_CODEC("spi0.0", "wm0010-sdi1")),
+	DAILINK_COMP_ARRAY(COMP_PLATFORM("samsung-i2s.0")));
+
 struct snd_soc_card then sets up the machine with its DAIs. e.g.
 ::
 
@@ -81,6 +93,10 @@ struct snd_soc_card then sets up the machine with its DAIs. e.g.
 	.num_links = 1,
   };
 
+Following this, ``devm_snd_soc_register_card`` can be used to register
+the sound card. During the registration, the individual components
+such as the codec, CPU, and platform are probed. If all these components
+are successfully probed, the sound card gets registered.
 
 Machine Power Map
 -----------------
@@ -95,3 +111,13 @@ Machine Controls
 ----------------
 
 Machine specific audio mixer controls can be added in the DAI init function.
+
+
+Clocking Controls
+-----------------
+
+As previously noted, clock configuration is handled within the machine driver.
+For details on the clock APIs that the machine driver can utilize for
+setup, please refer to Documentation/sound/soc/clocking.rst. However, the
+callback needs to be registered by the CPU/Codec/Platform drivers to configure
+the clocks that is needed for the corresponding device operation.
-- 
2.39.3 (Apple Git-146)

Re: [PATCH V3] ALSA: machine: update documentation

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2222 bytes --]

On Sat, Nov 09, 2024 at 11:22:31AM -0800, anish kumar wrote:
> diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
> index 515c9444deaf..9db132bc0070 100644
> --- a/Documentation/sound/soc/machine.rst
> +++ b/Documentation/sound/soc/machine.rst
> @@ -71,6 +71,18 @@ struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
>  	.ops = &corgi_ops,
>    };
>  
> +In the above struct, dai’s are registered using names but you can pass
> +either dai name or device tree node but not both. Also, names used here
> +for cpu/codec/platform dais should be globally unique.
> +
> +Additionaly below example macro can be used to register cpu, codec and
> +platform dai::
> +
> +  SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp,
> +	DAILINK_COMP_ARRAY(COMP_CPU("samsung-i2s.0")),
> +	DAILINK_COMP_ARRAY(COMP_CODEC("spi0.0", "wm0010-sdi1")),
> +	DAILINK_COMP_ARRAY(COMP_PLATFORM("samsung-i2s.0")));
> +
>  struct snd_soc_card then sets up the machine with its DAIs. e.g.
>  ::
>  
> @@ -81,6 +93,10 @@ struct snd_soc_card then sets up the machine with its DAIs. e.g.
>  	.num_links = 1,
>    };
>  
> +Following this, ``devm_snd_soc_register_card`` can be used to register
> +the sound card. During the registration, the individual components
> +such as the codec, CPU, and platform are probed. If all these components
> +are successfully probed, the sound card gets registered.
>  
>  Machine Power Map
>  -----------------
> @@ -95,3 +111,13 @@ Machine Controls
>  ----------------
>  
>  Machine specific audio mixer controls can be added in the DAI init function.
> +
> +
> +Clocking Controls
> +-----------------
> +
> +As previously noted, clock configuration is handled within the machine driver.
> +For details on the clock APIs that the machine driver can utilize for
> +setup, please refer to Documentation/sound/soc/clocking.rst. However, the
> +callback needs to be registered by the CPU/Codec/Platform drivers to configure
> +the clocks that is needed for the corresponding device operation.

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH V3] ALSA: machine: update documentation

[Mark Brown]

On Sat, 09 Nov 2024 11:22:31 -0800, anish kumar wrote:
> 1. Added clocking details.
> 2. Updated ways to register the dai's
> 3. Bit more detail about card registration details.
> 
> 

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-next

Thanks!

[1/1] ALSA: machine: update documentation
      commit: e90dbd3839f554bef35786c4bec8276455691b20

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark