By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically
C FFI) type that *may* be owned by Rust, but need not be. Unlike
AlwaysRefCounted, this mechanism expects the reference to be unique
within Rust, and does not allow cloning.

Conceptually, this is similar to a KBox<T>, except that it delegates
resource management to the T instead of using a generic allocator.

Signed-off-by: Asahi Lina <lina@asahilina.net>
---
 rust/kernel/types.rs | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index ec6457bb3084ae327c38ba4ba79b1601aef38244..0bee56153dcea47fb1321162df6b8765b5436e9f 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -479,6 +479,116 @@ fn drop(&mut self) {
     }
 }
 
+/// Types that may be owned by Rust code or borrowed, but have a lifetime managed by C code.
+///
+/// It allows such types to define their own custom destructor function to be called when
+/// a Rust-owned reference is dropped.
+///
+/// This is usually implemented by wrappers to existing structures on the C side of the code.
+///
+/// # Safety
+///
+/// Implementers must ensure that any objects borrowed directly as `&T` stay alive for the duration
+/// of the lifetime, and that any objects owned by Rust as `Owned<T>`) stay alive while that owned
+/// reference exists, until the [`Ownable::release()`] trait method is called.
+pub unsafe trait Ownable {
+    /// Releases the object (frees it or returns it to foreign ownership).
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the object is no longer referenced after this call.
+    unsafe fn release(this: NonNull<Self>);
+}
+
+/// A subtrait of Ownable that asserts that an `Owned<T>` Rust reference is not only unique
+/// within Rust and keeps the `T` alive, but also guarantees that the C code follows the
+/// usual mutable reference requirements. That is, the kernel will never mutate the
+/// `T` (excluding internal mutability that follows the usual rules) while Rust owns it.
+///
+/// When this type is implemented for an [`Ownable`] type, it allows `Owned<T>` to be
+/// dereferenced into a &mut T.
+///
+/// # Safety
+///
+/// Implementers must ensure that the kernel never mutates the underlying type while
+/// Rust owns it.
+pub unsafe trait OwnableMut: Ownable {}
+
+/// An owned reference to an ownable kernel object.
+///
+/// The object is automatically freed or released when an instance of [`Owned`] is
+/// dropped.
+///
+/// # Invariants
+///
+/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`Owned`] instance.
+pub struct Owned<T: Ownable> {
+    ptr: NonNull<T>,
+    _p: PhantomData<T>,
+}
+
+// SAFETY: It is safe to send `Owned<T>` to another thread when the underlying `T` is `Send` because
+// it effectively means sending a unique `&mut T` pointer (which is safe because `T` is `Send`).
+unsafe impl<T: Ownable + Send> Send for Owned<T> {}
+
+// SAFETY: It is safe to send `&Owned<T>` to another thread when the underlying `T` is `Sync`
+// because it effectively means sharing `&T` (which is safe because `T` is `Sync`).
+unsafe impl<T: Ownable + Sync> Sync for Owned<T> {}
+
+impl<T: Ownable> Owned<T> {
+    /// Creates a new instance of [`Owned`].
+    ///
+    /// It takes over ownership of the underlying object.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the underlying object is acquired and can be considered owned by
+    /// Rust.
+    pub(crate) unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+        // INVARIANT: The safety requirements guarantee that the new instance now owns the
+        // reference.
+        Self {
+            ptr,
+            _p: PhantomData,
+        }
+    }
+
+    /// Consumes the `Owned`, returning a raw pointer.
+    ///
+    /// This function does not actually relinquish ownership of the object.
+    /// After calling this function, the caller is responsible for ownership previously managed
+    /// by the `Owned`.
+    #[allow(dead_code)]
+    pub(crate) fn into_raw(me: Self) -> NonNull<T> {
+        ManuallyDrop::new(me).ptr
+    }
+}
+
+impl<T: Ownable> Deref for Owned<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The type invariants guarantee that the object is valid.
+        unsafe { self.ptr.as_ref() }
+    }
+}
+
+impl<T: Ownable + OwnableMut> DerefMut for Owned<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        // SAFETY: The type invariants guarantee that the object is valid,
+        // and that we can safely return a mutable reference to it.
+        unsafe { self.ptr.as_mut() }
+    }
+}
+
+impl<T: Ownable> Drop for Owned<T> {
+    fn drop(&mut self) {
+        // SAFETY: The type invariants guarantee that the `Owned` owns the object we're about to
+        // release.
+        unsafe { T::release(self.ptr) };
+    }
+}
+
 /// A sum type that always holds either a value of type `L` or `R`.
 ///
 /// # Examples

-- 
2.47.1

"Asahi Lina" <lina@asahilina.net> writes:

> By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically
> C FFI) type that *may* be owned by Rust, but need not be. Unlike
> AlwaysRefCounted, this mechanism expects the reference to be unique
> within Rust, and does not allow cloning.
>
> Conceptually, this is similar to a KBox<T>, except that it delegates
> resource management to the T instead of using a generic allocator.
>
> Signed-off-by: Asahi Lina <lina@asahilina.net>

