| Message ID | 20240801000641.1882-2-dakr@kernel.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Generic `Allocator` support for Rust | expand |
On Thu, Aug 1, 2024 at 2:07 AM Danilo Krummrich <dakr@kernel.org> wrote: > > Add a kernel specific `Allocator` trait, that in contrast to the one in > Rust's core library doesn't require unstable features and supports GFP > flags. > > Subsequent patches add the following trait implementors: `Kmalloc`, > `Vmalloc` and `KVmalloc`. > > Signed-off-by: Danilo Krummrich <dakr@kernel.org> It could be nice to mention that the design without `self` parameters is necessary for compatibility with #[derive(SmartPointer)]. > rust/kernel/alloc.rs | 73 ++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 73 insertions(+) > > diff --git a/rust/kernel/alloc.rs b/rust/kernel/alloc.rs > index 1966bd407017..b79dd2c49277 100644 > --- a/rust/kernel/alloc.rs > +++ b/rust/kernel/alloc.rs > @@ -11,6 +11,7 @@ > /// Indicates an allocation error. > #[derive(Copy, Clone, PartialEq, Eq, Debug)] > pub struct AllocError; > +use core::{alloc::Layout, ptr::NonNull}; > > /// Flags to be used when allocating memory. > /// > @@ -86,3 +87,75 @@ pub mod flags { > /// small allocations. > pub const GFP_NOWAIT: Flags = Flags(bindings::GFP_NOWAIT); > } > + > +/// The kernel's [`Allocator`] trait. > +/// > +/// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffer described > +/// via [`Layout`]. > +/// > +/// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on > +/// an object instance. > +/// > +/// # Safety > +/// > +/// Memory returned from an allocator must point to a valid memory buffer and remain valid until > +/// it is explicitly freed. > +/// > +/// Any pointer to a memory buffer which is currently allocated must be valid to be passed to any > +/// other [`Allocator`] function. The same applies for a NULL pointer. > +/// > +/// If `realloc` is called with: > +/// - a size of zero, the given memory allocation, if any, must be freed > +/// - a NULL pointer, a new memory allocation must be created > +pub unsafe trait Allocator { > + /// Allocate memory based on `layout` and `flags`. > + /// > + /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout > + /// constraints (i.e. minimum size and alignment as specified by `layout`). > + /// > + /// This function is equivalent to `realloc` when called with a NULL pointer. > + fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { > + // SAFETY: Passing a NULL pointer to `realloc` is valid by it's safety requirements and asks > + // for a new memory allocation. > + unsafe { Self::realloc(None, layout, flags) } > + } > + > + /// Re-allocate an existing memory allocation to satisfy the requested `layout`. If the > + /// requested size is zero, `realloc` behaves equivalent to `free`. > + /// > + /// If the requested size is larger than the size of the existing allocation, a successful call > + /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but > + /// may also be larger. > + /// > + /// If the requested size is smaller than the size of the existing allocation, `realloc` may or > + /// may not shrink the buffer; this is implementation specific to the allocator. > + /// > + /// On allocation failure, the existing buffer, if any, remains valid. > + /// > + /// The buffer is represented as `NonNull<[u8]>`. > + /// > + /// # Safety > + /// > + /// `ptr` must point to an existing and valid memory allocation created by this allocator > + /// instance. > + /// > + /// Additionally, `ptr` is allowed to be a NULL pointer; in this case a new memory allocation is > + /// created. > + unsafe fn realloc( > + ptr: Option<NonNull<u8>>, > + layout: Layout, > + flags: Flags, > + ) -> Result<NonNull<[u8]>, AllocError>; Is it intentional that this allows you to change the alignment of an allocation? If so, that could use a note in the docs. > + /// Free an existing memory allocation. > + /// > + /// # Safety > + /// > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > + /// instance. > + unsafe fn free(ptr: NonNull<u8>) { > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > + } At the very least, the provided implementation of `free` changes the alignment when it calls `realloc`. Alice
On Thu, Aug 01, 2024 at 10:19:41AM +0200, Alice Ryhl wrote: > On Thu, Aug 1, 2024 at 2:07 AM Danilo Krummrich <dakr@kernel.org> wrote: > > > > Add a kernel specific `Allocator` trait, that in contrast to the one in > > Rust's core library doesn't require unstable features and supports GFP > > flags. > > > > Subsequent patches add the following trait implementors: `Kmalloc`, > > `Vmalloc` and `KVmalloc`. > > > > Signed-off-by: Danilo Krummrich <dakr@kernel.org> > > It could be nice to mention that the design without `self` parameters > is necessary for compatibility with #[derive(SmartPointer)]. Agreed, will do. > > > rust/kernel/alloc.rs | 73 ++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 73 insertions(+) > > > > diff --git a/rust/kernel/alloc.rs b/rust/kernel/alloc.rs > > index 1966bd407017..b79dd2c49277 100644 > > --- a/rust/kernel/alloc.rs > > +++ b/rust/kernel/alloc.rs > > @@ -11,6 +11,7 @@ > > /// Indicates an allocation error. > > #[derive(Copy, Clone, PartialEq, Eq, Debug)] > > pub struct AllocError; > > +use core::{alloc::Layout, ptr::NonNull}; > > > > /// Flags to be used when allocating memory. > > /// > > @@ -86,3 +87,75 @@ pub mod flags { > > /// small allocations. > > pub const GFP_NOWAIT: Flags = Flags(bindings::GFP_NOWAIT); > > } > > + > > +/// The kernel's [`Allocator`] trait. > > +/// > > +/// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffer described > > +/// via [`Layout`]. > > +/// > > +/// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on > > +/// an object instance. > > +/// > > +/// # Safety > > +/// > > +/// Memory returned from an allocator must point to a valid memory buffer and remain valid until > > +/// it is explicitly freed. > > +/// > > +/// Any pointer to a memory buffer which is currently allocated must be valid to be passed to any > > +/// other [`Allocator`] function. The same applies for a NULL pointer. > > +/// > > +/// If `realloc` is called with: > > +/// - a size of zero, the given memory allocation, if any, must be freed > > +/// - a NULL pointer, a new memory allocation must be created > > +pub unsafe trait Allocator { > > + /// Allocate memory based on `layout` and `flags`. > > + /// > > + /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout > > + /// constraints (i.e. minimum size and alignment as specified by `layout`). > > + /// > > + /// This function is equivalent to `realloc` when called with a NULL pointer. > > + fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { > > + // SAFETY: Passing a NULL pointer to `realloc` is valid by it's safety requirements and asks > > + // for a new memory allocation. > > + unsafe { Self::realloc(None, layout, flags) } > > + } > > + > > + /// Re-allocate an existing memory allocation to satisfy the requested `layout`. If the > > + /// requested size is zero, `realloc` behaves equivalent to `free`. > > + /// > > + /// If the requested size is larger than the size of the existing allocation, a successful call > > + /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but > > + /// may also be larger. > > + /// > > + /// If the requested size is smaller than the size of the existing allocation, `realloc` may or > > + /// may not shrink the buffer; this is implementation specific to the allocator. > > + /// > > + /// On allocation failure, the existing buffer, if any, remains valid. > > + /// > > + /// The buffer is represented as `NonNull<[u8]>`. > > + /// > > + /// # Safety > > + /// > > + /// `ptr` must point to an existing and valid memory allocation created by this allocator > > + /// instance. > > + /// > > + /// Additionally, `ptr` is allowed to be a NULL pointer; in this case a new memory allocation is > > + /// created. > > + unsafe fn realloc( > > + ptr: Option<NonNull<u8>>, > > + layout: Layout, > > + flags: Flags, > > + ) -> Result<NonNull<[u8]>, AllocError>; > > Is it intentional that this allows you to change the alignment of an > allocation? If so, that could use a note in the docs. Yes, it's intentional and yes it really misses a note in the documentation. The idea is to allow a change of alignment as long as the new alignment is smaller than the old alignment. In terms of safety, it is the callers responsibility to ensure constant alignment throughout re-allocations (if required). > > > + /// Free an existing memory allocation. > > + /// > > + /// # Safety > > + /// > > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > > + /// instance. > > + unsafe fn free(ptr: NonNull<u8>) { > > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > > + } > > At the very least, the provided implementation of `free` changes the > alignment when it calls `realloc`. Yes, I think that's fine though. Hopefully no one attempts to use the memory anymore once `free` is being called. > > Alice >
On Thu, Aug 1, 2024 at 2:27 PM Danilo Krummrich <dakr@kernel.org> wrote: > > On Thu, Aug 01, 2024 at 10:19:41AM +0200, Alice Ryhl wrote: > > On Thu, Aug 1, 2024 at 2:07 AM Danilo Krummrich <dakr@kernel.org> wrote: > > > + /// Free an existing memory allocation. > > > + /// > > > + /// # Safety > > > + /// > > > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > > > + /// instance. > > > + unsafe fn free(ptr: NonNull<u8>) { > > > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > > > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > > > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > > > + } > > > > At the very least, the provided implementation of `free` changes the > > alignment when it calls `realloc`. > > Yes, I think that's fine though. Hopefully no one attempts to use the memory > anymore once `free` is being called. Sure, but if you require the alignment to remain constant throughout calls to realloc, then you have to word it in a way that allows a different alignment when the new size is zero. Alice
On Thu, Aug 01, 2024 at 04:25:25PM +0200, Alice Ryhl wrote: > On Thu, Aug 1, 2024 at 2:27 PM Danilo Krummrich <dakr@kernel.org> wrote: > > > > On Thu, Aug 01, 2024 at 10:19:41AM +0200, Alice Ryhl wrote: > > > On Thu, Aug 1, 2024 at 2:07 AM Danilo Krummrich <dakr@kernel.org> wrote: > > > > + /// Free an existing memory allocation. > > > > + /// > > > > + /// # Safety > > > > + /// > > > > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > > > > + /// instance. > > > > + unsafe fn free(ptr: NonNull<u8>) { > > > > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > > > > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > > > > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > > > > + } > > > > > > At the very least, the provided implementation of `free` changes the > > > alignment when it calls `realloc`. > > > > Yes, I think that's fine though. Hopefully no one attempts to use the memory > > anymore once `free` is being called. > > Sure, but if you require the alignment to remain constant throughout > calls to realloc, then you have to word it in a way that allows a > different alignment when the new size is zero. Agreed, this case should be covered once I documented that the new alignment must be equal to or smaller than the old alignment. > > Alice >
On Thu, Aug 01, 2024 at 02:02:00AM +0200, Danilo Krummrich wrote: [...] > +/// The kernel's [`Allocator`] trait. > +/// > +/// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffer described > +/// via [`Layout`]. > +/// > +/// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on > +/// an object instance. > +/// > +/// # Safety > +/// > +/// Memory returned from an allocator must point to a valid memory buffer and remain valid until > +/// it is explicitly freed. > +/// > +/// Any pointer to a memory buffer which is currently allocated must be valid to be passed to any > +/// other [`Allocator`] function. The same applies for a NULL pointer. > +/// Are you saying you could kmalloc() a memory buffer and pass it to a vfree()? Or am I missing something here? Regards, Boqun > +/// If `realloc` is called with: > +/// - a size of zero, the given memory allocation, if any, must be freed > +/// - a NULL pointer, a new memory allocation must be created > +pub unsafe trait Allocator { > + /// Allocate memory based on `layout` and `flags`. > + /// > + /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout > + /// constraints (i.e. minimum size and alignment as specified by `layout`). > + /// > + /// This function is equivalent to `realloc` when called with a NULL pointer. > + fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { > + // SAFETY: Passing a NULL pointer to `realloc` is valid by it's safety requirements and asks > + // for a new memory allocation. > + unsafe { Self::realloc(None, layout, flags) } > + } > + > + /// Re-allocate an existing memory allocation to satisfy the requested `layout`. If the > + /// requested size is zero, `realloc` behaves equivalent to `free`. > + /// > + /// If the requested size is larger than the size of the existing allocation, a successful call > + /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but > + /// may also be larger. > + /// > + /// If the requested size is smaller than the size of the existing allocation, `realloc` may or > + /// may not shrink the buffer; this is implementation specific to the allocator. > + /// > + /// On allocation failure, the existing buffer, if any, remains valid. > + /// > + /// The buffer is represented as `NonNull<[u8]>`. > + /// > + /// # Safety > + /// > + /// `ptr` must point to an existing and valid memory allocation created by this allocator > + /// instance. > + /// > + /// Additionally, `ptr` is allowed to be a NULL pointer; in this case a new memory allocation is > + /// created. > + unsafe fn realloc( > + ptr: Option<NonNull<u8>>, > + layout: Layout, > + flags: Flags, > + ) -> Result<NonNull<[u8]>, AllocError>; > + > + /// Free an existing memory allocation. > + /// > + /// # Safety > + /// > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > + /// instance. > + unsafe fn free(ptr: NonNull<u8>) { > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > + } > +} > -- > 2.45.2 >
On Sat, Aug 03, 2024 at 11:21:21PM -0700, Boqun Feng wrote: > On Thu, Aug 01, 2024 at 02:02:00AM +0200, Danilo Krummrich wrote: > [...] > > +/// The kernel's [`Allocator`] trait. > > +/// > > +/// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffer described > > +/// via [`Layout`]. > > +/// > > +/// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on > > +/// an object instance. > > +/// > > +/// # Safety > > +/// > > +/// Memory returned from an allocator must point to a valid memory buffer and remain valid until > > +/// it is explicitly freed. > > +/// > > +/// Any pointer to a memory buffer which is currently allocated must be valid to be passed to any > > +/// other [`Allocator`] function. The same applies for a NULL pointer. > > +/// > > Are you saying you could kmalloc() a memory buffer and pass it to a > vfree()? Or am I missing something here? I will extend it to: "valid to be passed to any other [`Allocator`] function" of the same type. > > Regards, > Boqun > > > +/// If `realloc` is called with: > > +/// - a size of zero, the given memory allocation, if any, must be freed > > +/// - a NULL pointer, a new memory allocation must be created > > +pub unsafe trait Allocator { > > + /// Allocate memory based on `layout` and `flags`. > > + /// > > + /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout > > + /// constraints (i.e. minimum size and alignment as specified by `layout`). > > + /// > > + /// This function is equivalent to `realloc` when called with a NULL pointer. > > + fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { > > + // SAFETY: Passing a NULL pointer to `realloc` is valid by it's safety requirements and asks > > + // for a new memory allocation. > > + unsafe { Self::realloc(None, layout, flags) } > > + } > > + > > + /// Re-allocate an existing memory allocation to satisfy the requested `layout`. If the > > + /// requested size is zero, `realloc` behaves equivalent to `free`. > > + /// > > + /// If the requested size is larger than the size of the existing allocation, a successful call > > + /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but > > + /// may also be larger. > > + /// > > + /// If the requested size is smaller than the size of the existing allocation, `realloc` may or > > + /// may not shrink the buffer; this is implementation specific to the allocator. > > + /// > > + /// On allocation failure, the existing buffer, if any, remains valid. > > + /// > > + /// The buffer is represented as `NonNull<[u8]>`. > > + /// > > + /// # Safety > > + /// > > + /// `ptr` must point to an existing and valid memory allocation created by this allocator > > + /// instance. > > + /// > > + /// Additionally, `ptr` is allowed to be a NULL pointer; in this case a new memory allocation is > > + /// created. > > + unsafe fn realloc( > > + ptr: Option<NonNull<u8>>, > > + layout: Layout, > > + flags: Flags, > > + ) -> Result<NonNull<[u8]>, AllocError>; > > + > > + /// Free an existing memory allocation. > > + /// > > + /// # Safety > > + /// > > + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` > > + /// instance. > > + unsafe fn free(ptr: NonNull<u8>) { > > + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. > > + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. > > + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; > > + } > > +} > > -- > > 2.45.2 > > >
diff --git a/rust/kernel/alloc.rs b/rust/kernel/alloc.rs index 1966bd407017..b79dd2c49277 100644 --- a/rust/kernel/alloc.rs +++ b/rust/kernel/alloc.rs @@ -11,6 +11,7 @@ /// Indicates an allocation error. #[derive(Copy, Clone, PartialEq, Eq, Debug)] pub struct AllocError; +use core::{alloc::Layout, ptr::NonNull}; /// Flags to be used when allocating memory. /// @@ -86,3 +87,75 @@ pub mod flags { /// small allocations. pub const GFP_NOWAIT: Flags = Flags(bindings::GFP_NOWAIT); } + +/// The kernel's [`Allocator`] trait. +/// +/// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffer described +/// via [`Layout`]. +/// +/// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on +/// an object instance. +/// +/// # Safety +/// +/// Memory returned from an allocator must point to a valid memory buffer and remain valid until +/// it is explicitly freed. +/// +/// Any pointer to a memory buffer which is currently allocated must be valid to be passed to any +/// other [`Allocator`] function. The same applies for a NULL pointer. +/// +/// If `realloc` is called with: +/// - a size of zero, the given memory allocation, if any, must be freed +/// - a NULL pointer, a new memory allocation must be created +pub unsafe trait Allocator { + /// Allocate memory based on `layout` and `flags`. + /// + /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout + /// constraints (i.e. minimum size and alignment as specified by `layout`). + /// + /// This function is equivalent to `realloc` when called with a NULL pointer. + fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { + // SAFETY: Passing a NULL pointer to `realloc` is valid by it's safety requirements and asks + // for a new memory allocation. + unsafe { Self::realloc(None, layout, flags) } + } + + /// Re-allocate an existing memory allocation to satisfy the requested `layout`. If the + /// requested size is zero, `realloc` behaves equivalent to `free`. + /// + /// If the requested size is larger than the size of the existing allocation, a successful call + /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but + /// may also be larger. + /// + /// If the requested size is smaller than the size of the existing allocation, `realloc` may or + /// may not shrink the buffer; this is implementation specific to the allocator. + /// + /// On allocation failure, the existing buffer, if any, remains valid. + /// + /// The buffer is represented as `NonNull<[u8]>`. + /// + /// # Safety + /// + /// `ptr` must point to an existing and valid memory allocation created by this allocator + /// instance. + /// + /// Additionally, `ptr` is allowed to be a NULL pointer; in this case a new memory allocation is + /// created. + unsafe fn realloc( + ptr: Option<NonNull<u8>>, + layout: Layout, + flags: Flags, + ) -> Result<NonNull<[u8]>, AllocError>; + + /// Free an existing memory allocation. + /// + /// # Safety + /// + /// `ptr` must point to an existing and valid memory allocation created by this `Allocator` + /// instance. + unsafe fn free(ptr: NonNull<u8>) { + // SAFETY: `ptr` is guaranteed to be previously allocated with this `Allocator` or NULL. + // Calling `realloc` with a buffer size of zero, frees the buffer `ptr` points to. + let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), Flags(0)) }; + } +}
Add a kernel specific `Allocator` trait, that in contrast to the one in Rust's core library doesn't require unstable features and supports GFP flags. Subsequent patches add the following trait implementors: `Kmalloc`, `Vmalloc` and `KVmalloc`. Signed-off-by: Danilo Krummrich <dakr@kernel.org> --- rust/kernel/alloc.rs | 73 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+)