diff --git a/src/derive_util.rs b/src/derive_util.rs index 003be093ec..edf88e3bd7 100644 --- a/src/derive_util.rs +++ b/src/derive_util.rs @@ -65,7 +65,7 @@ macro_rules! union_has_padding { #[cfg(test)] mod tests { - use crate::testutil::*; + use crate::util::testutil::*; #[test] fn test_struct_has_padding() { diff --git a/src/lib.rs b/src/lib.rs index 5e416b583b..fe425a5da4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -155,17 +155,19 @@ #[macro_use] mod macros; -#[cfg(test)] -mod testutil; #[cfg(feature = "byteorder")] pub mod byteorder; #[cfg(any(feature = "derive", test))] #[doc(hidden)] pub mod derive_util; +// TODO(#252): If we make this pub, come up with a better name. +mod util; +mod wrappers; #[cfg(feature = "byteorder")] pub use crate::byteorder::*; +pub use crate::wrappers::*; #[cfg(any(feature = "derive", test))] pub use zerocopy_derive::*; @@ -173,7 +175,7 @@ use core::{ cell::{self, RefMut}, cmp::Ordering, fmt::{self, Debug, Display, Formatter}, - hash::{Hash, Hasher}, + hash::Hasher, marker::PhantomData, mem::{self, ManuallyDrop, MaybeUninit}, num::{ @@ -1202,359 +1204,6 @@ mod simd { simd_arch_mod!(arm, int8x4_t, uint8x4_t); } -/// A type with no alignment requirement. -/// -/// An `Unalign` wraps a `T`, removing any alignment requirement. `Unalign` -/// 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(Unaligned, FromZeroes, FromBytes, AsBytes))] -#[repr(C, packed)] -pub struct Unalign(T); - -safety_comment! { - /// SAFETY: - /// - `Unalign` is `repr(packed)`, so it is unaligned regardless of the - /// alignment of `T`, and so we don't require that `T: Unaligned` - /// - `Unalign` 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); - impl_or_verify!(T: FromZeroes => FromZeroes for Unalign); - impl_or_verify!(T: FromBytes => FromBytes for Unalign); - impl_or_verify!(T: AsBytes => AsBytes for Unalign); -} - -// 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 Clone for Unalign { - fn clone(&self) -> Unalign { - *self - } -} - -impl Unalign { - /// Constructs a new `Unalign`. - pub const fn new(val: T) -> Unalign { - Unalign(val) - } - - /// Consumes `self`, returning the inner `T`. - pub const fn into_inner(self) -> T { - // Use this instead of `mem::transmute` since the latter can't tell - // that `Unalign` and `T` have the same size. - #[repr(C)] - union Transmute { - u: ManuallyDrop>, - t: ManuallyDrop, - } - - // SAFETY: Since `Unalign` is `#[repr(C, packed)]`, it has the same - // layout as `T`. `ManuallyDrop` is guaranteed to have the same - // layout as `U`, and so `ManuallyDrop>` has the same layout - // as `ManuallyDrop`. Since `Transmute` 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::()`, then it is unsound to - /// return a reference to the wrapped `T`, and `try_deref` returns `None`. - /// - /// If `T: Unaligned`, then `Unalign` implements [`Deref`], and callers - /// may prefer [`Deref::deref`], which is infallible. - pub fn try_deref(&self) -> Option<&T> { - if !aligned_to::<_, T>(self) { - return None; - } - - // SAFETY: `deref_unchecked`'s safety requirement is that `self` is - // aligned to `align_of::()`, 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::()`, then it is unsound to - /// return a reference to the wrapped `T`, and `try_deref_mut` returns - /// `None`. - /// - /// If `T: Unaligned`, then `Unalign` implements [`DerefMut`], and - /// callers may prefer [`DerefMut::deref_mut`], which is infallible. - pub fn try_deref_mut(&mut self) -> Option<&mut T> { - if !aligned_to::<_, T>(&*self) { - return None; - } - - // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is - // aligned to `align_of::()`, 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` implements[ `Deref`], and callers - /// may prefer [`Deref::deref`], which is safe. - /// - /// # Safety - /// - /// If `self` does not satisfy `mem::align_of::()`, then - /// `self.deref_unchecked()` may cause undefined behavior. - pub const unsafe fn deref_unchecked(&self) -> &T { - // SAFETY: `Unalign` 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` implements[ `DerefMut`], and - /// callers may prefer [`DerefMut::deref_mut`], which is safe. - /// - /// # Safety - /// - /// If `self` does not satisfy `mem::align_of::()`, then - /// `self.deref_mut_unchecked()` may cause undefined behavior. - 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::()`. 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 - 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::()`. 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`. - 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`. - 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` 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::()` 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 - pub fn update O>(&mut self, f: F) -> O { - // On drop, this moves `copy` out of itself and uses `ptr::write` to - // overwrite `slf`. - struct WriteBackOnDrop { - copy: ManuallyDrop, - slf: *mut Unalign, - } - - impl Drop for WriteBackOnDrop { - fn drop(&mut self) { - // SAFETY: See inline comments. - unsafe { - // SAFETY: We never use `copy` again as required by - // `ManuallyDrop::take`. - let copy = 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. - ptr::write(self.slf, Unalign::new(copy)); - } - } - } - - // SAFETY: We know that `self` is valid for reads, properly aligned, and - // points to an initialized `Unalign` 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` 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 Unalign { - /// Gets a copy of the inner `T`. - // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`. - pub fn get(&self) -> T { - let Unalign(val) = *self; - val - } -} - -impl Deref for Unalign { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: `deref_unchecked`'s safety requirement is that `self` is - // aligned to `align_of::()`. `T: Unaligned` guarantees that - // `align_of::() == 1`, and all pointers are one-aligned because all - // addresses are divisible by 1. - unsafe { self.deref_unchecked() } - } -} - -impl DerefMut for Unalign { - fn deref_mut(&mut self) -> &mut T { - // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is - // aligned to `align_of::()`. `T: Unaligned` guarantees that - // `align_of::() == 1`, and all pointers are one-aligned because all - // addresses are divisible by 1. - unsafe { self.deref_mut_unchecked() } - } -} - -impl PartialOrd> for Unalign { - fn partial_cmp(&self, other: &Unalign) -> Option { - PartialOrd::partial_cmp(self.deref(), other.deref()) - } -} - -impl Ord for Unalign { - fn cmp(&self, other: &Unalign) -> Ordering { - Ord::cmp(self.deref(), other.deref()) - } -} - -impl PartialEq> for Unalign { - fn eq(&self, other: &Unalign) -> bool { - PartialEq::eq(self.deref(), other.deref()) - } -} - -impl Eq for Unalign {} - -impl Hash for Unalign { - fn hash(&self, state: &mut H) - where - H: Hasher, - { - self.deref().hash(state); - } -} - -impl Debug for Unalign { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - Debug::fmt(self.deref(), f) - } -} - -impl Display for Unalign { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - Display::fmt(self.deref(), f) - } -} - // Used in `transmute!` below. #[doc(hidden)] pub use core::mem::transmute as __real_transmute; @@ -1669,7 +1318,7 @@ where /// these checks fail, it returns `None`. #[inline] pub fn new(bytes: B) -> Option> { - if bytes.len() != mem::size_of::() || !aligned_to::<_, T>(bytes.deref()) { + if bytes.len() != mem::size_of::() || !util::aligned_to::<_, T>(bytes.deref()) { return None; } Some(Ref(bytes, PhantomData)) @@ -1684,7 +1333,7 @@ where /// checks fail, it returns `None`. #[inline] pub fn new_from_prefix(bytes: B) -> Option<(Ref, B)> { - if bytes.len() < mem::size_of::() || !aligned_to::<_, T>(bytes.deref()) { + if bytes.len() < mem::size_of::() || !util::aligned_to::<_, T>(bytes.deref()) { return None; } let (bytes, suffix) = bytes.split_at(mem::size_of::()); @@ -1704,7 +1353,7 @@ where let bytes_len = bytes.len(); let split_at = bytes_len.checked_sub(mem::size_of::())?; let (prefix, bytes) = bytes.split_at(split_at); - if !aligned_to::<_, T>(bytes.deref()) { + if !util::aligned_to::<_, T>(bytes.deref()) { return None; } Some((prefix, Ref(bytes, PhantomData))) @@ -1731,7 +1380,7 @@ where .len() .checked_rem(mem::size_of::()) .expect("Ref::new_slice called on a zero-sized type"); - if remainder != 0 || !aligned_to::<_, T>(bytes.deref()) { + if remainder != 0 || !util::aligned_to::<_, T>(bytes.deref()) { return None; } Some(Ref(bytes, PhantomData)) @@ -2380,55 +2029,6 @@ where } } -trait AsAddress { - fn addr(self) -> usize; -} - -impl<'a, T: ?Sized> AsAddress for &'a T { - #[inline(always)] - fn addr(self) -> usize { - let ptr: *const T = self; - AsAddress::addr(ptr) - } -} - -impl<'a, T: ?Sized> AsAddress for &'a mut T { - #[inline(always)] - fn addr(self) -> usize { - let ptr: *const T = self; - AsAddress::addr(ptr) - } -} - -impl AsAddress for *const T { - #[inline(always)] - fn addr(self) -> usize { - // TODO(https://github.com/rust-lang/rust/issues/95228): Use `.addr()` - // instead of `as usize` once it's stable, and get rid of this `allow`. - // Currently, `as usize` is the only way to accomplish this. - #[allow(clippy::as_conversions)] - return self.cast::<()>() as usize; - } -} - -impl AsAddress for *mut T { - #[inline(always)] - fn addr(self) -> usize { - let ptr: *const T = self; - AsAddress::addr(ptr) - } -} - -/// Is `t` aligned to `mem::align_of::()`? -#[inline(always)] -fn aligned_to(t: T) -> bool { - // `mem::align_of::()` is guaranteed to return a non-zero value, which in - // turn guarantees that this mod operation will not panic. - #[allow(clippy::arithmetic_side_effects)] - let remainder = t.addr() % mem::align_of::(); - remainder == 0 -} - impl Ref where B: ByteSlice, @@ -3020,52 +2620,12 @@ pub use alloc_support::*; mod tests { #![allow(clippy::unreadable_literal)] - use core::{ops::Deref, panic::AssertUnwindSafe}; + use core::ops::Deref; use static_assertions::assert_impl_all; use super::*; - use crate::testutil::AU64; - - /// A `T` which is aligned to at least `align_of::()`. - #[derive(Default)] - struct Align { - t: T, - _a: [A; 0], - } - - impl Align { - fn set_default(&mut self) { - self.t = T::default(); - } - } - - impl Align { - const fn new(t: T) -> Align { - Align { t, _a: [] } - } - } - - /// A `T` which is guaranteed not to satisfy `align_of::()`. - /// - /// It must be the case that `align_of::() < align_of::()` in order - /// fot this type to work properly. - #[repr(C)] - struct ForceUnalign { - // 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::() < align_of::()`, then that offset will be - // guaranteed *not* to satisfy `align_of::()`. - _u: u8, - t: T, - _a: [A; 0], - } - - impl ForceUnalign { - const fn new(t: T) -> ForceUnalign { - ForceUnalign { _u: 0, t, _a: [] } - } - } + use crate::util::testutil::*; // An unsized type. // @@ -3121,87 +2681,6 @@ mod tests { assert_eq!(s, "\0\0\0\0\0"); } - #[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::(&u)); - assert_eq!(u.get_mut_ptr(), <*mut _>::cast::(&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 = 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))); - } - #[test] fn test_read_write() { const VAL: u64 = 0x12345678; diff --git a/src/testutil.rs b/src/testutil.rs deleted file mode 100644 index f13c3fb6e7..0000000000 --- a/src/testutil.rs +++ /dev/null @@ -1,28 +0,0 @@ -// Copyright 2023 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -use super::*; - -// A `u64` with alignment 8. -// -// Though `u64` has alignment 8 on some platforms, it's not guaranteed. -// By contrast, `AU64` is guaranteed to have alignment 8. -#[derive( - FromZeroes, FromBytes, AsBytes, Eq, PartialEq, Ord, PartialOrd, Default, Debug, Copy, Clone, -)] -#[repr(C, align(8))] -pub(crate) struct AU64(pub(crate) u64); - -impl AU64 { - // Converts `self` using this platform's endianness. - pub(crate) fn to_bytes(self) -> [u8; 8] { - transmute!(self) - } -} - -impl Display for AU64 { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - Display::fmt(&self.0, f) - } -} diff --git a/src/util.rs b/src/util.rs new file mode 100644 index 0000000000..eb9ad3c071 --- /dev/null +++ b/src/util.rs @@ -0,0 +1,103 @@ +// Copyright 2023 The Fuchsia Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +use core::mem; + +pub(crate) trait AsAddress { + fn addr(self) -> usize; +} + +impl<'a, T: ?Sized> AsAddress for &'a T { + #[inline(always)] + fn addr(self) -> usize { + let ptr: *const T = self; + AsAddress::addr(ptr) + } +} + +impl<'a, T: ?Sized> AsAddress for &'a mut T { + #[inline(always)] + fn addr(self) -> usize { + let ptr: *const T = self; + AsAddress::addr(ptr) + } +} + +impl AsAddress for *const T { + #[inline(always)] + fn addr(self) -> usize { + // TODO(https://github.com/rust-lang/rust/issues/95228): Use `.addr()` + // instead of `as usize` once it's stable, and get rid of this `allow`. + // Currently, `as usize` is the only way to accomplish this. + #[allow(clippy::as_conversions)] + return self.cast::<()>() as usize; + } +} + +impl AsAddress for *mut T { + #[inline(always)] + fn addr(self) -> usize { + let ptr: *const T = self; + AsAddress::addr(ptr) + } +} + +/// Is `t` aligned to `mem::align_of::()`? +#[inline(always)] +pub(crate) fn aligned_to(t: T) -> bool { + // `mem::align_of::()` is guaranteed to return a non-zero value, which in + // turn guarantees that this mod operation will not panic. + #[allow(clippy::arithmetic_side_effects)] + let remainder = t.addr() % mem::align_of::(); + remainder == 0 +} + +#[cfg(test)] +pub(crate) mod testutil { + use core::fmt::{self, Display, Formatter}; + + use crate::*; + + /// A `T` which is aligned to at least `align_of::()`. + #[derive(Default)] + pub(crate) struct Align { + pub(crate) t: T, + _a: [A; 0], + } + + impl Align { + pub(crate) fn set_default(&mut self) { + self.t = T::default(); + } + } + + impl Align { + pub(crate) const fn new(t: T) -> Align { + Align { t, _a: [] } + } + } + + // A `u64` with alignment 8. + // + // Though `u64` has alignment 8 on some platforms, it's not guaranteed. + // By contrast, `AU64` is guaranteed to have alignment 8. + #[derive( + FromZeroes, FromBytes, AsBytes, Eq, PartialEq, Ord, PartialOrd, Default, Debug, Copy, Clone, + )] + #[repr(C, align(8))] + pub(crate) struct AU64(pub(crate) u64); + + impl AU64 { + // Converts this `AU64` to bytes using this platform's endianness. + pub(crate) fn to_bytes(self) -> [u8; 8] { + crate::transmute!(self) + } + } + + impl Display for AU64 { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + Display::fmt(&self.0, f) + } + } +} diff --git a/src/wrappers.rs b/src/wrappers.rs new file mode 100644 index 0000000000..fb9b1d553a --- /dev/null +++ b/src/wrappers.rs @@ -0,0 +1,477 @@ +// Copyright 2023 The Fuchsia Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +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` +/// 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(FromZeroes, FromBytes, AsBytes, Unaligned))] +#[repr(C, packed)] +pub struct Unalign(T); + +safety_comment! { + /// SAFETY: + /// - `Unalign` is `repr(packed)`, so it is unaligned regardless of the + /// alignment of `T`, and so we don't require that `T: Unaligned` + /// - `Unalign` 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); + impl_or_verify!(T: FromZeroes => FromZeroes for Unalign); + impl_or_verify!(T: FromBytes => FromBytes for Unalign); + impl_or_verify!(T: AsBytes => AsBytes for Unalign); +} + +// 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 Clone for Unalign { + fn clone(&self) -> Unalign { + *self + } +} + +impl Unalign { + /// Constructs a new `Unalign`. + pub const fn new(val: T) -> Unalign { + Unalign(val) + } + + /// Consumes `self`, returning the inner `T`. + pub const fn into_inner(self) -> T { + // Use this instead of `mem::transmute` since the latter can't tell + // that `Unalign` and `T` have the same size. + #[repr(C)] + union Transmute { + u: ManuallyDrop>, + t: ManuallyDrop, + } + + // SAFETY: Since `Unalign` is `#[repr(C, packed)]`, it has the same + // layout as `T`. `ManuallyDrop` is guaranteed to have the same + // layout as `U`, and so `ManuallyDrop>` has the same layout + // as `ManuallyDrop`. Since `Transmute` 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::()`, then it is unsound to + /// return a reference to the wrapped `T`, and `try_deref` returns `None`. + /// + /// If `T: Unaligned`, then `Unalign` implements [`Deref`], and callers + /// may prefer [`Deref::deref`], which is infallible. + 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::()`, 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::()`, then it is unsound to + /// return a reference to the wrapped `T`, and `try_deref_mut` returns + /// `None`. + /// + /// If `T: Unaligned`, then `Unalign` implements [`DerefMut`], and + /// callers may prefer [`DerefMut::deref_mut`], which is infallible. + 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::()`, 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` implements[ `Deref`], and callers + /// may prefer [`Deref::deref`], which is safe. + /// + /// # Safety + /// + /// If `self` does not satisfy `mem::align_of::()`, then + /// `self.deref_unchecked()` may cause undefined behavior. + pub const unsafe fn deref_unchecked(&self) -> &T { + // SAFETY: `Unalign` 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` implements[ `DerefMut`], and + /// callers may prefer [`DerefMut::deref_mut`], which is safe. + /// + /// # Safety + /// + /// If `self` does not satisfy `mem::align_of::()`, then + /// `self.deref_mut_unchecked()` may cause undefined behavior. + 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::()`. 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 + 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::()`. 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`. + 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`. + 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` 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::()` 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 + pub fn update O>(&mut self, f: F) -> O { + // On drop, this moves `copy` out of itself and uses `ptr::write` to + // overwrite `slf`. + struct WriteBackOnDrop { + copy: ManuallyDrop, + slf: *mut Unalign, + } + + impl Drop for WriteBackOnDrop { + fn drop(&mut self) { + // SAFETY: See inline comments. + unsafe { + // SAFETY: We never use `copy` again as required by + // `ManuallyDrop::take`. + let copy = 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. + ptr::write(self.slf, Unalign::new(copy)); + } + } + } + + // SAFETY: We know that `self` is valid for reads, properly aligned, and + // points to an initialized `Unalign` 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` 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 Unalign { + /// Gets a copy of the inner `T`. + // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`. + pub fn get(&self) -> T { + let Unalign(val) = *self; + val + } +} + +impl Deref for Unalign { + type Target = T; + + fn deref(&self) -> &T { + // SAFETY: `deref_unchecked`'s safety requirement is that `self` is + // aligned to `align_of::()`. `T: Unaligned` guarantees that + // `align_of::() == 1`, and all pointers are one-aligned because all + // addresses are divisible by 1. + unsafe { self.deref_unchecked() } + } +} + +impl DerefMut for Unalign { + fn deref_mut(&mut self) -> &mut T { + // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is + // aligned to `align_of::()`. `T: Unaligned` guarantees that + // `align_of::() == 1`, and all pointers are one-aligned because all + // addresses are divisible by 1. + unsafe { self.deref_mut_unchecked() } + } +} + +impl PartialOrd> for Unalign { + fn partial_cmp(&self, other: &Unalign) -> Option { + PartialOrd::partial_cmp(self.deref(), other.deref()) + } +} + +impl Ord for Unalign { + fn cmp(&self, other: &Unalign) -> Ordering { + Ord::cmp(self.deref(), other.deref()) + } +} + +impl PartialEq> for Unalign { + fn eq(&self, other: &Unalign) -> bool { + PartialEq::eq(self.deref(), other.deref()) + } +} + +impl Eq for Unalign {} + +impl Hash for Unalign { + fn hash(&self, state: &mut H) + where + H: Hasher, + { + self.deref().hash(state); + } +} + +impl Debug for Unalign { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + Debug::fmt(self.deref(), f) + } +} + +impl Display for Unalign { + 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::()`. + /// + /// It must be the case that `align_of::() < align_of::()` in order + /// fot this type to work properly. + #[repr(C)] + struct ForceUnalign { + // 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::() < align_of::()`, then that offset will be + // guaranteed *not* to satisfy `align_of::()`. + _u: u8, + t: T, + _a: [A; 0], + } + + impl ForceUnalign { + const fn new(t: T) -> ForceUnalign { + 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::(&u)); + assert_eq!(u.get_mut_ptr(), <*mut _>::cast::(&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 = 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))); + } +}