Clarify that implementers of `AlwaysReferenceCounted` must prevent the
implementer from being directly initialized by users.

It is a violation of the safety requirements of `AlwaysReferenceCounted` if
its implementers can be initialized on the stack by users. Although this
follows from the safety requirements, it is not immediately obvious.

The following example demonstrates the issue. Note that the safety
requirements for implementing `AlwaysRefCounted` and for calling
`ARef::from_raw` are satisfied.

  struct Empty {}

  unsafe impl AlwaysRefCounted for Empty {
      fn inc_ref(&self) {}
      unsafe fn dec_ref(_obj: NonNull<Self>) {}
  }

  fn unsound() -> ARef<Empty> {
      use core::ptr::NonNull;
      use kernel::types::{ARef, RefCounted};

      let mut data = Empty {};
      let ptr = NonNull::<Empty>::new(&mut data).unwrap();
      let aref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };

      aref
  }

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
Changes in v2:
- Express safety requirement in terms of ownership rather than
  initialization.
- Link to v1: https://lore.kernel.org/r/20250502-aref-from-raw-v1-1-eb0630626bba@kernel.org
---
 rust/kernel/types.rs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index 9d0471afc964..52683d686c8a 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
 /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
 /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
 /// alive.)
+///
+/// Implementers of this trait must ensure that values of types implementing this trait can never be
+/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
+/// that implements [`Deref`].
 pub unsafe trait AlwaysRefCounted {
     /// Increments the reference count on the object.
     fn inc_ref(&self);

---
base-commit: b4432656b36e5cc1d50a1f2dc15357543add530e
change-id: 20250502-aref-from-raw-e110b3e6dbf5

Best regards,
-- 
Andreas Hindborg <a.hindborg@kernel.org>

On Tue May 6, 2025 at 10:29 AM CEST, Andreas Hindborg wrote:
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index 9d0471afc964..52683d686c8a 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
>  /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
>  /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
>  /// alive.)
> +///
> +/// Implementers of this trait must ensure that values of types implementing this trait can never be
> +/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
> +/// that implements [`Deref`].

I don't think this covers every case, if I modify your example above
with Alice's suggestion and using `Box` instead of the stack, I get the
same problem:

    struct Empty {}
 
    unsafe impl AlwaysRefCounted for Empty {
        fn inc_ref(&self) {}
        unsafe fn dec_ref(_obj: NonNull<Self>) {}
    }
 
    fn unsound() -> ARef<Empty> {
        use kernel::types::{ARef, RefCounted};
 
        let data = Box::new(Empty {});
        let aref = ARef::from(&data);
 
        aref
    }

The same should be true if one uses `Arc` instead of `Box`. So, even
though we store it in a "pointer type that implements `Deref`", it is
unsound.

I think that types that implement `AlwaysRefCounted` must only be store
inside of `ARef<T>`. So something like "Values of this trait must only
be exposed as `ARef<Self>` or `&Self`." I'm not satisfied with the
wording 'exposed', maybe you have a better word or can expand the
sentence.

---
Cheers,
Benno

>  pub unsafe trait AlwaysRefCounted {
>      /// Increments the reference count on the object.
>      fn inc_ref(&self);
>
> ---
> base-commit: b4432656b36e5cc1d50a1f2dc15357543add530e
> change-id: 20250502-aref-from-raw-e110b3e6dbf5
>
> Best regards,

On Wed, May 07, 2025 at 10:35:16AM +0200, Benno Lossin wrote:
> On Tue May 6, 2025 at 10:29 AM CEST, Andreas Hindborg wrote:
> > diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> > index 9d0471afc964..52683d686c8a 100644
> > --- a/rust/kernel/types.rs
> > +++ b/rust/kernel/types.rs
> > @@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
> >  /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
> >  /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
> >  /// alive.)
> > +///
> > +/// Implementers of this trait must ensure that values of types implementing this trait can never be
> > +/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
> > +/// that implements [`Deref`].
> 
> I don't think this covers every case, if I modify your example above
> with Alice's suggestion and using `Box` instead of the stack, I get the
> same problem:
> 
>     struct Empty {}
>  
>     unsafe impl AlwaysRefCounted for Empty {
>         fn inc_ref(&self) {}
>         unsafe fn dec_ref(_obj: NonNull<Self>) {}
>     }
>  
>     fn unsound() -> ARef<Empty> {
>         use kernel::types::{ARef, RefCounted};
>  
>         let data = Box::new(Empty {});
>         let aref = ARef::from(&data);
>  
>         aref
>     }
> 
> The same should be true if one uses `Arc` instead of `Box`. So, even
> though we store it in a "pointer type that implements `Deref`", it is
> unsound.
> 
> I think that types that implement `AlwaysRefCounted` must only be store
> inside of `ARef<T>`. So something like "Values of this trait must only
> be exposed as `ARef<Self>` or `&Self`." I'm not satisfied with the
> wording 'exposed', maybe you have a better word or can expand the
> sentence.

I mean, in some sense the problem is that Empty violates the existing
requirement:

Implementers must also ensure that all instances are reference-counted.
(Otherwise they won't be able to honour the requirement that
[`AlwaysRefCounted::inc_ref`] keep the object alive.)

Alice

"Alice Ryhl" <aliceryhl@google.com> writes:

> On Wed, May 07, 2025 at 10:35:16AM +0200, Benno Lossin wrote:
>> On Tue May 6, 2025 at 10:29 AM CEST, Andreas Hindborg wrote:
>> > diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
>> > index 9d0471afc964..52683d686c8a 100644
>> > --- a/rust/kernel/types.rs
>> > +++ b/rust/kernel/types.rs
>> > @@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
>> >  /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
>> >  /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
>> >  /// alive.)
>> > +///
>> > +/// Implementers of this trait must ensure that values of types implementing this trait can never be
>> > +/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
>> > +/// that implements [`Deref`].
>>
>> I don't think this covers every case, if I modify your example above
>> with Alice's suggestion and using `Box` instead of the stack, I get the
>> same problem:
>>
>>     struct Empty {}
>>
>>     unsafe impl AlwaysRefCounted for Empty {
>>         fn inc_ref(&self) {}
>>         unsafe fn dec_ref(_obj: NonNull<Self>) {}
>>     }
>>
>>     fn unsound() -> ARef<Empty> {
>>         use kernel::types::{ARef, RefCounted};
>>
>>         let data = Box::new(Empty {});
>>         let aref = ARef::from(&data);
>>
>>         aref
>>     }
>>
>> The same should be true if one uses `Arc` instead of `Box`. So, even
>> though we store it in a "pointer type that implements `Deref`", it is
>> unsound.
>>
>> I think that types that implement `AlwaysRefCounted` must only be store
>> inside of `ARef<T>`. So something like "Values of this trait must only
>> be exposed as `ARef<Self>` or `&Self`." I'm not satisfied with the
>> wording 'exposed', maybe you have a better word or can expand the
>> sentence.
>
> I mean, in some sense the problem is that Empty violates the existing
> requirement:
>
> Implementers must also ensure that all instances are reference-counted.
> (Otherwise they won't be able to honour the requirement that
> [`AlwaysRefCounted::inc_ref`] keep the object alive.)

The example holds, even if you implement `inc_ref`/`dec_ref` properly,
right?


Best regards,
Andreas Hindborg

On Wed May 7, 2025 at 11:19 AM CEST, Andreas Hindborg wrote:
> "Alice Ryhl" <aliceryhl@google.com> writes:
>> On Wed, May 07, 2025 at 10:35:16AM +0200, Benno Lossin wrote:
>>> On Tue May 6, 2025 at 10:29 AM CEST, Andreas Hindborg wrote:
>>> > diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
>>> > index 9d0471afc964..52683d686c8a 100644
>>> > --- a/rust/kernel/types.rs
>>> > +++ b/rust/kernel/types.rs
>>> > @@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
>>> >  /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
>>> >  /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
>>> >  /// alive.)
>>> > +///
>>> > +/// Implementers of this trait must ensure that values of types implementing this trait can never be
>>> > +/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
>>> > +/// that implements [`Deref`].
>>>
>>> I don't think this covers every case, if I modify your example above
>>> with Alice's suggestion and using `Box` instead of the stack, I get the
>>> same problem:
>>>
>>>     struct Empty {}
>>>
>>>     unsafe impl AlwaysRefCounted for Empty {
>>>         fn inc_ref(&self) {}
>>>         unsafe fn dec_ref(_obj: NonNull<Self>) {}
>>>     }
>>>
>>>     fn unsound() -> ARef<Empty> {
>>>         use kernel::types::{ARef, RefCounted};
>>>
>>>         let data = Box::new(Empty {});
>>>         let aref = ARef::from(&data);
>>>
>>>         aref
>>>     }
>>>
>>> The same should be true if one uses `Arc` instead of `Box`. So, even
>>> though we store it in a "pointer type that implements `Deref`", it is
>>> unsound.
>>>
>>> I think that types that implement `AlwaysRefCounted` must only be store
>>> inside of `ARef<T>`. So something like "Values of this trait must only
>>> be exposed as `ARef<Self>` or `&Self`." I'm not satisfied with the
>>> wording 'exposed', maybe you have a better word or can expand the
>>> sentence.
>>
>> I mean, in some sense the problem is that Empty violates the existing
>> requirement:
>>
>> Implementers must also ensure that all instances are reference-counted.
>> (Otherwise they won't be able to honour the requirement that
>> [`AlwaysRefCounted::inc_ref`] keep the object alive.)
>
> The example holds, even if you implement `inc_ref`/`dec_ref` properly,
> right?

Yes.

Although one could interpret the part that Alice quoted above to mean
the same thing as I suggested (only giving access to `ARef<Self>`, as
any other smart pointer isn't aware of the inner refcounting of the
value).

With that interpretation, we could argue that there is nothing wrong
with the safety requirements. But I'd say that we should definitely
mention that one is only allowed to use `ARef<Self>`/`&Self` and not
hand out any other ways to access `Self`.

---
Cheers,
Benno

On Tue, May 06, 2025 at 10:29:02AM +0200, Andreas Hindborg wrote:
> Clarify that implementers of `AlwaysReferenceCounted` must prevent the
> implementer from being directly initialized by users.
> 
> It is a violation of the safety requirements of `AlwaysReferenceCounted` if
> its implementers can be initialized on the stack by users. Although this
> follows from the safety requirements, it is not immediately obvious.
> 
> The following example demonstrates the issue. Note that the safety
> requirements for implementing `AlwaysRefCounted` and for calling
> `ARef::from_raw` are satisfied.
> 
>   struct Empty {}
> 
>   unsafe impl AlwaysRefCounted for Empty {
>       fn inc_ref(&self) {}
>       unsafe fn dec_ref(_obj: NonNull<Self>) {}
>   }
> 
>   fn unsound() -> ARef<Empty> {
>       use core::ptr::NonNull;
>       use kernel::types::{ARef, RefCounted};
> 
>       let mut data = Empty {};
>       let ptr = NonNull::<Empty>::new(&mut data).unwrap();
>       let aref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };
> 

Hmm.. I would say in this case, what gets violated is the safe
requirement of ARef::from_raw(), because callers are supposed to
guarantee that an refcount increment was passed to `ARef` and in this
case, and unsound() cannot guarantee that here because it's going to
clean up `data` when the it returns.

Regards,
Boqun

>       aref
>   }
> 
> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
> ---
> Changes in v2:
> - Express safety requirement in terms of ownership rather than
>   initialization.
> - Link to v1: https://lore.kernel.org/r/20250502-aref-from-raw-v1-1-eb0630626bba@kernel.org
> ---
>  rust/kernel/types.rs | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index 9d0471afc964..52683d686c8a 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -409,6 +409,10 @@ pub const fn raw_get(this: *const Self) -> *mut T {
>  /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
>  /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
>  /// alive.)
> +///
> +/// Implementers of this trait must ensure that values of types implementing this trait can never be
> +/// owned by value. Instead, values must be owned and used through a pointer type. That is, a type
> +/// that implements [`Deref`].
>  pub unsafe trait AlwaysRefCounted {
>      /// Increments the reference count on the object.
>      fn inc_ref(&self);
> 
> ---
> base-commit: b4432656b36e5cc1d50a1f2dc15357543add530e
> change-id: 20250502-aref-from-raw-e110b3e6dbf5
> 
> Best regards,
> -- 
> Andreas Hindborg <a.hindborg@kernel.org>
> 
>

On Tue, May 06, 2025 at 07:10:43AM -0700, Boqun Feng wrote:
> On Tue, May 06, 2025 at 10:29:02AM +0200, Andreas Hindborg wrote:
> > Clarify that implementers of `AlwaysReferenceCounted` must prevent the
> > implementer from being directly initialized by users.
> > 
> > It is a violation of the safety requirements of `AlwaysReferenceCounted` if
> > its implementers can be initialized on the stack by users. Although this
> > follows from the safety requirements, it is not immediately obvious.
> > 
> > The following example demonstrates the issue. Note that the safety
> > requirements for implementing `AlwaysRefCounted` and for calling
> > `ARef::from_raw` are satisfied.
> > 
> >   struct Empty {}
> > 
> >   unsafe impl AlwaysRefCounted for Empty {
> >       fn inc_ref(&self) {}
> >       unsafe fn dec_ref(_obj: NonNull<Self>) {}
> >   }
> > 
> >   fn unsound() -> ARef<Empty> {
> >       use core::ptr::NonNull;
> >       use kernel::types::{ARef, RefCounted};
> > 
> >       let mut data = Empty {};
> >       let ptr = NonNull::<Empty>::new(&mut data).unwrap();
> >       let aref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };
> > 
> 
> Hmm.. I would say in this case, what gets violated is the safe
> requirement of ARef::from_raw(), because callers are supposed to
> guarantee that an refcount increment was passed to `ARef` and in this
> case, and unsound() cannot guarantee that here because it's going to
> clean up `data` when the it returns.

You can change the example to go through `impl From<&T> for ARef<T>`,
and then you have the same situation without this unsafe op.

Alice

"Boqun Feng" <boqun.feng@gmail.com> writes:

> On Tue, May 06, 2025 at 10:29:02AM +0200, Andreas Hindborg wrote:
>> Clarify that implementers of `AlwaysReferenceCounted` must prevent the
>> implementer from being directly initialized by users.
>>
>> It is a violation of the safety requirements of `AlwaysReferenceCounted` if
>> its implementers can be initialized on the stack by users. Although this
>> follows from the safety requirements, it is not immediately obvious.
>>
>> The following example demonstrates the issue. Note that the safety
>> requirements for implementing `AlwaysRefCounted` and for calling
>> `ARef::from_raw` are satisfied.
>>
>>   struct Empty {}
>>
>>   unsafe impl AlwaysRefCounted for Empty {
>>       fn inc_ref(&self) {}
>>       unsafe fn dec_ref(_obj: NonNull<Self>) {}
>>   }
>>
>>   fn unsound() -> ARef<Empty> {
>>       use core::ptr::NonNull;
>>       use kernel::types::{ARef, RefCounted};
>>
>>       let mut data = Empty {};
>>       let ptr = NonNull::<Empty>::new(&mut data).unwrap();
>>       let aref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };
>>
>
> Hmm.. I would say in this case, what gets violated is the safe
> requirement of ARef::from_raw(), because callers are supposed to
> guarantee that an refcount increment was passed to `ARef` and in this
> case, and unsound() cannot guarantee that here because it's going to
> clean up `data` when the it returns.

Right, `unsound` is not following this part of the safety requirement:

  and that they are properly relinquishing one increment ...
  callers must not use the underlying object anymore

Freeing the object by returning is using the object.

So maybe we don't need to change anything, we can just fix up the
example for `ARef::into_raw`.


Best regards,
Andreas Hindborg