Re: [PATCH V2] ASoC: doc: update clocking

[Bagas Sanjaya <bagasdotme@gmail.com>]

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

On Tue, Oct 29, 2024 at 04:56:23PM -0700, anish kumar wrote:
> Add ASoC clock api details to this document.

Patch title should be "ASOC: doc: Document DAI clock APIs". The patch
description (i.e. commit message) should reflect from the title.

> 
> Signed-off-by: anish kumar <yesanishhere@gmail.com>
> ---
> v2: fixed the compilation errors
> 
>  Documentation/sound/soc/clocking.rst | 59 +++++++++++++++++++++++++++-
>  1 file changed, 58 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/sound/soc/clocking.rst b/Documentation/sound/soc/clocking.rst
> index 32122d6877a3..8ba16c7ae75f 100644
> --- a/Documentation/sound/soc/clocking.rst
> +++ b/Documentation/sound/soc/clocking.rst
> @@ -18,7 +18,6 @@ Some master clocks (e.g. PLLs and CPU based clocks) are configurable in that
>  their speed can be altered by software (depending on the system use and to save
>  power). Other master clocks are fixed at a set frequency (i.e. crystals).
>  
> -
>  DAI Clocks
>  ----------
>  The Digital Audio Interface is usually driven by a Bit Clock (often referred to
> @@ -42,5 +41,63 @@ rate, number of channels and word size) to save on power.
>  It is also desirable to use the codec (if possible) to drive (or master) the
>  audio clocks as it usually gives more accurate sample rates than the CPU.
>  
> +ASoC provided clock APIs
> +------------------------
> +
> +.. function:: int snd_soc_dai_set_sysclk(struct snd_soc_dai *dai,
> +                                          int clk_id, unsigned int freq,
> +                                          int dir)
> +
> +   This function is generally called in the machine driver to set the
> +   sysclk or MCLK. This function in turn calls the codec or platform
> +   callbacks to set the sysclk/MCLK. If the call ends up in the codec
> +   driver and MCLK is provided by the codec, the direction should be
> +   :c:macro:`SND_SOC_CLOCK_IN`. If the processor is providing the clock,
> +   it should be set to :c:macro:`SND_SOC_CLOCK_OUT`. If the callback
> +   ends up in the platform/cpu driver, it can set up any clocks that are
> +   required for platform hardware.
> +
> +   :param dai: Digital audio interface corresponding to the component.
> +   :param clk_id: DAI specific clock ID.
> +   :param freq: New clock frequency in Hz.
> +   :param dir: New clock direction (:c:macro:`SND_SOC_CLOCK_IN` or
> +                :c:macro:`SND_SOC_CLOCK_OUT`).
> +
> +.. function:: int snd_soc_dai_set_clkdiv(struct snd_soc_dai *dai,
> +                                          int div_id, int div)
> +
> +   This function is used to set the clock divider for the corresponding
> +   DAI. It is called in the machine driver. In the case of codec DAI
> +   connected through I2S for data transfer, bit clock dividers are set
> +   based on this call to either a multiple of the bit clock frequency
> +   required to support the requested sample rate or equal to the bit
> +   clock frequency.
> +
> +   :param dai: Digital audio interface corresponding to the component.
> +   :param div_id: DAI specific clock divider ID.
> +   :param div: New clock divisor.
> +
> +.. function:: int snd_soc_dai_set_pll(struct snd_soc_dai *dai,
> +                                       int pll_id, int source,
> +                                       unsigned int freq_in,
> +                                       unsigned int freq_out)
> +
> +   This interface function provides a way for the DAI component drivers
> +   to configure PLL based on the input clock. This is called in the machine
> +   driver. This PLL can be used to generate output clock such as the
> +   bit clock for the codec.
> +
> +   :param dai: Digital audio interface corresponding to the component.
> +   :param pll_id: DAI specific PLL ID.
> +   :param source: DAI specific source for the PLL.
> +   :param freq_in: PLL input clock frequency in Hz.
> +   :param freq_out: Requested PLL output clock frequency in Hz.
> +
> +.. function:: int snd_soc_dai_set_bclk_ratio(struct snd_soc_dai *dai,
> +                                              unsigned int ratio)
>  
> +   This function configures the DAI for a preset BCLK to sample rate
> +   ratio. It is called in the machine driver.
>  
> +   :param dai: Digital audio interface corresponding to the component.
> +   :param ratio: Ratio of BCLK to sample rate.

