| // Copyright 2023 The Fuchsia Authors |
| // |
| // Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0 |
| // <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT |
| // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. |
| // This file may not be copied, modified, or distributed except according to |
| // those terms. |
| |
| use core::{ |
| cmp::Ordering, |
| fmt::{self, Debug, Display, Formatter}, |
| hash::Hash, |
| mem::{self, ManuallyDrop}, |
| ops::{Deref, DerefMut}, |
| ptr, |
| }; |
| |
| use super::*; |
| |
| /// A type with no alignment requirement. |
| /// |
| /// An `Unalign` wraps a `T`, removing any alignment requirement. `Unalign<T>` |
| /// has the same size and bit validity as `T`, but not necessarily the same |
| /// alignment [or ABI]. This is useful if a type with an alignment requirement |
| /// needs to be read from a chunk of memory which provides no alignment |
| /// guarantees. |
| /// |
| /// Since `Unalign` has no alignment requirement, the inner `T` may not be |
| /// properly aligned in memory. There are five ways to access the inner `T`: |
| /// - by value, using [`get`] or [`into_inner`] |
| /// - by reference inside of a callback, using [`update`] |
| /// - fallibly by reference, using [`try_deref`] or [`try_deref_mut`]; these can |
| /// fail if the `Unalign` does not satisfy `T`'s alignment requirement at |
| /// runtime |
| /// - unsafely by reference, using [`deref_unchecked`] or |
| /// [`deref_mut_unchecked`]; it is the caller's responsibility to ensure that |
| /// the `Unalign` satisfies `T`'s alignment requirement |
| /// - (where `T: Unaligned`) infallibly by reference, using [`Deref::deref`] or |
| /// [`DerefMut::deref_mut`] |
| /// |
| /// [or ABI]: https://github.com/google/zerocopy/issues/164 |
| /// [`get`]: Unalign::get |
| /// [`into_inner`]: Unalign::into_inner |
| /// [`update`]: Unalign::update |
| /// [`try_deref`]: Unalign::try_deref |
| /// [`try_deref_mut`]: Unalign::try_deref_mut |
| /// [`deref_unchecked`]: Unalign::deref_unchecked |
| /// [`deref_mut_unchecked`]: Unalign::deref_mut_unchecked |
| // NOTE: This type is sound to use with types that need to be dropped. The |
| // reason is that the compiler-generated drop code automatically moves all |
| // values to aligned memory slots before dropping them in-place. This is not |
| // well-documented, but it's hinted at in places like [1] and [2]. However, this |
| // also means that `T` must be `Sized`; unless something changes, we can never |
| // support unsized `T`. [3] |
| // |
| // [1] https://github.com/rust-lang/rust/issues/54148#issuecomment-420529646 |
| // [2] https://github.com/google/zerocopy/pull/126#discussion_r1018512323 |
| // [3] https://github.com/google/zerocopy/issues/209 |
| #[allow(missing_debug_implementations)] |
| #[derive(Default, Copy)] |
| #[cfg_attr( |
| any(feature = "derive", test), |
| derive(KnownLayout, FromZeroes, FromBytes, AsBytes, Unaligned) |
| )] |
| #[repr(C, packed)] |
| pub struct Unalign<T>(T); |
| |
| #[cfg(not(any(feature = "derive", test)))] |
| impl_known_layout!(T => Unalign<T>); |
| |
| safety_comment! { |
| /// SAFETY: |
| /// - `Unalign<T>` is `repr(packed)`, so it is unaligned regardless of the |
| /// alignment of `T`, and so we don't require that `T: Unaligned` |
| /// - `Unalign<T>` has the same bit validity as `T`, and so it is |
| /// `FromZeroes`, `FromBytes`, or `AsBytes` exactly when `T` is as well. |
| impl_or_verify!(T => Unaligned for Unalign<T>); |
| impl_or_verify!(T: FromZeroes => FromZeroes for Unalign<T>); |
| impl_or_verify!(T: FromBytes => FromBytes for Unalign<T>); |
| impl_or_verify!(T: AsBytes => AsBytes for Unalign<T>); |
| } |
| |
| // Note that `Unalign: Clone` only if `T: Copy`. Since the inner `T` may not be |
| // aligned, there's no way to safely call `T::clone`, and so a `T: Clone` bound |
| // is not sufficient to implement `Clone` for `Unalign`. |
| impl<T: Copy> Clone for Unalign<T> { |
| #[inline(always)] |
| fn clone(&self) -> Unalign<T> { |
| *self |
| } |
| } |
| |
| impl<T> Unalign<T> { |
| /// Constructs a new `Unalign`. |
| #[inline(always)] |
| pub const fn new(val: T) -> Unalign<T> { |
| Unalign(val) |
| } |
| |
| /// Consumes `self`, returning the inner `T`. |
| #[inline(always)] |
| pub const fn into_inner(self) -> T { |
| // Use this instead of `mem::transmute` since the latter can't tell |
| // that `Unalign<T>` and `T` have the same size. |
| #[repr(C)] |
| union Transmute<T> { |
| u: ManuallyDrop<Unalign<T>>, |
| t: ManuallyDrop<T>, |
| } |
| |
| // SAFETY: Since `Unalign` is `#[repr(C, packed)]`, it has the same |
| // layout as `T`. `ManuallyDrop<U>` is guaranteed to have the same |
| // layout as `U`, and so `ManuallyDrop<Unalign<T>>` has the same layout |
| // as `ManuallyDrop<T>`. Since `Transmute<T>` is `#[repr(C)]`, its `t` |
| // and `u` fields both start at the same offset (namely, 0) within the |
| // union. |
| // |
| // We do this instead of just destructuring in order to prevent |
| // `Unalign`'s `Drop::drop` from being run, since dropping is not |
| // supported in `const fn`s. |
| // |
| // TODO(https://github.com/rust-lang/rust/issues/73255): Destructure |
| // instead of using unsafe. |
| unsafe { ManuallyDrop::into_inner(Transmute { u: ManuallyDrop::new(self) }.t) } |
| } |
| |
| /// Attempts to return a reference to the wrapped `T`, failing if `self` is |
| /// not properly aligned. |
| /// |
| /// If `self` does not satisfy `mem::align_of::<T>()`, then it is unsound to |
| /// return a reference to the wrapped `T`, and `try_deref` returns `None`. |
| /// |
| /// If `T: Unaligned`, then `Unalign<T>` implements [`Deref`], and callers |
| /// may prefer [`Deref::deref`], which is infallible. |
| #[inline(always)] |
| pub fn try_deref(&self) -> Option<&T> { |
| if !crate::util::aligned_to::<_, T>(self) { |
| return None; |
| } |
| |
| // SAFETY: `deref_unchecked`'s safety requirement is that `self` is |
| // aligned to `align_of::<T>()`, which we just checked. |
| unsafe { Some(self.deref_unchecked()) } |
| } |
| |
| /// Attempts to return a mutable reference to the wrapped `T`, failing if |
| /// `self` is not properly aligned. |
| /// |
| /// If `self` does not satisfy `mem::align_of::<T>()`, then it is unsound to |
| /// return a reference to the wrapped `T`, and `try_deref_mut` returns |
| /// `None`. |
| /// |
| /// If `T: Unaligned`, then `Unalign<T>` implements [`DerefMut`], and |
| /// callers may prefer [`DerefMut::deref_mut`], which is infallible. |
| #[inline(always)] |
| pub fn try_deref_mut(&mut self) -> Option<&mut T> { |
| if !crate::util::aligned_to::<_, T>(&*self) { |
| return None; |
| } |
| |
| // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is |
| // aligned to `align_of::<T>()`, which we just checked. |
| unsafe { Some(self.deref_mut_unchecked()) } |
| } |
| |
| /// Returns a reference to the wrapped `T` without checking alignment. |
| /// |
| /// If `T: Unaligned`, then `Unalign<T>` implements[ `Deref`], and callers |
| /// may prefer [`Deref::deref`], which is safe. |
| /// |
| /// # Safety |
| /// |
| /// If `self` does not satisfy `mem::align_of::<T>()`, then |
| /// `self.deref_unchecked()` may cause undefined behavior. |
| #[inline(always)] |
| pub const unsafe fn deref_unchecked(&self) -> &T { |
| // SAFETY: `Unalign<T>` is `repr(transparent)`, so there is a valid `T` |
| // at the same memory location as `self`. It has no alignment guarantee, |
| // but the caller has promised that `self` is properly aligned, so we |
| // know that it is sound to create a reference to `T` at this memory |
| // location. |
| // |
| // We use `mem::transmute` instead of `&*self.get_ptr()` because |
| // dereferencing pointers is not stable in `const` on our current MSRV |
| // (1.56 as of this writing). |
| unsafe { mem::transmute(self) } |
| } |
| |
| /// Returns a mutable reference to the wrapped `T` without checking |
| /// alignment. |
| /// |
| /// If `T: Unaligned`, then `Unalign<T>` implements[ `DerefMut`], and |
| /// callers may prefer [`DerefMut::deref_mut`], which is safe. |
| /// |
| /// # Safety |
| /// |
| /// If `self` does not satisfy `mem::align_of::<T>()`, then |
| /// `self.deref_mut_unchecked()` may cause undefined behavior. |
| #[inline(always)] |
| pub unsafe fn deref_mut_unchecked(&mut self) -> &mut T { |
| // SAFETY: `self.get_mut_ptr()` returns a raw pointer to a valid `T` at |
| // the same memory location as `self`. It has no alignment guarantee, |
| // but the caller has promised that `self` is properly aligned, so we |
| // know that the pointer itself is aligned, and thus that it is sound to |
| // create a reference to a `T` at this memory location. |
| unsafe { &mut *self.get_mut_ptr() } |
| } |
| |
| /// Gets an unaligned raw pointer to the inner `T`. |
| /// |
| /// # Safety |
| /// |
| /// The returned raw pointer is not necessarily aligned to |
| /// `align_of::<T>()`. Most functions which operate on raw pointers require |
| /// those pointers to be aligned, so calling those functions with the result |
| /// of `get_ptr` will be undefined behavior if alignment is not guaranteed |
| /// using some out-of-band mechanism. In general, the only functions which |
| /// are safe to call with this pointer are those which are explicitly |
| /// documented as being sound to use with an unaligned pointer, such as |
| /// [`read_unaligned`]. |
| /// |
| /// [`read_unaligned`]: core::ptr::read_unaligned |
| #[inline(always)] |
| pub const fn get_ptr(&self) -> *const T { |
| ptr::addr_of!(self.0) |
| } |
| |
| /// Gets an unaligned mutable raw pointer to the inner `T`. |
| /// |
| /// # Safety |
| /// |
| /// The returned raw pointer is not necessarily aligned to |
| /// `align_of::<T>()`. Most functions which operate on raw pointers require |
| /// those pointers to be aligned, so calling those functions with the result |
| /// of `get_ptr` will be undefined behavior if alignment is not guaranteed |
| /// using some out-of-band mechanism. In general, the only functions which |
| /// are safe to call with this pointer are those which are explicitly |
| /// documented as being sound to use with an unaligned pointer, such as |
| /// [`read_unaligned`]. |
| /// |
| /// [`read_unaligned`]: core::ptr::read_unaligned |
| // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`. |
| #[inline(always)] |
| pub fn get_mut_ptr(&mut self) -> *mut T { |
| ptr::addr_of_mut!(self.0) |
| } |
| |
| /// Sets the inner `T`, dropping the previous value. |
| // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`. |
| #[inline(always)] |
| pub fn set(&mut self, t: T) { |
| *self = Unalign::new(t); |
| } |
| |
| /// Updates the inner `T` by calling a function on it. |
| /// |
| /// If [`T: Unaligned`], then `Unalign<T>` implements [`DerefMut`], and that |
| /// impl should be preferred over this method when performing updates, as it |
| /// will usually be faster and more ergonomic. |
| /// |
| /// For large types, this method may be expensive, as it requires copying |
| /// `2 * size_of::<T>()` bytes. \[1\] |
| /// |
| /// \[1\] Since the inner `T` may not be aligned, it would not be sound to |
| /// invoke `f` on it directly. Instead, `update` moves it into a |
| /// properly-aligned location in the local stack frame, calls `f` on it, and |
| /// then moves it back to its original location in `self`. |
| /// |
| /// [`T: Unaligned`]: Unaligned |
| #[inline] |
| pub fn update<O, F: FnOnce(&mut T) -> O>(&mut self, f: F) -> O { |
| // On drop, this moves `copy` out of itself and uses `ptr::write` to |
| // overwrite `slf`. |
| struct WriteBackOnDrop<T> { |
| copy: ManuallyDrop<T>, |
| slf: *mut Unalign<T>, |
| } |
| |
| impl<T> Drop for WriteBackOnDrop<T> { |
| fn drop(&mut self) { |
| // SAFETY: We never use `copy` again as required by |
| // `ManuallyDrop::take`. |
| let copy = unsafe { ManuallyDrop::take(&mut self.copy) }; |
| // SAFETY: `slf` is the raw pointer value of `self`. We know it |
| // is valid for writes and properly aligned because `self` is a |
| // mutable reference, which guarantees both of these properties. |
| unsafe { ptr::write(self.slf, Unalign::new(copy)) }; |
| } |
| } |
| |
| // SAFETY: We know that `self` is valid for reads, properly aligned, and |
| // points to an initialized `Unalign<T>` because it is a mutable |
| // reference, which guarantees all of these properties. |
| // |
| // Since `T: !Copy`, it would be unsound in the general case to allow |
| // both the original `Unalign<T>` and the copy to be used by safe code. |
| // We guarantee that the copy is used to overwrite the original in the |
| // `Drop::drop` impl of `WriteBackOnDrop`. So long as this `drop` is |
| // called before any other safe code executes, soundness is upheld. |
| // While this method can terminate in two ways (by returning normally or |
| // by unwinding due to a panic in `f`), in both cases, `write_back` is |
| // dropped - and its `drop` called - before any other safe code can |
| // execute. |
| let copy = unsafe { ptr::read(self) }.into_inner(); |
| let mut write_back = WriteBackOnDrop { copy: ManuallyDrop::new(copy), slf: self }; |
| |
| let ret = f(&mut write_back.copy); |
| |
| drop(write_back); |
| ret |
| } |
| } |
| |
| impl<T: Copy> Unalign<T> { |
| /// Gets a copy of the inner `T`. |
| // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`. |
| #[inline(always)] |
| pub fn get(&self) -> T { |
| let Unalign(val) = *self; |
| val |
| } |
| } |
| |
| impl<T: Unaligned> Deref for Unalign<T> { |
| type Target = T; |
| |
| #[inline(always)] |
| fn deref(&self) -> &T { |
| // SAFETY: `deref_unchecked`'s safety requirement is that `self` is |
| // aligned to `align_of::<T>()`. `T: Unaligned` guarantees that |
| // `align_of::<T>() == 1`, and all pointers are one-aligned because all |
| // addresses are divisible by 1. |
| unsafe { self.deref_unchecked() } |
| } |
| } |
| |
| impl<T: Unaligned> DerefMut for Unalign<T> { |
| #[inline(always)] |
| fn deref_mut(&mut self) -> &mut T { |
| // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is |
| // aligned to `align_of::<T>()`. `T: Unaligned` guarantees that |
| // `align_of::<T>() == 1`, and all pointers are one-aligned because all |
| // addresses are divisible by 1. |
| unsafe { self.deref_mut_unchecked() } |
| } |
| } |
| |
| impl<T: Unaligned + PartialOrd> PartialOrd<Unalign<T>> for Unalign<T> { |
| #[inline(always)] |
| fn partial_cmp(&self, other: &Unalign<T>) -> Option<Ordering> { |
| PartialOrd::partial_cmp(self.deref(), other.deref()) |
| } |
| } |
| |
| impl<T: Unaligned + Ord> Ord for Unalign<T> { |
| #[inline(always)] |
| fn cmp(&self, other: &Unalign<T>) -> Ordering { |
| Ord::cmp(self.deref(), other.deref()) |
| } |
| } |
| |
| impl<T: Unaligned + PartialEq> PartialEq<Unalign<T>> for Unalign<T> { |
| #[inline(always)] |
| fn eq(&self, other: &Unalign<T>) -> bool { |
| PartialEq::eq(self.deref(), other.deref()) |
| } |
| } |
| |
| impl<T: Unaligned + Eq> Eq for Unalign<T> {} |
| |
| impl<T: Unaligned + Hash> Hash for Unalign<T> { |
| #[inline(always)] |
| fn hash<H>(&self, state: &mut H) |
| where |
| H: Hasher, |
| { |
| self.deref().hash(state); |
| } |
| } |
| |
| impl<T: Unaligned + Debug> Debug for Unalign<T> { |
| #[inline(always)] |
| fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { |
| Debug::fmt(self.deref(), f) |
| } |
| } |
| |
| impl<T: Unaligned + Display> Display for Unalign<T> { |
| #[inline(always)] |
| fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { |
| Display::fmt(self.deref(), f) |
| } |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| use core::panic::AssertUnwindSafe; |
| |
| use super::*; |
| use crate::util::testutil::*; |
| |
| /// A `T` which is guaranteed not to satisfy `align_of::<A>()`. |
| /// |
| /// It must be the case that `align_of::<T>() < align_of::<A>()` in order |
| /// fot this type to work properly. |
| #[repr(C)] |
| struct ForceUnalign<T, A> { |
| // The outer struct is aligned to `A`, and, thanks to `repr(C)`, `t` is |
| // placed at the minimum offset that guarantees its alignment. If |
| // `align_of::<T>() < align_of::<A>()`, then that offset will be |
| // guaranteed *not* to satisfy `align_of::<A>()`. |
| _u: u8, |
| t: T, |
| _a: [A; 0], |
| } |
| |
| impl<T, A> ForceUnalign<T, A> { |
| const fn new(t: T) -> ForceUnalign<T, A> { |
| ForceUnalign { _u: 0, t, _a: [] } |
| } |
| } |
| |
| #[test] |
| fn test_unalign() { |
| // Test methods that don't depend on alignment. |
| let mut u = Unalign::new(AU64(123)); |
| assert_eq!(u.get(), AU64(123)); |
| assert_eq!(u.into_inner(), AU64(123)); |
| assert_eq!(u.get_ptr(), <*const _>::cast::<AU64>(&u)); |
| assert_eq!(u.get_mut_ptr(), <*mut _>::cast::<AU64>(&mut u)); |
| u.set(AU64(321)); |
| assert_eq!(u.get(), AU64(321)); |
| |
| // Test methods that depend on alignment (when alignment is satisfied). |
| let mut u: Align<_, AU64> = Align::new(Unalign::new(AU64(123))); |
| assert_eq!(u.t.try_deref(), Some(&AU64(123))); |
| assert_eq!(u.t.try_deref_mut(), Some(&mut AU64(123))); |
| // SAFETY: The `Align<_, AU64>` guarantees proper alignment. |
| assert_eq!(unsafe { u.t.deref_unchecked() }, &AU64(123)); |
| // SAFETY: The `Align<_, AU64>` guarantees proper alignment. |
| assert_eq!(unsafe { u.t.deref_mut_unchecked() }, &mut AU64(123)); |
| *u.t.try_deref_mut().unwrap() = AU64(321); |
| assert_eq!(u.t.get(), AU64(321)); |
| |
| // Test methods that depend on alignment (when alignment is not |
| // satisfied). |
| let mut u: ForceUnalign<_, AU64> = ForceUnalign::new(Unalign::new(AU64(123))); |
| assert_eq!(u.t.try_deref(), None); |
| assert_eq!(u.t.try_deref_mut(), None); |
| |
| // Test methods that depend on `T: Unaligned`. |
| let mut u = Unalign::new(123u8); |
| assert_eq!(u.try_deref(), Some(&123)); |
| assert_eq!(u.try_deref_mut(), Some(&mut 123)); |
| assert_eq!(u.deref(), &123); |
| assert_eq!(u.deref_mut(), &mut 123); |
| *u = 21; |
| assert_eq!(u.get(), 21); |
| |
| // Test that some `Unalign` functions and methods are `const`. |
| const _UNALIGN: Unalign<u64> = Unalign::new(0); |
| const _UNALIGN_PTR: *const u64 = _UNALIGN.get_ptr(); |
| const _U64: u64 = _UNALIGN.into_inner(); |
| // Make sure all code is considered "used". |
| // |
| // TODO(https://github.com/rust-lang/rust/issues/104084): Remove this |
| // attribute. |
| #[allow(dead_code)] |
| const _: () = { |
| let x: Align<_, AU64> = Align::new(Unalign::new(AU64(123))); |
| // Make sure that `deref_unchecked` is `const`. |
| // |
| // SAFETY: The `Align<_, AU64>` guarantees proper alignment. |
| let au64 = unsafe { x.t.deref_unchecked() }; |
| match au64 { |
| AU64(123) => {} |
| _ => unreachable!(), |
| } |
| }; |
| } |
| |
| #[test] |
| fn test_unalign_update() { |
| let mut u = Unalign::new(AU64(123)); |
| u.update(|a| a.0 += 1); |
| assert_eq!(u.get(), AU64(124)); |
| |
| // Test that, even if the callback panics, the original is still |
| // correctly overwritten. Use a `Box` so that Miri is more likely to |
| // catch any unsoundness (which would likely result in two `Box`es for |
| // the same heap object, which is the sort of thing that Miri would |
| // probably catch). |
| let mut u = Unalign::new(Box::new(AU64(123))); |
| let res = std::panic::catch_unwind(AssertUnwindSafe(|| { |
| u.update(|a| { |
| a.0 += 1; |
| panic!(); |
| }) |
| })); |
| assert!(res.is_err()); |
| assert_eq!(u.into_inner(), Box::new(AU64(124))); |
| } |
| } |
