Re: [PATCH v2 1/7] rust: types: rename ForLt to CovariantForLt

["Gary Guo" <gary@garyguo.net>]

On Wed Jun 3, 2026 at 2:10 AM BST, Danilo Krummrich wrote:
> Rename ForLt to CovariantForLt to prepare for the introduction of a new
> ForLt base trait that does not require covariance.
>
> The existing ForLt trait requires covariance, which enables the safe
> cast_ref() method. This rename preserves the same semantics under a more
> precise name, making room for a weaker ForLt trait in a subsequent
> commit.
>
> No functional change.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
>  drivers/gpu/nova-core/driver.rs       |  4 +-
>  rust/kernel/auxiliary.rs              | 23 +++++-----
>  rust/kernel/types.rs                  |  2 +-
>  rust/kernel/types/for_lt.rs           | 61 ++++++++++++++-------------
>  rust/macros/for_lt.rs                 |  4 +-
>  rust/macros/lib.rs                    | 11 +++--
>  samples/rust/rust_driver_auxiliary.rs |  8 ++--
>  7 files changed, 57 insertions(+), 56 deletions(-)
>
> diff --git a/rust/kernel/types/for_lt.rs b/rust/kernel/types/for_lt.rs
> index d44323c28e8d..ef510ab6c092 100644
> --- a/rust/kernel/types/for_lt.rs
> +++ b/rust/kernel/types/for_lt.rs
> @@ -1,8 +1,8 @@
>  // SPDX-License-Identifier: Apache-2.0 OR MIT
>  
> -//! Provide implementation and test of the `ForLt` trait and macro.
> +//! Provide implementation and test of the `CovariantForLt` trait and macro.
>  //!
> -//! This module is hidden and user should just use `ForLt!` directly.
> +//! This module is hidden and user should just use `CovariantForLt!` directly.
>  
>  use core::marker::PhantomData;
>  
> @@ -15,38 +15,39 @@
>  ///
>  /// # Macro
>  ///
> -/// It is not recommended to implement this trait directly. `ForLt!` macro is provided to obtain a
> -/// type that implements this trait.
> +/// It is not recommended to implement this trait directly. `CovariantForLt!` macro is provided to
> +/// obtain a type that implements this trait.
>  ///
>  /// The full syntax is
>  ///
>  /// ```
> -/// # use kernel::types::ForLt;
> -/// # fn expect_lt<F: ForLt>() {}
> +/// # use kernel::types::CovariantForLt;
> +/// # fn expect_lt<F: CovariantForLt>() {}
>  /// # struct TypeThatUse<'a>(&'a ());
>  /// # expect_lt::<
> -/// ForLt!(for<'a> TypeThatUse<'a>)
> +/// CovariantForLt!(for<'a> TypeThatUse<'a>)
>  /// # >();
>  /// ```
>  ///
> -/// which gives a type so that `<ForLt!(for<'a> TypeThatUse<'a>) as ForLt>::Of<'b>`
> +/// which gives a type so that
> +/// `<CovariantForLt!(for<'a> TypeThatUse<'a>) as CovariantForLt>::Of<'b>`
>  /// is `TypeThatUse<'b>`.
>  ///
>  /// You may also use a short-hand syntax which works similar to lifetime elision.
>  /// The macro also accepts types that do not involve a lifetime at all.
>  ///
>  /// ```
> -/// # use kernel::types::ForLt;
> -/// # fn expect_lt<F: ForLt>() {}
> +/// # use kernel::types::CovariantForLt;
> +/// # fn expect_lt<F: CovariantForLt>() {}
>  /// # struct TypeThatUse<'a>(&'a ());
>  /// # expect_lt::<
> -/// ForLt!(TypeThatUse<'_>) // Equivalent to `ForLt!(for<'a> TypeThatUse<'a>)`.
> +/// CovariantForLt!(TypeThatUse<'_>) // Equivalent to `CovariantForLt!(for<'a> TypeThatUse<'a>)`.
>  /// # >();
>  /// # expect_lt::<
> -/// ForLt!(&u32) // Equivalent to `ForLt!(for<'a> &'a u32)`.
> +/// CovariantForLt!(&u32) // Equivalent to `CovariantForLt!(for<'a> &'a u32)`.
>  /// # >();
>  /// # expect_lt::<
> -/// ForLt!(u32) // Equivalent to `ForLt!(for<'a> u32)`.
> +/// CovariantForLt!(u32) // Equivalent to `CovariantForLt!(for<'a> u32)`.
>  /// # >();
>  /// ```
>  ///
> @@ -55,10 +56,10 @@
>  /// it.
>  ///
>  /// ```ignore,compile_fail
> -/// # use kernel::types::ForLt;
> -/// # fn expect_lt<F: ForLt>() {}
> +/// # use kernel::types::CovariantForLt;
> +/// # fn expect_lt<F: CovariantForLt>() {}
>  /// # expect_lt::<
> -/// ForLt!(fn(&u32)) // Contravariant, will fail compilation.
> +/// CovariantForLt!(fn(&u32)) // Contravariant, will fail compilation.
>  /// # >();
>  /// ```
>  ///
> @@ -67,23 +68,23 @@
>  /// the generic parameter but is in a separate item.
>  ///
>  /// ```
> -/// # use kernel::types::ForLt;
> -/// fn expect_lt<F: ForLt>() {}
> +/// # use kernel::types::CovariantForLt;
> +/// fn expect_lt<F: CovariantForLt>() {}
>  /// # #[allow(clippy::unnecessary_safety_comment, reason = "false positive")]
>  /// fn generic_fn<T: 'static>() {
>  ///     // Syntactically proven by the macro
> -///     expect_lt::<ForLt!(&T)>();
> +///     expect_lt::<CovariantForLt!(&T)>();
>  ///     // Syntactically proven by the macro
> -///     expect_lt::<ForLt!(&KBox<T>)>();
> +///     expect_lt::<CovariantForLt!(&KBox<T>)>();
>  ///     // Cannot be syntactically proven, need to check covariance of `KBox`
> -///     // expect_lt::<ForLt!(&KBox<&T>)>();
> +///     // expect_lt::<CovariantForLt!(&KBox<&T>)>();
>  /// }
>  /// ```
>  ///
>  /// # Safety
>  ///
>  /// `Self::Of<'a>` must be covariant over the lifetime `'a`.
> -pub unsafe trait ForLt {
> +pub unsafe trait CovariantForLt {
>      /// The type parameterized by the lifetime.
>      type Of<'a>: 'a;
>  
> @@ -94,11 +95,11 @@ fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Sel
>          unsafe { core::mem::transmute(long) }
>      }
>  }
> -pub use macros::ForLt;
> +pub use macros::CovariantForLt;
>  
> -/// This is intended to be an "unsafe-to-refer-to" type.
> +/// Helper type for the `CovariantForLt!` macro.
>  ///
> -/// Must only be used by the `ForLt!` macro.
> +/// Must only be used by the `CovariantForLt!` macro.
>  ///
>  /// `T` is the magic `dyn for<'a> WithLt<'a, TypeThatUse<'a>>` generated by macro.
>  ///
> @@ -107,16 +108,16 @@ fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Sel
>  /// `N` is to provide the macro a place to emit arbitrary items, in case it needs to prove
>  /// additional properties.
>  #[doc(hidden)]
> -pub struct UnsafeForLtImpl<T: ?Sized, WF, const N: usize>(PhantomData<(WF, T)>);
> +pub struct CovariantForLtImpl<T: ?Sized, WF, const N: usize>(PhantomData<(WF, T)>);

