[PATCH V2] ALSA: machine: update documentation

[PATCH V2] 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>
---
V2:
  took care of comments from bagas related to underline
  and making macro 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..9c8e006b1e50 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 V2] ALSA: machine: update documentation

[Jonathan Corbet]

anish kumar <yesanishhere@gmail.com> writes:

> 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>
> ---
> V2:
>   took care of comments from bagas related to underline
>   and making macro 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..9c8e006b1e50 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")));
> +

This will not give you the literal block you were hoping for.  Please
actually build the docs after making changes and look at the results.

Thanks,

jon

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

[Jonathan Corbet]

[I suspect that your HTML email will keep your response off the list -
don't do that.]

anish kumar <yesanishhere@gmail.com> writes:

> On Fri, Nov 8, 2024 at 11:29 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
>  anish kumar <yesanishhere@gmail.com> writes:
>  > +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")));
>  > +
>
>  This will not give you the literal block you were hoping for.  Please
>  actually build the docs after making changes and look at the results.
>
> I was not hoping for literally code block but rather just a tab. I just pasted Bagas comment as I
> thought it is better way to say that about the change. 

The "::" you added above introduces a literal block.  Yes, that is what
you were hoping for.

jon

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

[Bagas Sanjaya]

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

On Fri, Nov 08, 2024 at 12:29:14PM -0700, Jonathan Corbet wrote:
> anish kumar <yesanishhere@gmail.com> writes:
> > +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")));
> > +
> 
> This will not give you the literal block you were hoping for.  Please
> actually build the docs after making changes and look at the results.

My htmldocs build gets:

Documentation/sound/soc/machine.rst:81: WARNING: Literal block expected; none found.

Thanks.

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

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

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

[Bagas Sanjaya]

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

On Fri, Nov 08, 2024 at 11:24:13AM -0800, anish kumar wrote:
> +Clocking Controls
> +—----------------

I see in my htmldocs build output that above section heading is still
normal paragraph instead...

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

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

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

[anish kumar]

On Fri, Nov 8, 2024 at 7:33 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On Fri, Nov 08, 2024 at 11:24:13AM -0800, anish kumar wrote:
> > +Clocking Controls
> > +—----------------
>
> I see in my htmldocs build output that above section heading is still
> normal paragraph instead...

Uploaded a new version to take care of this and the warning.
>
> --
> An old man doll... just what I always wanted! - Clara