linux-kernel - Re: [PATCH v5 09/26] rust: alloc: implement kernel `Box`

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <Zr0ocI-j3fZZM7Rw@cassiopeiae>
Date: Wed, 14 Aug 2024 23:58:08 +0200
From: Danilo Krummrich <dakr@...nel.org>
To: Benno Lossin <benno.lossin@...ton.me>
Cc: ojeda@...nel.org, alex.gaynor@...il.com, wedsonaf@...il.com,
	boqun.feng@...il.com, gary@...yguo.net, bjorn3_gh@...tonmail.com,
	a.hindborg@...sung.com, aliceryhl@...gle.com,
	akpm@...ux-foundation.org, daniel.almeida@...labora.com,
	faith.ekstrand@...labora.com, boris.brezillon@...labora.com,
	lina@...hilina.net, mcanal@...lia.com, zhiw@...dia.com,
	cjia@...dia.com, jhubbard@...dia.com, airlied@...hat.com,
	ajanulgu@...hat.com, lyude@...hat.com, linux-kernel@...r.kernel.org,
	rust-for-linux@...r.kernel.org, linux-mm@...ck.org
Subject: Re: [PATCH v5 09/26] rust: alloc: implement kernel `Box`

On Wed, Aug 14, 2024 at 05:01:34PM +0000, Benno Lossin wrote:
> On 12.08.24 20:22, Danilo Krummrich wrote:
> > +/// The kernel's [`Box`] type - a heap allocation for a single value of type `T`.
> > +///
> > +/// This is the kernel's version of the Rust stdlib's `Box`. There are a couple of differences,
> > +/// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
> > +/// supported.
> 
> I would add "But otherwise it works the same." (I don't know if there is
> a comma needed after the "otherwise").

There are more differences we don't list here, and probably don't need to.
Hence, saying that it otherwise works the same isn't correct.

> Also I remember that there was one more difference with a custom box
> compared to the stdlib, but I forgot what that was, does someone else
> remember? We should also put that here.

Obviously, there are also quite some API differences. For instance, `Box`
generally requires two generics, value type and allocator, we take page flags
and return a `Result`, where std just panics on failure.

> 
> > +///
> > +/// `Box` works with any of the kernel's allocators, e.g. [`super::allocator::Kmalloc`],
> > +/// [`super::allocator::Vmalloc`] or [`super::allocator::KVmalloc`]. There are aliases for `Box`
> > +/// with these allocators ([`KBox`], [`VBox`], [`KVBox`]).
> > +///
> > +/// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// let b = KBox::<u64>::new(24_u64, GFP_KERNEL)?;
> > +///
> > +/// assert_eq!(*b, 24_u64);
> > +///
> > +/// # Ok::<(), Error>(())
> > +/// ```
> > +///
> > +/// ```
> > +/// # use kernel::bindings;
> > +///
> > +/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
> > +/// struct Huge([u8; SIZE]);
> > +///
> > +/// assert!(KBox::<Huge>::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err());
> > +/// ```
> > +///
> > +/// ```
> > +/// # use kernel::bindings;
> > +///
> > +/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
> > +/// struct Huge([u8; SIZE]);
> > +///
> > +/// assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok());
> > +/// ```
> > +///
> > +/// # Invariants
> > +///
> > +/// The [`Box`]' pointer always properly aligned and either points to memory allocated with `A` or,
> 
> "pointer always properly" -> "pointer is properly"
> 
> > +/// for zero-sized types, is a dangling pointer.
> 
> I think this section would look nicer, if it were formatted using bullet
> points (that way the bracketing of the "or" is also unambiguous).
> 
> Additionally, this is missing that the pointer is valid for reads and
> writes.
> 
> > +pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
> 
> Why no `repr(transparent)`?

I wasn't entirely sure whether that's OK with the additional `PhantomData`, but
I think it is, gonna add it.

> 
> > +
> > +/// Type alias for `Box` with a `Kmalloc` allocator.
> 
> I think we should add that this is only designed for small values.

I don't want duplicate the existing documentation around kmalloc and friends
[1].

Maybe we can refer to the existing documentation somehow.

[1] https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html

> 
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// let b = KBox::new(24_u64, GFP_KERNEL)?;
> > +///
> > +/// assert_eq!(*b, 24_u64);
> > +///
> > +/// # Ok::<(), Error>(())
> > +/// ```
> > +pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
> > +
> > +/// Type alias for `Box` with a `Vmalloc` allocator.
> 
> Same here, add that this is supposed to be used for big values (or is
> this also a general-purpose allocator, just not guaranteeing that the
> memory is physically contiguous? in that case I would document it
> here and also on `Vmalloc`).

Same as above, I'd rather not duplicate that. But I'm happy to link things in,
just not sure what's the best way doing it.