Over all looks good to me - I agree with the points already discussed.

Could you put it in a separate module and file? `kernel::types::ownable`
and then `pub use` in `types.rs`. `types.rs` is getting quite busy.


Best regards,
Andreas Hindborg

On Sun, Feb 2, 2025 at 2:06 PM Asahi Lina <lina@asahilina.net> wrote:
>
> By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically
> C FFI) type that *may* be owned by Rust, but need not be. Unlike
> AlwaysRefCounted, this mechanism expects the reference to be unique
> within Rust, and does not allow cloning.
>
> Conceptually, this is similar to a KBox<T>, except that it delegates
> resource management to the T instead of using a generic allocator.
>
> Signed-off-by: Asahi Lina <lina@asahilina.net>

Overall LGTM.

> +/// A subtrait of Ownable that asserts that an `Owned<T>` Rust reference is not only unique
> +/// within Rust and keeps the `T` alive, but also guarantees that the C code follows the
> +/// usual mutable reference requirements. That is, the kernel will never mutate the
> +/// `T` (excluding internal mutability that follows the usual rules) while Rust owns it.
> +///
> +/// When this type is implemented for an [`Ownable`] type, it allows `Owned<T>` to be
> +/// dereferenced into a &mut T.
> +///
> +/// # Safety
> +///
> +/// Implementers must ensure that the kernel never mutates the underlying type while
> +/// Rust owns it.
> +pub unsafe trait OwnableMut: Ownable {}

Giving out mutable references allows users to call core::mem::swap on
the object. We must require that this is allowed.