I think I prefer this name to be stayed the same (so it has the "Unsafe" in it
and is not too long).

You can actually use this same helper type for both `ForLt!` and
`CovariantForLt!` later in patch 2, by using different `N` based on whether
covariance check has been conducted. So

impl<T: ?Sized + for<'a> WithLt<'a>, WF, const N: usize> ForLt for UnsafeForLtImpl<T, WF, N> {
    type Of<'a> = <T as WithLt<'a>>::Of;
}

impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for UnsafeForLtImpl<T, WF, 1> {}

Best,
Gary

>  
> -// This is a helper trait for implementation `ForLt` to be able to use HRTB.
> +// This is a helper trait for implementation `CovariantForLt` to be able to use HRTB.
>  #[doc(hidden)]
>  pub trait WithLt<'a> {
>      type Of: 'a;
>  }
>  
> -// SAFETY: In `ForLt!` macro, a covariance proof is generated when naming `UnsafeForLtImpl`
> -// and it will fail to evaluate if the type is not covariant.
> -unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> ForLt for UnsafeForLtImpl<T, WF, 0> {
> +// SAFETY: In `CovariantForLt!` macro, a covariance proof is generated when naming
> +// `CovariantForLtImpl` and it will fail to evaluate if the type is not covariant.
> +unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for CovariantForLtImpl<T, WF, 0> {
>      type Of<'a> = <T as WithLt<'a>>::Of;
>  }
> diff --git a/rust/macros/for_lt.rs b/rust/macros/for_lt.rs
> index 364d4113cd10..3cb094d00548 100644
> --- a/rust/macros/for_lt.rs
> +++ b/rust/macros/for_lt.rs
> @@ -176,7 +176,7 @@ fn prove(&mut self, ty: &'a Type) {
>      }
>  }
>  
> -pub(crate) fn for_lt(input: HigherRankedType) -> TokenStream {
> +pub(crate) fn covariant_for_lt(input: HigherRankedType) -> TokenStream {
>      let (ty, lifetime) = match input {
>          HigherRankedType::Explicit { lifetime, ty, .. } => (ty, lifetime),
>          HigherRankedType::Implicit { ty } => {
> @@ -235,7 +235,7 @@ fn #cov_proof_name<'__short, '__long: '__short>(
>      );
>  
>      quote!(
> -        ::kernel::types::for_lt::UnsafeForLtImpl::<
> +        ::kernel::types::for_lt::CovariantForLtImpl::<
>              dyn for<#lifetime> ::kernel::types::for_lt::WithLt<#lifetime, Of = #ty>,
>              #ty_static,
>              {
> diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
> index 4a48fabbc268..2167cb270928 100644
> --- a/rust/macros/lib.rs
> +++ b/rust/macros/lib.rs
> @@ -491,14 +491,13 @@ pub fn kunit_tests(attr: TokenStream, input: TokenStream) -> TokenStream {
>          .into()
>  }
>  
> -/// Obtain a type that implements [`ForLt`] for the given higher-ranked type.
> +/// Obtain a type that implements [`CovariantForLt`] for the given higher-ranked type.
>  ///
> -/// Please refer to the documentation of the [`ForLt`] trait.
> +/// Please refer to the documentation of the [`CovariantForLt`] trait.
>  ///
> -/// [`ForLt`]: trait.ForLt.html
> +/// [`CovariantForLt`]: trait.CovariantForLt.html
>  #[proc_macro]
> -// The macro shares the name with the trait.
>  #[allow(non_snake_case)]
> -pub fn ForLt(input: TokenStream) -> TokenStream {
> -    for_lt::for_lt(parse_macro_input!(input)).into()
> +pub fn CovariantForLt(input: TokenStream) -> TokenStream {
> +    for_lt::covariant_for_lt(parse_macro_input!(input)).into()
>  }
> diff --git a/samples/rust/rust_driver_auxiliary.rs b/samples/rust/rust_driver_auxiliary.rs
> index 2c1351040e45..92ee6a6d348e 100644
> --- a/samples/rust/rust_driver_auxiliary.rs
> +++ b/samples/rust/rust_driver_auxiliary.rs
> @@ -13,7 +13,7 @@
>      driver,
>      pci,
>      prelude::*,
> -    types::ForLt,
> +    types::CovariantForLt,
>      InPlaceModule, //
>  };
>  
> @@ -60,8 +60,8 @@ struct Data<'bound> {
>  
>  #[allow(clippy::type_complexity)]
>  struct ParentData<'bound> {
> -    _reg0: auxiliary::Registration<'bound, ForLt!(Data<'_>)>,
> -    _reg1: auxiliary::Registration<'bound, ForLt!(Data<'_>)>,
> +    _reg0: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
> +    _reg1: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
>  }
>  
>  kernel::pci_device_table!(
> @@ -115,7 +115,7 @@ fn probe<'bound>(
>  
>  impl ParentDriver {
>      fn connect(adev: &auxiliary::Device<Bound>) -> Result {
> -        let data = adev.registration_data::<ForLt!(Data<'_>)>()?;
> +        let data = adev.registration_data::<CovariantForLt!(Data<'_>)>()?;
>          let pdev = data.parent;
>  
>          dev_info!(