Sphinx reports htmldocs warnings due to function prototypes split into
multiple lines:

Documentation/sound/soc/clocking.rst:47: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 51]
  int snd_soc_dai_set_sysclk(struct snd_soc_dai *dai,
  ---------------------------------------------------^
Documentation/sound/soc/clocking.rst:47: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 10]
  int clk_id, unsigned int freq,
  ----------^
Documentation/sound/soc/clocking.rst:47: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 7]
  int dir)
  -------^
Documentation/sound/soc/clocking.rst:66: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 51]
  int snd_soc_dai_set_clkdiv(struct snd_soc_dai *dai,
  ---------------------------------------------------^
Documentation/sound/soc/clocking.rst:66: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 10]
  int div_id, int div)
  ----------^
Documentation/sound/soc/clocking.rst:80: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 48]
  int snd_soc_dai_set_pll(struct snd_soc_dai *dai,
  ------------------------------------------------^
Documentation/sound/soc/clocking.rst:80: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 10]
  int pll_id, int source,
  ----------^
Documentation/sound/soc/clocking.rst:80: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 20]
  unsigned int freq_in,
  --------------------^
Documentation/sound/soc/clocking.rst:80: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 21]
  unsigned int freq_out)
  ---------------------^
Documentation/sound/soc/clocking.rst:96: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 55]
  int snd_soc_dai_set_bclk_ratio(struct snd_soc_dai *dai,
  -------------------------------------------------------^
Documentation/sound/soc/clocking.rst:96: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 18]
  unsigned int ratio)
  ------------------^

I have to merge these lines so that the prototypes are formatted correctly
in the output with syntax-highlighted data types:

---- >8 ----
diff --git a/Documentation/sound/soc/clocking.rst b/Documentation/sound/soc/clocking.rst
index 8ba16c7ae75f44..a1f4b8cb4d247f 100644
--- a/Documentation/sound/soc/clocking.rst
+++ b/Documentation/sound/soc/clocking.rst
@@ -44,9 +44,7 @@ audio clocks as it usually gives more accurate sample rates than the CPU.
 ASoC provided clock APIs
 ------------------------
 
-.. function:: int snd_soc_dai_set_sysclk(struct snd_soc_dai *dai,
-                                          int clk_id, unsigned int freq,
-                                          int dir)
+.. function:: int snd_soc_dai_set_sysclk(struct snd_soc_dai *dai, int clk_id, unsigned int freq, int dir)
 
    This function is generally called in the machine driver to set the
    sysclk or MCLK. This function in turn calls the codec or platform
@@ -63,8 +61,7 @@ ASoC provided clock APIs
    :param dir: New clock direction (:c:macro:`SND_SOC_CLOCK_IN` or
                 :c:macro:`SND_SOC_CLOCK_OUT`).
 
-.. function:: int snd_soc_dai_set_clkdiv(struct snd_soc_dai *dai,
-                                          int div_id, int div)
+.. function:: int snd_soc_dai_set_clkdiv(struct snd_soc_dai *dai, int div_id, int div)
 
    This function is used to set the clock divider for the corresponding
    DAI. It is called in the machine driver. In the case of codec DAI
@@ -77,10 +74,7 @@ ASoC provided clock APIs
    :param div_id: DAI specific clock divider ID.
    :param div: New clock divisor.
 
-.. function:: int snd_soc_dai_set_pll(struct snd_soc_dai *dai,
-                                       int pll_id, int source,
-                                       unsigned int freq_in,
-                                       unsigned int freq_out)
+.. function:: int snd_soc_dai_set_pll(struct snd_soc_dai *dai, int pll_id, int source, unsigned int freq_in, unsigned int freq_out)
 
    This interface function provides a way for the DAI component drivers
    to configure PLL based on the input clock. This is called in the machine
@@ -93,8 +87,7 @@ ASoC provided clock APIs
    :param freq_in: PLL input clock frequency in Hz.
    :param freq_out: Requested PLL output clock frequency in Hz.
 
-.. function:: int snd_soc_dai_set_bclk_ratio(struct snd_soc_dai *dai,
-                                              unsigned int ratio)
+.. function:: int snd_soc_dai_set_bclk_ratio(struct snd_soc_dai *dai, unsigned int ratio)
 
    This function configures the DAI for a preset BCLK to sample rate
    ratio. It is called in the machine driver.

Thanks.

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

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