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@xxxxxxxxx>
> ---
> 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:
signature.asc
Description: PGP signature
