Documentation/sound/soc/clocking.rst | 59 +++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-)
Add ASoC clock api details to this document.
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.
--
2.39.3 (Apple Git-146)On Tue, Oct 29, 2024 at 04:56:23PM -0700, anish kumar wrote: > Add ASoC clock api details to this document. > +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. This feels like it is (or should be) duplicating the kerneldoc generated documentation - I'm not sure that we can cross reference the two sensibly through?
On Wed, Oct 30, 2024 at 6:08 AM Mark Brown <broonie@kernel.org> wrote: > > On Tue, Oct 29, 2024 at 04:56:23PM -0700, anish kumar wrote: > > > Add ASoC clock api details to this document. > > > +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. > > This feels like it is (or should be) duplicating the kerneldoc generated > documentation - I'm not sure that we can cross reference the two > sensibly through? Jonathan, wondering if you know a way to link the clock functions defined in https://github.com/torvalds/linux/blob/master/sound/soc/soc-dai.c here?
anish kumar <yesanishhere@gmail.com> writes: >> This feels like it is (or should be) duplicating the kerneldoc generated >> documentation - I'm not sure that we can cross reference the two >> sensibly through? > > Jonathan, wondering if you know a way to link the clock functions defined > in https://github.com/torvalds/linux/blob/master/sound/soc/soc-dai.c here? I'm not quite sure what your question is. Kerneldoc comments can be brought into the documentation, of course - that's a big part of what the build system does. You can link to that documentation just by saying function() - nothing more required. What else are you looking for? Thanks, jon
On Wed, Oct 30, 2024 at 3:18 PM Jonathan Corbet <corbet@lwn.net> wrote: > > anish kumar <yesanishhere@gmail.com> writes: > > >> This feels like it is (or should be) duplicating the kerneldoc generated > >> documentation - I'm not sure that we can cross reference the two > >> sensibly through? > > > > Jonathan, wondering if you know a way to link the clock functions defined > > in https://github.com/torvalds/linux/blob/master/sound/soc/soc-dai.c here? > > I'm not quite sure what your question is. Kerneldoc comments can be > brought into the documentation, of course - that's a big part of what > the build system does. You can link to that documentation just by > saying function() - nothing more required. What else are you looking > for? Was missing this, thanks Jonathan. .. kernel-doc:: sound/soc/soc-dai.c :identifiers: Will send V2. > > Thanks, > > jon
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
© 2016 - 2024 Red Hat, Inc.