> +impl<T: Ownable> Owned<T> {
> +    /// Creates a new instance of [`Owned`].
> +    ///
> +    /// It takes over ownership of the underlying object.
> +    ///
> +    /// # Safety
> +    ///
> +    /// Callers must ensure that the underlying object is acquired and can be considered owned by
> +    /// Rust.
> +    pub(crate) unsafe fn from_raw(ptr: NonNull<T>) -> Self {
> +        // INVARIANT: The safety requirements guarantee that the new instance now owns the
> +        // reference.
> +        Self {
> +            ptr,
> +            _p: PhantomData,
> +        }
> +    }
> +
> +    /// Consumes the `Owned`, returning a raw pointer.
> +    ///
> +    /// This function does not actually relinquish ownership of the object.
> +    /// After calling this function, the caller is responsible for ownership previously managed
> +    /// by the `Owned`.
> +    #[allow(dead_code)]
> +    pub(crate) fn into_raw(me: Self) -> NonNull<T> {

I would just make these methods public, like the ARef ones. Then you
can drop the #[allow(dead_code)] annotation.

Alice

On 2/3/25 6:13 PM, Alice Ryhl wrote:
> On Sun, Feb 2, 2025 at 2:06 PM Asahi Lina <lina@asahilina.net> wrote:
>>
>> By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically
>> C FFI) type that *may* be owned by Rust, but need not be. Unlike
>> AlwaysRefCounted, this mechanism expects the reference to be unique
>> within Rust, and does not allow cloning.
>>
>> Conceptually, this is similar to a KBox<T>, except that it delegates
>> resource management to the T instead of using a generic allocator.
>>
>> Signed-off-by: Asahi Lina <lina@asahilina.net>
> 
> Overall LGTM.
> 
>> +/// A subtrait of Ownable that asserts that an `Owned<T>` Rust reference is not only unique
>> +/// within Rust and keeps the `T` alive, but also guarantees that the C code follows the
>> +/// usual mutable reference requirements. That is, the kernel will never mutate the
>> +/// `T` (excluding internal mutability that follows the usual rules) while Rust owns it.
>> +///
>> +/// When this type is implemented for an [`Ownable`] type, it allows `Owned<T>` to be
>> +/// dereferenced into a &mut T.
>> +///
>> +/// # Safety
>> +///
>> +/// Implementers must ensure that the kernel never mutates the underlying type while
>> +/// Rust owns it.
>> +pub unsafe trait OwnableMut: Ownable {}
> 
> Giving out mutable references allows users to call core::mem::swap on
> the object. We must require that this is allowed.

Hmm, yeah. I don't use this yet, and I'm not sure if it makes much sense
with that caveat. I'll drop it for v2.

> 
>> +impl<T: Ownable> Owned<T> {
>> +    /// Creates a new instance of [`Owned`].
>> +    ///
>> +    /// It takes over ownership of the underlying object.
>> +    ///
>> +    /// # Safety
>> +    ///
>> +    /// Callers must ensure that the underlying object is acquired and can be considered owned by
>> +    /// Rust.
>> +    pub(crate) unsafe fn from_raw(ptr: NonNull<T>) -> Self {
>> +        // INVARIANT: The safety requirements guarantee that the new instance now owns the
>> +        // reference.
>> +        Self {
>> +            ptr,
>> +            _p: PhantomData,
>> +        }
>> +    }
>> +
>> +    /// Consumes the `Owned`, returning a raw pointer.
>> +    ///
>> +    /// This function does not actually relinquish ownership of the object.
>> +    /// After calling this function, the caller is responsible for ownership previously managed
>> +    /// by the `Owned`.
>> +    #[allow(dead_code)]
>> +    pub(crate) fn into_raw(me: Self) -> NonNull<T> {
> 
> I would just make these methods public, like the ARef ones. Then you
> can drop the #[allow(dead_code)] annotation.

Does it make sense to ever have drivers doing this? I feel like these
methods should be limited to the kernel crate.

~~ Lina

On Mon, Feb 3, 2025 at 3:17 PM Asahi Lina <lina@asahilina.net> wrote:
>
>
>
> On 2/3/25 6:13 PM, Alice Ryhl wrote:
> > On Sun, Feb 2, 2025 at 2:06 PM Asahi Lina <lina@asahilina.net> wrote:
> >> +    /// Consumes the `Owned`, returning a raw pointer.
> >> +    ///
> >> +    /// This function does not actually relinquish ownership of the object.
> >> +    /// After calling this function, the caller is responsible for ownership previously managed
> >> +    /// by the `Owned`.
> >> +    #[allow(dead_code)]
> >> +    pub(crate) fn into_raw(me: Self) -> NonNull<T> {
> >
> > I would just make these methods public, like the ARef ones. Then you
> > can drop the #[allow(dead_code)] annotation.
>
> Does it make sense to ever have drivers doing this? I feel like these
> methods should be limited to the kernel crate.

Not having drivers use this is the ideal, but I don't think we should
always expect it to be possible. The Binder driver has a C component
for the binderfs component, and it also has some code that's
essentially an abstraction inside the driver that I was asked to move
into Binder because it's so specific to Binder that it's not useful
for anyone else.

Alice

On 2/4/25 3:17 AM, Alice Ryhl wrote:
> On Mon, Feb 3, 2025 at 3:17 PM Asahi Lina <lina@asahilina.net> wrote:
>>
>>
>>
>> On 2/3/25 6:13 PM, Alice Ryhl wrote:
>>> On Sun, Feb 2, 2025 at 2:06 PM Asahi Lina <lina@asahilina.net> wrote:
>>>> +    /// Consumes the `Owned`, returning a raw pointer.
>>>> +    ///
>>>> +    /// This function does not actually relinquish ownership of the object.
>>>> +    /// After calling this function, the caller is responsible for ownership previously managed
>>>> +    /// by the `Owned`.
>>>> +    #[allow(dead_code)]
>>>> +    pub(crate) fn into_raw(me: Self) -> NonNull<T> {
>>>
>>> I would just make these methods public, like the ARef ones. Then you
>>> can drop the #[allow(dead_code)] annotation.
>>
>> Does it make sense to ever have drivers doing this? I feel like these
>> methods should be limited to the kernel crate.
> 
> Not having drivers use this is the ideal, but I don't think we should
> always expect it to be possible. The Binder driver has a C component
> for the binderfs component, and it also has some code that's
> essentially an abstraction inside the driver that I was asked to move
> into Binder because it's so specific to Binder that it's not useful
> for anyone else.

That's fair, I'll make it pub.

~~ Lina

"Asahi Lina" <lina@asahilina.net> writes:

> On 2/4/25 3:17 AM, Alice Ryhl wrote:
>> On Mon, Feb 3, 2025 at 3:17 PM Asahi Lina <lina@asahilina.net> wrote:
>>>
>>>
>>>
>>> On 2/3/25 6:13 PM, Alice Ryhl wrote:
>>>> On Sun, Feb 2, 2025 at 2:06 PM Asahi Lina <lina@asahilina.net> wrote:
>>>>> +    /// Consumes the `Owned`, returning a raw pointer.
>>>>> +    ///
>>>>> +    /// This function does not actually relinquish ownership of the object.
>>>>> +    /// After calling this function, the caller is responsible for ownership previously managed
>>>>> +    /// by the `Owned`.
>>>>> +    #[allow(dead_code)]
>>>>> +    pub(crate) fn into_raw(me: Self) -> NonNull<T> {
>>>>
>>>> I would just make these methods public, like the ARef ones. Then you
>>>> can drop the #[allow(dead_code)] annotation.
>>>
>>> Does it make sense to ever have drivers doing this? I feel like these
>>> methods should be limited to the kernel crate.
>>
>> Not having drivers use this is the ideal, but I don't think we should
>> always expect it to be possible. The Binder driver has a C component
>> for the binderfs component, and it also has some code that's
>> essentially an abstraction inside the driver that I was asked to move
>> into Binder because it's so specific to Binder that it's not useful
>> for anyone else.
>
> That's fair, I'll make it pub.

Also, the kernel crate will split at some point. We might as well have
them public now and avoid the churn.


Best regards,
Andreas Hindborg