[RFC 08/16] bus1/util: add basic utilities

[David Rheinsberg <david@readahead.eu>]

Import some basic utility helpers. They come with documentation and
should be self-explanatory.

Some helpers will become obsolete, once the MSRV is bumped. This is
noted in the documentation.

Signed-off-by: David Rheinsberg <david@readahead.eu>
---
 ipc/bus1/lib.rs      |  2 +
 ipc/bus1/util/mod.rs | 87 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 ipc/bus1/util/mod.rs

diff --git a/ipc/bus1/lib.rs b/ipc/bus1/lib.rs
index 7c3364651638..a7e7a99086c2 100644
--- a/ipc/bus1/lib.rs
+++ b/ipc/bus1/lib.rs
@@ -4,6 +4,8 @@
 //! This is the in-kernel implementation of the Bus1 communication system in
 //! rust. Any user-space API is outside the scope of this module.
 
+pub mod util;
+
 #[allow(
     dead_code,
     missing_docs,
diff --git a/ipc/bus1/util/mod.rs b/ipc/bus1/util/mod.rs
new file mode 100644
index 000000000000..4dd08c04eec6
--- /dev/null
+++ b/ipc/bus1/util/mod.rs
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: GPL-2.0
+//! # Utility library
+//!
+//! This module provides utilities that can be used independently of the core
+//! module.
+
+use kernel::prelude::*;
+use kernel::sync::{Arc, ArcBorrow};
+
+/// Convert an Arc to its pinned version.
+///
+/// All [`Arc`] instances are unconditionally pinned. It is always safe to
+/// convert from their unpinned variant to their pinned variant.
+///
+/// Most kernel APIs just use a plain [`Arc`], even if they rely on pinning.
+/// If another API needs a `Pin<T>`, this converter can provide it for [`Arc`],
+/// even though most other kernel APIs do not use `Pin<Arc<T>>`.
+pub fn arc_pin<T>(v: Arc<T>) -> Pin<Arc<T>> {
+    // SAFETY: `Arc<T>` guarantees its target is pinned.
+    unsafe { Pin::new_unchecked(v) }
+}
+
+/// Convert an Arc to its unpinned version.
+///
+/// All [`Arc`] instances are unconditionally pinned. It is always safe to
+/// convert from their pinned variant to their unpinned variant.
+///
+/// Most kernel APIs just use a plain [`Arc`], even if they rely on pinning.
+/// This converter allows getting an [`Arc`] if some other API returned a
+/// generic `Pin<T>` with `T = Arc<U>`.
+pub fn arc_unpin<T>(v: Pin<Arc<T>>) -> Arc<T> {
+    // SAFETY: `Arc<T>` guarantees its target is pinned, even if not wrapped.
+    unsafe { Pin::into_inner_unchecked(v) }
+}
+
+/// Convert an ArcBorrow to its pinned version.
+///
+/// All [`Arc`] instances are unconditionally pinned. It is always safe to
+/// convert from their unpinned variant to their pinned variant.
+pub fn arc_borrow_pin<T>(v: ArcBorrow<'_, T>) -> Pin<ArcBorrow<'_, T>> {
+    // SAFETY: `Arc<T>` guarantees its target is pinned.
+    unsafe { Pin::new_unchecked(v) }
+}
+
+/// Create a [`NonNull`] from a reference.
+///
+/// This is a backport of [`core::ptr::NonNull::from_ref()`].
+pub fn nonnull_from_ref<T: ?Sized>(v: &T) -> core::ptr::NonNull<T> {
+    // SAFETY: A reference cannot be NULL.
+    unsafe { core::ptr::NonNull::new_unchecked(core::ptr::from_ref(v).cast_mut()) }
+}
+
+/// Create a [`NonNull`] from a reference.
+///
+/// This is a backport of [`core::ptr::NonNull::from_mut()`].
+pub fn nonnull_from_mut<T: ?Sized>(v: &mut T) -> core::ptr::NonNull<T> {
+    // SAFETY: A reference cannot be NULL.
+    unsafe { core::ptr::NonNull::new_unchecked(v) }
+}
+
+/// Return the memory address part of a pointer without exposing provenance.
+///
+/// This returns the same value as an `as usize` cast. However, this function
+/// is meant to not expose provenance, and rather behave like
+/// `<*mut T>::addr()`. Unfortunately, the latter requires an MSRV of 1.84,
+/// which is not yet available upstream. Until then, this serves as a
+/// replacement.
+pub fn ptr_addr<T: ?Sized>(v: *const T) -> usize {
+    // Simply expose the provenance until. A transmute would avoid the
+    // exposition, but is not a stable API.
+    v.cast::<()>() as usize
+}
+
+/// Compare two pointers.
+///
+/// This is equivalent to `<*const T as Ord>::cmp()`. Unlike the trait-based
+/// solution, this has fixed pointer types and thus can be called with
+/// references, which are then coerced to pointers.
+///
+/// This serves the same purpose as `core::ptr::eq()`, but for `Ord` rather
+/// than `Eq`.
+pub fn ptr_cmp<T: ?Sized>(a: *const T, b: *const T) -> core::cmp::Ordering {
+    // Even though `PartialOrd for *mut T` documents that it uses
+    // `<*mut T>::addr()` for comparisons, clippy still warns about it. Cast
+    // to `()` to ensure metadata is ignored.
+    a.cast::<()>().cmp(&b.cast::<()>())
+}
-- 
2.53.0