rust: alloc: kvec doc example and allocator unit tests
Subsystems (2)
v4 cover rust: alloc: kvec doc example and allocator unit tests
From: Hui Zhu <[email protected]>
This series includes two Rust patches:
Patch 1 adds KUnit tests for Rust allocation wrappers (kmalloc, vmalloc, kvmalloc). It covers basic allocations, large alignments, and checks for expected failures. Each test verifies content integrity through byte pattern checks.
Patch 2 improves the documentation for KVec::as_slice() by adding a code example. This shows how to use the method with push operations and assertions.
Both patches are co-developed with Geliang Tang. Tested on x86_64 using KUnit.
Changelog:
v4:
According to the comments of, add the error check for push. v3:
According to the comments of Danilo and Boqun, move KVec test to doc example and move VBox to allocator unit tests.
v2:
According to the comments of Danilo, updated the commit to samples the usage of VBox and KVec.
Hui Zhu (2):
rust: allocator: add unit tests of kmalloc, vmalloc and kvmalloc
rust: alloc: kvec: add doc example for as_slice method
rust/kernel/alloc/allocator.rs | 57 ++++++++++++++++++++++++++++++++++ rust/kernel/alloc/kvec.rs | 10 ++++++ 2 files changed, 67 insertions(+)
Signature · 1 line
2.43.0
PATCH v4 1/2 rust: allocator: add unit tests of kmalloc, vmalloc and kvmalloc
From: Hui Zhu <[email protected]>
Add KUnit test cases to validate the functionality of Rust allocation wrappers (kmalloc, vmalloc, kvmalloc).
The tests include:
Basic allocation tests for each allocator using a 1024-byte Blob structure initialized with a 0xfe pattern.
Large alignment (> PAGE_SIZE) allocation testing using an 8192-byte aligned LargeAlignBlob structure.
Verification of allocation constraints:
- kmalloc successfully handles large alignments.
- vmalloc and kvmalloc correctly fail for unsupported large alignments. Content verification through byte-by-byte pattern checking.
--- rust/kernel/alloc/allocator.rs | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)
rust/kernel/alloc/allocator.rs +57 -0
@@ -187,3 +187,60 @@ unsafe fn realloc(unsafe {ReallocFunc ::KVREALLOC .call (ptr, layout, old_layout, flags) } } } + +#[macros::kunit_tests(rust_allocator_kunit)] +mod tests { +use super ::*; +use kernel::prelude::*; + +const TEST_SIZE :usize =1024 ; +const LARGE_ALIGN_TEST_SIZE :usize = kernel::page::PAGE_SIZE *4 ; +#[repr(align( 128 ))] +struct Blob ([u8 ;TEST_SIZE ]); +// This structure is used to test the allocation of alignments larger +// than PAGE_SIZE. +// Since this is not yet supported, avoid accessing the contents of +// the structure for now. +#[allow(dead_code)] +#[repr(align( 8192 ))] +struct LargeAlignBlob ([u8 ;LARGE_ALIGN_TEST_SIZE ]); + +#[test] +fn test_kmalloc () ->Result <(),AllocError > { +let blob =KBox ::new (Blob ([0xfeu8 ;TEST_SIZE ]),GFP_KERNEL )?; +for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfeu8 ); + } + +let blob =KBox ::new (LargeAlignBlob ([0xfdu8 ;LARGE_ALIGN_TEST_SIZE ]),GFP_KERNEL )?; +for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfdu8 ); + } + +Ok (()) + } + +#[test] +fn test_vmalloc () ->Result <(),AllocError > { +let blob =VBox ::new (Blob ([0xfeu8 ;TEST_SIZE ]),GFP_KERNEL )?; +for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfeu8 ); + } + +assert! (VBox ::<LargeAlignBlob >::new_uninit (GFP_KERNEL ).is_err ()); + +Ok (()) + } + +#[test] +fn test_kvmalloc () ->Result <(),AllocError > { +let blob =KVBox ::new (Blob ([0xfeu8 ;TEST_SIZE ]),GFP_KERNEL )?; +for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfeu8 ); + } + +assert! (KVBox ::<LargeAlignBlob >::new_uninit (GFP_KERNEL ).is_err ()); + +Ok (()) + } +}
Signature · 1 line
2.43.0
Danilo Krummrich
maintainerRe: [PATCH v4 1/2] rust: allocator: add unit tests of kmalloc, vmalloc and kvmalloc
Quoted 15 lines · Hui Zhu
From: Hui Zhu <[email protected]>
Add KUnit test cases to validate the functionality of Rust allocation wrappers (kmalloc, vmalloc, kvmalloc).
The tests include:
Basic allocation tests for each allocator using a 1024-byte Blob structure initialized with a0xfepattern.
Large alignment (>PAGE_SIZE) allocation testing using an 8192-byte aligned LargeAlignBlob structure.
Verification of allocation constraints:
- kmalloc successfully handles large alignments.
- vmalloc and kvmalloc correctly fail for unsupported large alignments. Content verification through byte-by-byte pattern checking.
Quoted 3 lines
Co-developed-by Geliang Tang <[email protected]>Signed-off-by Geliang Tang <[email protected]>Signed-off-by Hui Zhu <[email protected]>
Thanks for the patch, additional test are always welcome! :)
Quoted 23 lines
--- rust/kernel/alloc/allocator.rs | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)rust/kernel/alloc/allocator.rs +11
-0@@ -187,3 +187,60 @@ unsafe fn realloc(unsafe {ReallocFunc ::KVREALLOC .call (ptr, layout, old_layout, flags) } } } + +#[macros::kunit_tests(rust_allocator_kunit)] +mod tests { +use super ::*; +use kernel::prelude::*; + +const TEST_SIZE :usize =1024 ; +const LARGE_ALIGN_TEST_SIZE :usize = kernel::page::PAGE_SIZE *4 ; +#[repr(align( 128 ))] +struct Blob ([u8 ;TEST_SIZE ]); +// This structure is used to test the allocation of alignments larger
rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 210
Quoted 10 lines
rust/kernel/alloc/allocator.rs +10
-0+// than PAGE_SIZE. +// Since this is not yet supported, avoid accessing the contents of +// the structure for now. +#[allow(dead_code)] +#[repr(align( 8192 ))] +struct LargeAlignBlob ([u8 ;LARGE_ALIGN_TEST_SIZE ]); + +#[test] +fn test_kmalloc () ->Result <(),AllocError > { +let blob =KBox ::new (Blob ([0xfeu8 ;TEST_SIZE ]),GFP_KERNEL )?;
Since those are now actual unit tests on the Allocator implementations, it would be fine to use them directly. However, for the case you are testing here, i.e. alignment using Box is perfectly fine.
Having that said, I wouldn't call those tests test_*malloc(), since they're not really testing all aspects of a certain allocator, but only the success to allocate with certain alignment arguments.
Instead, I propose to write just a single test, test_alignment(), with a few helper functions.
For instance, your Blob test structure could have a constructor that is generic over A: Allocator.
However, given that you really only want to check alignment, you probably want a structure like this instead.
struct TestAlign<A: Allocator>(Box<MaybeUninit<[u8; TEST_SIZE]>, A>);
impl<A: Allocator> TestAlign<A> {
fn new() -> Result<Self> {
Box::<_, A>::new_uninit(GFP_KERNEL)
}
fn alignment_valid(&self) -> bool {
...
}
}and then test_alignment() can just do
let test = TestAlign::<Kmalloc>::new()?; assert!(test.alignment_valid()); ...
Given that this is now a unit test I also think that actually validating the alignment of the pointer Box wraps makes sense, similar to what you had in v2.
rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 213
Quoted 3 lines
rust/kernel/alloc/allocator.rs +3
-0+for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfeu8 ); + }
I don't think that this has any valid in the context of testing alignment.
rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 215
Quoted 1 line
rust/kernel/alloc/allocator.rs +1
-0+let blob =KBox ::new (LargeAlignBlob ([0xfdu8 ;LARGE_ALIGN_TEST_SIZE ]),GFP_KERNEL )?;
For the large alignment case, you can consider to let TestAlign take a const generic, additional to A: Allocator, e.g.
struct TestAlign<A: Allocator, const SIZE: usize>(Box<MaybeUninit<[u8; SIZE]>, A>);
This way you can keep test_alignment() function very compact.
- Danilo
Re: [PATCH v4 1/2] rust: allocator: add unit tests of kmalloc, vmalloc and kvmalloc
Hi Danilo,
Quoted 16 lines · Danilo Krummrich
Quoted 15 lines · Hui Zhu
From: Hui Zhu <[email protected]>
Add KUnit test cases to validate the functionality of Rust allocation wrappers (kmalloc, vmalloc, kvmalloc).
The tests include:
Basic allocation tests for each allocator using a 1024-byte Blob structure initialized with a0xfepattern.
Large alignment (>PAGE_SIZE) allocation testing using an 8192-byte aligned LargeAlignBlob structure.
Verification of allocation constraints:
- kmalloc successfully handles large alignments.
- vmalloc and kvmalloc correctly fail for unsupported large alignments. Content verification through byte-by-byte pattern checking.
Quoted 5 lines
Quoted 3 lines
Co-developed-by Geliang Tang <[email protected]>Signed-off-by Geliang Tang <[email protected]>Signed-off-by Hui Zhu <[email protected]>Thanks for the patch, additional test are always welcome! :)
Great!
Quoted 80 lines
Quoted 24 lines
--- rust/kernel/alloc/allocator.rs | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)rust/kernel/alloc/allocator.rs +11
-0@@ -187,3 +187,60 @@ unsafe fn realloc(unsafe {ReallocFunc ::KVREALLOC .call (ptr, layout, old_layout, flags) } } } + +#[macros::kunit_tests(rust_allocator_kunit)] +mod tests { +use super ::*; +use kernel::prelude::*; + +const TEST_SIZE :usize =1024 ; +const LARGE_ALIGN_TEST_SIZE :usize = kernel::page::PAGE_SIZE *4 ; +#[repr(align( 128 ))] +struct Blob ([u8 ;TEST_SIZE ]); +// This structure is used to test the allocation of alignments larger rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 210
Quoted 10 lines
rust/kernel/alloc/allocator.rs +10
-0+// than PAGE_SIZE. +// Since this is not yet supported, avoid accessing the contents of +// the structure for now. +#[allow(dead_code)] +#[repr(align( 8192 ))] +struct LargeAlignBlob ([u8 ;LARGE_ALIGN_TEST_SIZE ]); + +#[test] +fn test_kmalloc () ->Result <(),AllocError > { +let blob =KBox ::new (Blob ([0xfeu8 ;TEST_SIZE ]),GFP_KERNEL )?;Since those are now actual unit tests on the Allocator implementations, it would be fine to use them directly. However, for the case you are testing here, i.e. alignment using Box is perfectly fine.
Having that said, I wouldn't call those tests test_*malloc(), since they're not really testing all aspects of a certain allocator, but only the success to allocate with certain alignment arguments.
Instead, I propose to write just a single test,
test_alignment(), with a few helper functions.For instance, your Blob test structure could have a constructor that is generic over A: Allocator.
However, given that you really only want to check alignment, you probably want a structure like this instead.
struct TestAlign<A: Allocator>(Box<MaybeUninit<[u8; TEST_SIZE]>, A>); impl<A: Allocator> TestAlign<A> { fn new() -> Result<Self> { Box::<_, A>::new_uninit(GFP_KERNEL) } fn alignment_valid(&self) -> bool { ... } }and then
test_alignment()can just dolet test = TestAlign::<Kmalloc>::new()?; assert!(test.alignment_valid()); ...Given that this is now a unit test I also think that actually validating the alignment of the pointer Box wraps makes sense, similar to what you had in v2.
rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 213
Quoted 3 lines
rust/kernel/alloc/allocator.rs +3
-0+for bin blob.0 .as_slice ().iter () { +assert_eq! (*b,0xfeu8 ); + }I don't think that this has any valid in the context of testing alignment.
Quoted 9 lines
rust/kernel/alloc/allocator.rs unsafe fn realloc( · line 215
Quoted 1 line
rust/kernel/alloc/allocator.rs +1
-0+let blob =KBox ::new (LargeAlignBlob ([0xfdu8 ;LARGE_ALIGN_TEST_SIZE ]),GFP_KERNEL )?;For the large alignment case, you can consider to let TestAlign take a const generic, additional to A: Allocator, e.g.
struct TestAlign<A: Allocator, const SIZE: usize>(Box<MaybeUninit<[u8; SIZE]>, A>);This way you can keep
test_alignment()function very compact.
I sent new patches according to your comments.
Quoted 1 line
- Danilo
Best,
Hui
PATCH v4 2/2 rust: alloc: kvec: add doc example for as_slice method
In reply to Hui ZhuFrom: Hui Zhu <[email protected]>
Add a practical usage example to the documentation of KVec::as_slice() showing how to:
Create a new KVec.
Push elements into it.
Convert to a slice via as_slice().
--- rust/kernel/alloc/kvec.rs | 10 ++++++++++ 1 file changed, 10 insertions(+)
rust/kernel/alloc/kvec.rs +10 -0
@@ -224,6 +224,16 @@ unsafe fn dec_len(&mut self, count: usize) -> &mut [T] { }/// Returns a slice of the entire vector. +/// +/// # Examples +/// +/// ``` +/// let mut v = KVec::new(); +/// v.push(1, GFP_KERNEL)?; +/// v.push(2, GFP_KERNEL)?; +/// assert_eq!(v.as_slice(), &[1, 2]); +/// # Ok::<(), Error>(()) +/// ``` #[inline] pub fn as_slice (&self) -> &[T ] { self
Signature · 1 line
2.43.0