[PATCH v8 0/2] rust: xarray: Add an abstraction for XArray

["Maíra Canal" <mcanal@igalia.com>]

This abstraction is part of the set of dependencies I need to upstream
rustgem, a virtual GEM provider driver in the DRM [1]. Also, this
abstraction will be useful for the upstreaming process of the drm/asahi
driver.

Best Regards,
- Maíra

Changelog
=========

v1 -> v2: https://lore.kernel.org/r/20230224-rust-xarray-v1-1-80f0904ce5d3@asahilina.net

- Added Pin requirement for all XArray operations, to close a
  soundness hole due to the lock in the XArray (locks are not safe to
  move while locked). Creation does not require pinning in place, since
  the lock cannot be acquired at that point.
- Added safety note to Drop impl about why we don't need to do the lock
  unlock dance to ensure soundness in case of a dropped lock guard.
- Downstream drm/asahi driver was also rebased on this version to prove
  it works (previously it was still on a pre-v1 version).
- This still depends on the Error series (v1). v2 of that will need a
  trivial rename of Error::from_kernel_errno -> Error::from_errno. If
  this version of XArray ends up looking good, I'll send a trivial v4 of
  XArray with the rename, after sending the v2 of the Error series.

v2 -> v3: https://lore.kernel.org/r/20230224-rust-xarray-v2-1-4eeb0134944c@asahilina.net

- Updated to the error v2/v3 series API.
- Renamed `err` to `ret` for consistency with the other instance.

v3 -> v4: https://lore.kernel.org/rust-for-linux/20230224-rust-xarray-v3-1-04305b1173a5@asahilina.net/

- Rebase on top of rust-next.

v4 -> v5: https://lore.kernel.org/rust-for-linux/20231126131210.1384490-1-mcanal@igalia.com/T/

- Use Gary's suggestion for the Deref trait - no unsafe code! (Benno Lossin)
- Use NonNull (Benno Lossin)
- Not spelling out the lifetimes (Benno Lossin)
- Change XArray invariants (Benno Lossin)
- Add all SAFETY comments (Benno Lossin)
- Use `kernel::error::to_result` (Benno Lossin)
- s/alloc_limits/alloc_limits_opt (Benno Lossin)
- Split unsafe block (Benno Lossin)
- Make error handling of the function `alloc_limits_opt` through `ScopeGuard` (Benno Lossin)
- Use `ScopeGuard` in the function `get` (Benno Lossin)

v5 -> v6: https://lore.kernel.org/rust-for-linux/20231201195300.1329092-1-mcanal@igalia.com/T/

- Update constants to the new format (RUST_CONST_HELPER)
- Add invariant for `self.0` being a pointer derived from `T::from_foreign` (Benno Lossin)
- Fix the place of the INVARIANT comments (Benno Lossin)
- Use the Pin-Init API (Benno Lossin)
- Remove PhantomPinned from XArray (Benno Lossin)
- Add new requirements for calling `xa_unlock()` (Benno Lossin)
- Improve SAFETY comments (Benno Lossin)
- Split unsafe block (Benno Lossin)
- s/alloc_limits_opt/insert_between (Benno Lossin)
- Specify the target type of the cast (Andreas Hindborg/Trevor Gross)
- Guarantee that T is 4-byte aligned (Andreas Hindborg)
- Add code examples in the code (Boqun Feng)

v6 -> v7: https://lore.kernel.org/rust-for-linux/20240116151728.370238-1-mcanal@igalia.com/T/

- Change the INVARIANT from `Guard` (Boqun Feng)
- Change the INVARIANT from `XArray` (Boqun Feng)
- Change INVARIANT to # Invariant (Benno Lossin)
- Move XArray definition to the top of the file (Benno Lossin)
- Show structs from examples (Benno Lossin)
- Import XArray directly (Benno Lossin)
- Adjust some SAFETY comments (Benno Lossin & Alice Ryhl)
- Reestructure the NonNull block (Alice Ryhl)
- Create method `to_index()` (Alice Ryhl)
- Use `drop(T::from_foreign(new))` (Alice Ryhl)
- Both Sync and Send requires Send (Alice Ryhl)
- Add FOREIGN_ALIGN to trait ForeignOwnable (Alice Ryhl)

v7 -> v8: https://lore.kernel.org/rust-for-linux/20240209223201.2145570-2-mcanal@igalia.com/T/

* Fix clippy complains (Andreas Hindborg)
* Move semicolon outside of the unsafe block (Alice Ryhl)
* Remove PhantomData from Reservation (Alice Ryhl)
* Add `drop` call in `insert_between` (Alice Ryhl)
* Use "# Invariants" on the XArray struct (Alice Ryhl)
* Don't mention that you use pin-init to make `self.xa` be initialized and valid. (Alice Ryhl)
* Change Guard `NonNull<T>` to `NonNull<c_void>`, since that's the type used by `into_foreign` (Alice Ryhl)
* Migrate the C header to the new `srctree/` notation (Miguel Ojeda)
* Keep comments at 100 columns (Miguel Ojeda)
* Use intra-doc links where possible (Miguel Ojeda)
* Misc fixes in the comments (Miguel Ojeda)

[1] https://github.com/mairacanal/linux/pull/11

Asahi Lina (1):
  rust: xarray: Add an abstraction for XArray

Maíra Canal (1):
  rust: types: add FOREIGN_ALIGN to ForeignOwnable

 rust/bindings/bindings_helper.h |  17 ++
 rust/helpers.c                  |  37 +++
 rust/kernel/lib.rs              |   1 +
 rust/kernel/sync/arc.rs         |   2 +
 rust/kernel/types.rs            |   7 +
 rust/kernel/xarray.rs           | 407 ++++++++++++++++++++++++++++++++
 6 files changed, 471 insertions(+)
 create mode 100644 rust/kernel/xarray.rs

--
2.43.0