[PATCH v4 0/3] Clk improvements

[Daniel Almeida]

This series contains a few improvements that simplifies clock handling for
drivers.

Patch 1 implements the same typestate pattern that has been used
successfully for Regulators. This is needed because otherwise drivers
will be responsible for unpreparing and disabling clocks themselves and
ultimately handling the reference counts on their own. This is
undesirable. The patch automatically encodes this information using the
type system so that no misuse can occur.

Patch 2 makes things more convenient by offering devres-managed APIs. This
lets drivers set clock parameters once and forget about lifetime
management.

Patch 3 converts clk.rs to the newer kernel-vertical style in order to make
future changes easier.

Alice Ryhl's "rust: clk: implement Send and Sync" series, which this used to
depend on, has since been merged, so this series now applies directly on
clk-next.

---
Changes in v4:
- Rebased onto clk-next. Alice Ryhl's "rust: clk: implement Send and Sync"
  series is now merged upstream, so it is no longer carried as a dependency.
- Fixed the build with CONFIG_CPUFREQ_DT_RUST=y. The generic DT cpufreq
  driver only has the (unbound) per-CPU device, so it cannot hand a
  &Device<Bound> to Policy::set_clk(). Added a pub(crate) Clk::get_unbound()
  for the few in-tree abstractions that operate on a device outside a bind
  scope; set_clk() now takes &Device and uses it. Clk::get()/get_optional()
  and the devm_* helpers still require &Device<Bound>.
- Added impl From<Error<State>> for kernel::error::Error, so the fallible
  state transitions can be used with `?` (and chained) instead of
  .map_err(|e| e.error).
- Added Clk::<Prepared>::with_enabled(), which runs a closure with the clock
  temporarily enabled, scoping the Enabled state without giving up the
  prepared clock.
- Documented how to change a clock's state at runtime via an enum, for
  drivers that enable/disable across resume/suspend.
- Link to v3: https://lore.kernel.org/r/20260107-clk-type-state-v3-0-77d3e3ee59c2@collabora.com

Changes in v3:
- Rebased on top of 6.19-rc4
- Dropped patch 1 (from Alice), added her series as a dependency instead
- Fixed Tyr, PWM_TH1520 drivers
- Changed clk.rs imports to kernel-vertical style
- Added support get_optional shortcut for Prepared and Enabled (i.e.:
  Clk::<Enabled>::get_optional())
- Fixed misplaced #[inline] tag

Thanks, Danilo {
  - Moved the devres changes into its own patch
  - Require &Device<Bound> for all functions where a &Device is used
  - Account for con_in in SAFETY comments where applicable
  - Added backticks
}

- Link to v2: https://lore.kernel.org/r/20250910-clk-type-state-v2-0-1b97c11bb631@collabora.com

Changes in v2:
- Added Alice's patch as patch 1, since it is a dependency.
- Added devm helpers (like we did for Regulator<T>)
- Fixed missing clk_put() call in Drop (Danilo)
- Fixed missing parenthesis and wrong docs (Viresh)
- Removed extra "dev" parameter from "shutdown" example (Danilo)
- Removed useless type annotation from example (Danilo)
- Link to v1: https://lore.kernel.org/rust-for-linux/20250729-clk-type-state-v1-1-896b53816f7b@collabora.com/#r

To: "Rafael J. Wysocki" <rafael at kernel.org>
To: Viresh Kumar <viresh.kumar at linaro.org>
To: Danilo Krummrich <dakr at kernel.org>
To: Alice Ryhl <aliceryhl at google.com>
To: Daniel Almeida <daniel.almeida at collabora.com>
To: David Airlie <airlied at gmail.com>
To: Simona Vetter <simona at ffwll.ch>
To: Drew Fustini <fustini at kernel.org>
To: Guo Ren <guoren at kernel.org>
To: Fu Wei <wefu at redhat.com>
To: Michal Wilczynski <m.wilczynski at samsung.com>
To: Uwe Kleine-König <ukleinek at kernel.org>
To: Michael Turquette <mturquette at baylibre.com>
To: Stephen Boyd <sboyd at kernel.org>
To: Brian Masney <bmasney at redhat.com>
To: Miguel Ojeda <ojeda at kernel.org>
To: Boqun Feng <boqun at kernel.org>
To: Gary Guo <gary at garyguo.net>
To: Björn Roy Baron <bjorn3_gh at protonmail.com>
To: Benno Lossin <lossin at kernel.org>
To: Andreas Hindborg <a.hindborg at kernel.org>
To: Trevor Gross <tmgross at umich.edu>
Cc: linux-pm at vger.kernel.org
Cc: linux-kernel at vger.kernel.org
Cc: dri-devel at lists.freedesktop.org
Cc: linux-riscv at lists.infradead.org
Cc: linux-pwm at vger.kernel.org
Cc: linux-clk at vger.kernel.org
Cc: rust-for-linux at vger.kernel.org
Cc: Boris Brezillon <boris.brezillon at collabora.com>

---
Daniel Almeida (3):
      rust: clk: use the type-state pattern
      rust: clk: add devres-managed clks
      rust: clk: use 'kernel vertical style' for imports

 drivers/cpufreq/rcpufreq_dt.rs |   2 +-
 drivers/gpu/drm/tyr/driver.rs  |  31 +--
 drivers/pwm/pwm_th1520.rs      |  17 +-
 rust/kernel/clk.rs             | 595 +++++++++++++++++++++++++++++++----------
 rust/kernel/cpufreq.rs         |   8 +-
 5 files changed, 477 insertions(+), 176 deletions(-)
---
base-commit: 8d03cc42a42b1a3f1535757f65bfb74a9753953f
change-id: 20250909-clk-type-state-c01aa7dd551d

Best regards,
--  
Daniel Almeida <daniel.almeida at collabora.com>