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

[Danilo Krummrich <dakr@kernel.org>]

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