[PATCH] ALSA: machine: update documentation

[PATCH] 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>
---
 Documentation/sound/soc/machine.rst | 30 +++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
index 515c9444deaf..af7bad7ba134 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,9 +93,13 @@ 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
------------------
+---------------------------
 
 The machine driver can optionally extend the codec power map and to become an
 audio power map of the audio subsystem. This allows for automatic power up/down
@@ -92,6 +108,16 @@ sockets in the machine init function.
 
 
 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] ALSA: machine: update documentation

[Bagas Sanjaya]

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

On Sat, Nov 02, 2024 at 12:37:18AM -0700, anish kumar wrote:
> +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")));
> +

Make the macro usage a literal code block:

---- >8 ----
diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
index af7bad7ba13455..8788953cd160f5 100644
--- a/Documentation/sound/soc/machine.rst
+++ b/Documentation/sound/soc/machine.rst
@@ -76,9 +76,9 @@ 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.
+platform dai::
 
-SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp,
+  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")));

>  Machine Power Map
> ------------------
> +---------------------------

Keep the section underline length as-is.

>  Machine Controls
> -----------------
> +-----------------------

Likewise.

> +Clocking Controls:
> +—-----------------
> +

Fix the underline to render the section name as a heading:

---- >8 ----
diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
index 8788953cd160f5..bdb9dfc5d88e45 100644
--- a/Documentation/sound/soc/machine.rst
+++ b/Documentation/sound/soc/machine.rst
@@ -113,8 +113,8 @@ Machine Controls
 Machine specific audio mixer controls can be added in the DAI init function.
 
 
-Clocking Controls:
-—-----------------
+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

Thanks.

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

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

Re: [PATCH] ALSA: machine: update documentation

[anish kumar]

Mark,

Do you have any comments, or should I
go ahead and respin the patch to address
the review comments?

On Sat, Nov 2, 2024 at 9:30 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On Sat, Nov 02, 2024 at 12:37:18AM -0700, anish kumar wrote:
> > +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")));
> > +
>
> Make the macro usage a literal code block:
>
> ---- >8 ----
> diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
> index af7bad7ba13455..8788953cd160f5 100644
> --- a/Documentation/sound/soc/machine.rst
> +++ b/Documentation/sound/soc/machine.rst
> @@ -76,9 +76,9 @@ 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.
> +platform dai::
>
> -SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp,
> +  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")));
>
> >  Machine Power Map
> > ------------------
> > +---------------------------
>
> Keep the section underline length as-is.
>
> >  Machine Controls
> > -----------------
> > +-----------------------
>
> Likewise.
>
> > +Clocking Controls:
> > +—-----------------
> > +
>
> Fix the underline to render the section name as a heading:
>
> ---- >8 ----
> diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
> index 8788953cd160f5..bdb9dfc5d88e45 100644
> --- a/Documentation/sound/soc/machine.rst
> +++ b/Documentation/sound/soc/machine.rst
> @@ -113,8 +113,8 @@ Machine Controls
>  Machine specific audio mixer controls can be added in the DAI init function.
>
>
> -Clocking Controls:
> -—-----------------
> +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
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara

Re: [PATCH] ALSA: machine: update documentation

[Mark Brown]

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

On Wed, Nov 06, 2024 at 08:31:14PM -0800, anish kumar wrote:

> Do you have any comments, or should I
> go ahead and respin the patch to address
> the review comments?

Please take the review comments into account.

Please don't top post, reply in line with needed context.  This allows
readers to readily follow the flow of conversation and understand what
you are talking about and also helps ensure that everything in the
discussion is being addressed.

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