[PATCH v3 0/9] clk: add kunit tests and some documentation

[Brian Masney <bmasney@redhat.com>]

Here's a series that adds various kunit tests to the clk framework,
and documents the members of struct clk_core. These tests are centered
around inconsistencies and limitations in the clock framework that may
lead to some clocks unknowingly changing rates during a rate change of
their siblings.

The intent of the clock framework is to keep the siblings clock rate
stable during such an operation:

    clk_set_rate(clk, MY_NEW_RATE);

However, it assumes that the sibling can generate that rate in the first
place. In many situations, it can't, and it leads to numerous bugs and
solutions over the years.

https://lore.kernel.org/lkml/20230825-pll-mipi_keep_rate-v1-0-35bc43570730@oltmanns.dev/
https://lore.kernel.org/linux-kernel/20230807-pll-mipi_set_rate_parent-v6-0-f173239a4b59@oltmanns.dev/
https://lore.kernel.org/all/20241114065759.3341908-1-victor.liu@nxp.com/
https://lore.kernel.org/linux-clk/20241121-ge-ian-debug-imx8-clk-tree-v1-0-0f1b722588fe@bootlin.com/

We intend to fix these issues, but first we need to agree and document
what these shortcomings are. These patches are meant to do that, even
though some will be skipped as they are currently broken.

Changes since v2:
https://lore.kernel.org/linux-clk/20250528-clk-wip-v2-v2-0-0d2c2f220442@redhat.com/
- I left out my patches for changing the rate change propagation in
  the clk core so that parent rate changes are negotiated with all of
  it's children (and below). I will post a new version of that logic at
  a later time once I finish some more cleanups. The changes that are
  coming will make it so that the skipped tests in patch 4 of this
  series (div_div_2 and div_div_3) pass.
- Make divider clocks one based (Maxime)
- Text updates to clk_core kernel docs (Maxime)
- Convert from KUNIT_ASSERT_xx to KUNIT_EXPECT_xx (Maxime)
- Minor documentation updates to tests
- Drop rate constants and introduce clk_dummy_rate_mhz().

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
Brian Masney (9):
      clk: add kernel docs for struct clk_core
      clk: test: introduce clk_dummy_rate_mhz()
      clk: test: introduce clk_dummy_div for a mock divider
      clk: test: introduce test suite for sibling rate changes on a divider
      clk: test: introduce clk_dummy_gate for a mock gate
      clk: test: introduce test suite for sibling rate changes on a gate
      clk: test: introduce helper to create a mock mux
      clk: test: introduce test variation for sibling rate changes on a mux
      clk: test: introduce test variation for sibling rate changes on a gate/mux

 drivers/clk/clk.c      |  55 +++++
 drivers/clk/clk_test.c | 611 +++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 575 insertions(+), 91 deletions(-)
---
base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
change-id: 20250806-clk-tests-docs-3c398759e998

Best regards,
-- 
Brian Masney <bmasney@redhat.com>