rust: types: introduce ReadableFromBytes trait

If a type `T` implements this trait, it's possible to safely get a
shared reference to a `T` from a byte slice.

This commit also provides a macro that allows the automatic derivation
of `ReadableFromBytes` for simple structs that whose fields all
implement `ReadableFromBytes` as well.

Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>

Author: wedsonaf

rust/kernel/types.rs

@@ -7,7 +7,7 @@ use alloc::boxed::Box;
 use core::{
     cell::UnsafeCell,
     marker::{PhantomData, PhantomPinned},
-    mem::MaybeUninit,
+    mem::{align_of, size_of, MaybeUninit},
     ops::{Deref, DerefMut},
     ptr::NonNull,
 };
@@ -440,3 +440,96 @@ impl<T: LittleEndian + Copy> core::convert::From<T> for LE<T> {
         LE(value.to_le())
     }
 }
+
+/// Specifies that a type is safely readable from byte slices.
+///
+/// Not all types can be safely read from byte slices; examples from
+/// <https://doc.rust-lang.org/reference/behavior-considered-undefined.html> include `bool`
+/// that must be either `0` or `1`, and `char` that cannot be a surrogate or above `char::MAX`.
+///
+/// # Safety
+///
+/// Implementers must ensure that the type is made up only of types that can be safely read from
+/// arbitrary byte sequences (e.g., `u32`, `u64`, etc.).
+pub unsafe trait ReadableFromBytes: Sized {
+    /// Converts the given byte slice into a shared reference to [`Self`].
+    ///
+    /// It fails if the size or alignment requirements are not satisfied.
+    fn from_bytes(data: &[u8], offset: usize) -> Option<&Self> {
+        if offset > data.len() {
+            return None;
+        }
+        let ptr = &data[offset] as *const u8;
+        if ptr as usize % align_of::<Self>() != 0 || data.len() - offset < size_of::<Self>() {
+            return None;
+        }
+        // SAFETY: The memory is valid for read because we have a reference to it. We have just
+        // checked the minimum size and alignment as well.
+        Some(unsafe { &*ptr.cast() })
+    }
+
+    /// Converts the given byte slice into a shared slice of [`Self`].
+    ///
+    /// It fails if the size or alignment requirements are not satisfied.
+    fn from_bytes_to_slice(data: &[u8]) -> Option<&[Self]> {
+        let ptr = &data[0] as *const u8;
+        if ptr as usize % align_of::<Self>() != 0 {
+            return None;
+        }
+        // SAFETY: The memory is valid for read because we have a reference to it. We have just
+        // checked the minimum alignment as well, and the length of the slice is calculated from
+        // the length of `Self`.
+        Some(unsafe { core::slice::from_raw_parts(ptr.cast(), data.len() / size_of::<Self>()) })
+    }
+}
+
+// SAFETY: All bit patterns are acceptable values of the types below.
+unsafe impl ReadableFromBytes for u8 {}
+unsafe impl ReadableFromBytes for u16 {}
+unsafe impl ReadableFromBytes for u32 {}
+unsafe impl ReadableFromBytes for u64 {}
+unsafe impl ReadableFromBytes for usize {}
+unsafe impl ReadableFromBytes for i8 {}
+unsafe impl ReadableFromBytes for i16 {}
+unsafe impl ReadableFromBytes for i32 {}
+unsafe impl ReadableFromBytes for i64 {}
+unsafe impl ReadableFromBytes for isize {}
+unsafe impl<T: ReadableFromBytes> ReadableFromBytes for &[T] {}
+unsafe impl<const N: usize, T: ReadableFromBytes> ReadableFromBytes for [T; N] {}
+unsafe impl<T: ReadableFromBytes + Copy + LittleEndian> ReadableFromBytes for LE<T> {}
+
+/// Derive [`ReadableFromBytes`] for the struct defined.
+///
+/// # Examples
+///
+/// ```
+/// kernel::derive_readable_from_bytes! {
+///     #[repr(C)]
+///     struct Inode {
+///         a: u16,
+///         b: u16,
+///         c: u32,
+///     }
+/// }
+/// ```
+#[macro_export]
+macro_rules! derive_readable_from_bytes {
+    ($($(#[$outer:meta])* $outerv:vis struct $name:ident {
+        $($(#[$m:meta])* $v:vis $id:ident : $t:ty),* $(,)?
+    })*)=> {
+        $(
+            $(#[$outer])*
+            $outerv struct $name {
+                $(
+                    $(#[$m])*
+                    $v $id: $t,
+                )*
+            }
+            unsafe impl $crate::types::ReadableFromBytes for $name {}
+            const _: () = {
+                const fn is_readable_from_bytes<T: $crate::types::ReadableFromBytes>() {}
+                $(is_readable_from_bytes::<$t>();)*
+            };
+        )*
+    };
+}