Skip to content

Add XArray abstraction #1019

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 37 commits into
base: rust-dev
Choose a base branch
from
+1,708 −161
Draft

Add XArray abstraction #1019

Changes from 1 commit
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
520a56a
rust: allocator: Prevents mis-aligned allocation
fbq Jun 13, 2023
3d8d9bc
rust: make `UnsafeCell` the outer type in `Opaque`
Darksonn Jun 14, 2023
7671527
rust: types: make `Opaque` be `!Unpin`
y86-dev Jun 30, 2023
0ad204c
kbuild: rust_is_available: remove -v option
masahir0y Jun 16, 2023
70a61eb
kbuild: rust_is_available: fix version check when CC has multiple arg…
ruscur Jun 16, 2023
a250bde
docs: rust: add paragraph about finding a suitable `libclang`
ojeda Jun 16, 2023
00383f7
kbuild: rust_is_available: print docs reference
ojeda Jun 16, 2023
8b2e73a
kbuild: rust_is_available: add check for `bindgen` invocation
ojeda Jun 16, 2023
eb9199d
kbuild: rust_is_available: check that environment variables are set
ojeda Jun 16, 2023
6bed841
kbuild: rust_is_available: fix confusion when a version appears in th…
ojeda Jun 16, 2023
600eb66
kbuild: rust_is_available: normalize version matching
ojeda Jun 16, 2023
6d4220b
kbuild: rust_is_available: handle failures calling `$RUSTC`/`$BINDGEN`
ojeda Jun 16, 2023
10452fc
kbuild: rust_is_available: check that output looks as expected
ojeda Jun 16, 2023
6a4e6dc
kbuild: rust_is_available: add test suite
ojeda Jun 16, 2023
f2f2787
rust: alloc: Add realloc and alloc_zeroed to the GlobalAlloc impl
fbq Jun 25, 2023
53dd54f
rust: bindgen: upgrade to 0.65.1
Shinyzenith Jun 12, 2023
02ddf5a
rust: init: make doctests compilable/testable
ojeda Jun 14, 2023
276f14d
rust: str: make doctests compilable/testable
ojeda Jun 14, 2023
c30db85
rust: sync: make doctests compilable/testable
ojeda Jun 14, 2023
4009de1
rust: types: make doctests compilable/testable
ojeda Jun 14, 2023
e9e95cd
rust: support running Rust documentation tests as KUnit ones
ojeda Jun 14, 2023
eff7a66
MAINTAINERS: add Rust KUnit files to the KUnit entry
ojeda Jun 14, 2023
72fbe4a
rust: macros: fix redefine const_name in `vtable`
cqs21 Jun 26, 2023
8e87a0d
rust: macros: add `paste!` proc macro
nbdd0121 Jun 28, 2023
7c6e564
arm64: rust: Enable Rust support for AArch64
JamieCunliffe Jun 6, 2023
522ba05
arm64: rust: Enable PAC support for Rust.
JamieCunliffe Jun 6, 2023
b1555e1
arm64: Restrict Rust support to little endian only.
JamieCunliffe Jun 6, 2023
19b33fc
rust: bindgen: update installation instructions
matthewtgilbride Jun 29, 2023
c1c510f
rust: xarray: Add an abstraction for XArray
asahilina Jun 27, 2023
91f4147
rust: xarray: add rudimentary doctest
matthewtgilbride Jun 27, 2023
6c19acb
rust: xarray: add `get_mutable` and `find_mut`
matthewtgilbride Jun 27, 2023
3016eac
rust: xarray: add reservation mechanism
asahilina Jun 27, 2023
90ddba2
Why does this cuase NULL pointer dereference?
matthewtgilbride Jul 2, 2023
702746d
Just me thrashing about - figuring out NPE
matthewtgilbride Jul 4, 2023
976067b
rust: delete `ForeignOwnable::borrow_mut`
Darksonn Jul 6, 2023
ac520c2
rust: add improved version of `ForeignOwnable::borrow_mut`
Darksonn Jul 10, 2023
642ff49
rust: xarray: figure out pin and get_scoped
matthewtgilbride Jul 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
rust: xarray: add rudimentary doctest 
Add simple example of xarray usage with `get`, `set`, `replace`,
`remove`, and `find` operations.

