ASoC: soc-utils: Improve kerneldoc for snd_soc_tdm_params_to_bclk()
PATCH 1/1 ASoC: soc-utils: Improve kerneldoc for snd_soc_tdm_params_to_bclk()
The statement that snd_soc_tdm_params_to_bclk() is equivalent to snd_soc_params_to_bclk() if tdm_width==tdm_slots==0 is not accurate, it is only true is slot_multiple is also <2.
However, the description of special-case behaviour in terms of pairs of tdm_width and tdm_slot values is not particularly helpful so we might as well take the opportunity to rework the description to say the same thing in a simpler way. The behaviour of a pair of values is obvious from a description of each argument. At the same time make a few edits to clarify the rest of the description.
--- sound/soc/soc-utils.c | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-)
sound/soc/soc-utils.c +12 -11
@@ -56,23 +56,24 @@ EXPORT_SYMBOL_GPL(snd_soc_params_to_bclk);/** * snd_soc_tdm_params_to_bclk - calculate bclk from params and tdm slot info. * -* Calculate the bclk from the params sample rate and the tdm slot count and -* tdm slot width. Either or both of tdm_width and tdm_slots can be 0. +* Calculate the bclk from the params sample rate, the tdm slot count and the +* tdm slot width. Optionally round-up the slot count to a given multiple. +* Either or both of tdm_width and tdm_slots can be 0. * -* If tdm_width == 0 and tdm_slots > 0: the params_width will be used. -* If tdm_width > 0 and tdm_slots == 0: the params_channels will be used -* as the slot count. -* Both tdm_width and tdm_slots are 0: this is equivalent to calling -* snd_soc_params_to_bclk(). +* If tdm_width == 0: use params_width() as the slot width. +* If tdm_slots == 0: use params_channels() as the slot count. * -* If slot_multiple > 1 the slot count (or params_channels if tdm_slots == 0) -* will be rounded up to a multiple of this value. This is mainly useful for +* If slot_multiple > 1 the slot count (or params_channels() if tdm_slots == 0) +* will be rounded up to a multiple of slot_multiple. This is mainly useful for * I2S mode, which has a left and right phase so the number of slots is always * a multiple of 2. * +* If tdm_width == 0 && tdm_slots == 0 && slot_multiple < 2, this is equivalent +* to calling snd_soc_params_to_bclk(). +* * @params: Pointer to struct_pcm_hw_params. -* @tdm_width: Width in bits of the tdm slots. -* @tdm_slots: Number of tdm slots per frame. +* @tdm_width: Width in bits of the tdm slots. Must be >= 0. +* @tdm_slots: Number of tdm slots per frame. Must be >= 0. * @slot_multiple: If >1 roundup slot count to a multiple of this value. * * Return: bclk frequency in Hz, else a negative error code if params format
Signature · 1 line
2.30.2
Mark Brown
maintainerQuoted 4 lines · Richard Fitzgerald
The statement that
snd_soc_tdm_params_to_bclk()is equivalent tosnd_soc_params_to_bclk()if tdm_width==tdm_slots==0 is not accurate, it is only true isslot_multipleis also <2.
Quoted 8 lines
However, the description of special-case behaviour in terms of pairs of
tdm_widthandtdm_slotvalues is not particularly helpful so we might as well take the opportunity to rework the description to say the same thing in a simpler way. The behaviour of a pair of values is obvious from a description of each argument. At the same time make a few edits to clarify the rest of the description.[...]
Applied to
https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-next
Thanks!
[1/1] ASoC: soc-utils: Improve kerneldoc for snd_soc_tdm_params_to_bclk()
commit: efe30e2cb6ff87467389cece8ce604f6601059f9
All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.
You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.
If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.
Please add any relevant lists and maintainers to the CCs when replying to this mail.
Thanks,
Mark