[PATCH] rust: miscdevice: clarify invariant for `MiscDeviceRegistration`

[PATCH] rust: miscdevice: clarify invariant for `MiscDeviceRegistration`

[Shankari Anand]

Reword and expand the invariant documentation for `MiscDeviceRegistration`
to clarify what it means for the inner device to be "registered".
It expands to explain:
- `inner` points to a `miscdevice` registered via `misc_register`.
- This registration stays valid for the entire lifetime of the object.
- Deregistration is guaranteed on `Drop`, via `misc_deregister`.

Reported-by: Benno Lossin <lossin@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1168
Fixes: f893691e7426 ("rust: miscdevice: add base miscdevice abstraction")
Signed-off-by: Shankari Anand <shankari.ak0208@gmail.com>
---
 rust/kernel/miscdevice.rs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/miscdevice.rs b/rust/kernel/miscdevice.rs
index 939278bc7b03..5df98dce019a 100644
--- a/rust/kernel/miscdevice.rs
+++ b/rust/kernel/miscdevice.rs
@@ -45,7 +45,15 @@ pub const fn into_raw<T: MiscDevice>(self) -> bindings::miscdevice {
 ///
 /// # Invariants
 ///
-/// `inner` is a registered misc device.
+/// The `inner` field contains a `struct miscdevice` that has been registered with
+/// the kernel using `misc_register()`.
+/// This registration remains valid for the entire lifetime of the `MiscDeviceRegistration`
+/// instance.
+/// Deregistration is guaranteed to occur exactly once, during the [`Drop`] implementation, via
+/// a call to `misc_deregister()`.
+/// The `inner` pointer is never null and always points to a valid, pinned `miscdevice` instance
+/// initialized via `MiscDeviceOptions::into_raw`.
+
 #[repr(transparent)]
 #[pin_data(PinnedDrop)]
 pub struct MiscDeviceRegistration<T> {
-- 
2.34.1

Re: [PATCH] rust: miscdevice: clarify invariant for `MiscDeviceRegistration`

[Miguel Ojeda]

On Sun, Jun 22, 2025 at 1:07 PM Shankari Anand
<shankari.ak0208@gmail.com> wrote:
>
> Reword and expand the invariant documentation for `MiscDeviceRegistration`
> to clarify what it means for the inner device to be "registered".
> It expands to explain:
> - `inner` points to a `miscdevice` registered via `misc_register`.
> - This registration stays valid for the entire lifetime of the object.
> - Deregistration is guaranteed on `Drop`, via `misc_deregister`.
>
> Reported-by: Benno Lossin <lossin@kernel.org>
> Closes: https://github.com/Rust-for-Linux/linux/issues/1168
> Fixes: f893691e7426 ("rust: miscdevice: add base miscdevice abstraction")
> Signed-off-by: Shankari Anand <shankari.ak0208@gmail.com>

Cc'ing Danilo and Greg.

> +/// The `inner` field contains a `struct miscdevice` that has been registered with
> +/// the kernel using `misc_register()`.
> +/// This registration remains valid for the entire lifetime of the `MiscDeviceRegistration`
> +/// instance.
> +/// Deregistration is guaranteed to occur exactly once, during the [`Drop`] implementation, via
> +/// a call to `misc_deregister()`.
> +/// The `inner` pointer is never null and always points to a valid, pinned `miscdevice` instance
> +/// initialized via `MiscDeviceOptions::into_raw`.

These should be bullet points -- like this it will be rendered like a
single long paragraph (but please wait for other feedback before
fixing that).

The last one seems wrong -- `inner` is not a pointer. It should also
probably be simplified/merged with the first one.

Also, please use intra-doc links wherever possible, e.g.
[`MiscDeviceRegistration`] and for `into_raw` too.

Thanks for the patch!

Cheers,
Miguel

Re: [PATCH] rust: miscdevice: clarify invariant for `MiscDeviceRegistration`

[Danilo Krummrich]

On Sun, Jun 22, 2025 at 10:26:49PM +0200, Miguel Ojeda wrote:
> On Sun, Jun 22, 2025 at 1:07 PM Shankari Anand
> <shankari.ak0208@gmail.com> wrote:
> >
> > Reword and expand the invariant documentation for `MiscDeviceRegistration`
> > to clarify what it means for the inner device to be "registered".
> > It expands to explain:
> > - `inner` points to a `miscdevice` registered via `misc_register`.
> > - This registration stays valid for the entire lifetime of the object.
> > - Deregistration is guaranteed on `Drop`, via `misc_deregister`.
> >
> > Reported-by: Benno Lossin <lossin@kernel.org>
> > Closes: https://github.com/Rust-for-Linux/linux/issues/1168
> > Fixes: f893691e7426 ("rust: miscdevice: add base miscdevice abstraction")
> > Signed-off-by: Shankari Anand <shankari.ak0208@gmail.com>
> 
> Cc'ing Danilo and Greg.

Thanks -- also Cc'ing Alice.

> > +/// The `inner` field contains a `struct miscdevice` that has been registered with
> > +/// the kernel using `misc_register()`.
> > +/// This registration remains valid for the entire lifetime of the `MiscDeviceRegistration`
> > +/// instance.
> > +/// Deregistration is guaranteed to occur exactly once, during the [`Drop`] implementation, via
> > +/// a call to `misc_deregister()`.
> > +/// The `inner` pointer is never null and always points to a valid, pinned `miscdevice` instance
> > +/// initialized via `MiscDeviceOptions::into_raw`.
> 
> These should be bullet points -- like this it will be rendered like a
> single long paragraph (but please wait for other feedback before
> fixing that).
> 
> The last one seems wrong -- `inner` is not a pointer. It should also
> probably be simplified/merged with the first one.
> 
> Also, please use intra-doc links wherever possible, e.g.
> [`MiscDeviceRegistration`] and for `into_raw` too.
> 
> Thanks for the patch!
> 
> Cheers,
> Miguel