Signed-off-by: Matt Gilbride <[email protected]>
  • Loading branch information
@matthewtgilbride
matthewtgilbride committed Jul 5, 2023
commit 91f414785c7e1aa0f9c940edb9d8b0282cc55de6
43 changes: 43 additions & 0 deletions rust/kernel/xarray.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,49 @@ impl<'a, T: ForeignOwnable> Drop for ValueGuard<'a, T> {
/// This structure is expected to often be used with an inner type that can be efficiently
/// cloned, such as an `Arc<T>`.
///
/// # Examples
///
/// In this example, we create a new `XArray` and demonstrate
/// rudimentary read/write operations.
Comment on lines +50 to +51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this example is very helpful! Additionally it might be a good idea to take each example and put it on the relevant functions as well, especially the find function.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't realize that worked! I think at one point in time I could only get the kunit stuff working if the tests were on the top of the struct.

I see now that it does...what do we consider better, a long doctest at the top with interactions between different functions, or individual tests for each function? (Or both...with some repetition?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to have a examples on functions. Big examples only make sense if you want to demonstrate how things are used together. I would recommend this when the API is excessively complicated. I dont think that is the case here.

///
/// ```
/// use kernel::xarray::{XArray, flags::LOCK_IRQ};
///
/// let xarr: Box<XArray<Box<usize>>> = Box::try_new(XArray::new(LOCK_IRQ))?;
/// let xarr: Pin<Box<XArray<Box<usize>>>> = Box::into_pin(xarr);
/// let xarr: Pin<&XArray<Box<usize>>> = xarr.as_ref();
///
/// assert!(xarr.get(0).is_none());
///
/// xarr.set(0, Box::try_new(0)?);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing ? at the end.

/// assert_eq!(xarr.get(0).unwrap().borrow(), &0);
///
/// // `replace` is like `set`, but returns the old value.
/// let old = xarr.replace(0, Box::try_new(1)?)?.unwrap();
/// assert_eq!(old.as_ref(), &0);
/// assert_eq!(xarr.get(0).unwrap().borrow(), &1);
///
/// // `replace` returns `None` if there was no previous value.
/// assert!(xarr.replace(1, Box::try_new(1)?)?.is_none());
/// assert_eq!(xarr.get(1).unwrap().borrow(), &1);
///
/// // Similarly, `remove` returns the old value, or `None` if it didn't exist.
/// assert_eq!(xarr.remove(0).unwrap().as_ref(), &1);
/// assert!(xarr.get(0).is_none());
/// assert!(xarr.remove(0).is_none());
///
/// // `find` returns the index/value pair matching the index, the next larger
/// // index/value pair if it doesn't exist, or `None` of no larger index exists.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would also be good to know if the index wraps around, so if this is true:

let xarr: Box<XArray<Box<usize>>> = Box::try_new(XArray::new(LOCK_IRQ))?;
let xarr: Pin<Box<XArray<Box<usize>>>> = Box::into_pin(xarr);
let xarr: Pin<&XArray<Box<usize>>> = xarr.as_ref();
xarr.set(0, Box::try_new(42)?)?;
let (i, v) = xarr.find(1).unwrap();
assert_eq!(i, 0);
assert_eq!(v.borrow(), &42);

/// let (found_index, found_value) = xarr.find(1).unwrap();
/// assert_eq!(found_index, 1);
/// assert_eq!(found_value.borrow(), &1);
/// let (found_index, found_value) = xarr.find(0).unwrap();
/// assert_eq!(found_index, 1);
/// assert_eq!(found_value.borrow(), &1);
/// assert!(xarr.find(2).is_none());
///
/// # Ok::<(), Error>(())
/// ```
pub struct XArray<T: ForeignOwnable> {
xa: Opaque<bindings::xarray>,
_p: PhantomData<T>,
Expand Down