1// Copyright 2023 The Fuchsia Authors
2//
3// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
4// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
5// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6// This file may not be copied, modified, or distributed except according to
7// those terms.
8
9use core::{
10 cmp::Ordering,
11 fmt::{self, Debug, Display, Formatter},
12 hash::Hash,
13 mem::{self, ManuallyDrop},
14 ops::{Deref, DerefMut},
15 ptr,
16};
17
18use super::*;
19
20/// A type with no alignment requirement.
21///
22/// An `Unalign` wraps a `T`, removing any alignment requirement. `Unalign<T>`
23/// has the same size and bit validity as `T`, but not necessarily the same
24/// alignment [or ABI]. This is useful if a type with an alignment requirement
25/// needs to be read from a chunk of memory which provides no alignment
26/// guarantees.
27///
28/// Since `Unalign` has no alignment requirement, the inner `T` may not be
29/// properly aligned in memory. There are five ways to access the inner `T`:
30/// - by value, using [`get`] or [`into_inner`]
31/// - by reference inside of a callback, using [`update`]
32/// - fallibly by reference, using [`try_deref`] or [`try_deref_mut`]; these can
33/// fail if the `Unalign` does not satisfy `T`'s alignment requirement at
34/// runtime
35/// - unsafely by reference, using [`deref_unchecked`] or
36/// [`deref_mut_unchecked`]; it is the caller's responsibility to ensure that
37/// the `Unalign` satisfies `T`'s alignment requirement
38/// - (where `T: Unaligned`) infallibly by reference, using [`Deref::deref`] or
39/// [`DerefMut::deref_mut`]
40///
41/// [or ABI]: https://github.com/google/zerocopy/issues/164
42/// [`get`]: Unalign::get
43/// [`into_inner`]: Unalign::into_inner
44/// [`update`]: Unalign::update
45/// [`try_deref`]: Unalign::try_deref
46/// [`try_deref_mut`]: Unalign::try_deref_mut
47/// [`deref_unchecked`]: Unalign::deref_unchecked
48/// [`deref_mut_unchecked`]: Unalign::deref_mut_unchecked
49// NOTE: This type is sound to use with types that need to be dropped. The
50// reason is that the compiler-generated drop code automatically moves all
51// values to aligned memory slots before dropping them in-place. This is not
52// well-documented, but it's hinted at in places like [1] and [2]. However, this
53// also means that `T` must be `Sized`; unless something changes, we can never
54// support unsized `T`. [3]
55//
56// [1] https://github.com/rust-lang/rust/issues/54148#issuecomment-420529646
57// [2] https://github.com/google/zerocopy/pull/126#discussion_r1018512323
58// [3] https://github.com/google/zerocopy/issues/209
59#[allow(missing_debug_implementations)]
60#[derive(Default, Copy)]
61#[cfg_attr(
62 any(feature = "derive", test),
63 derive(KnownLayout, FromZeroes, FromBytes, AsBytes, Unaligned)
64)]
65#[repr(C, packed)]
66pub struct Unalign<T>(T);
67
68#[cfg(not(any(feature = "derive", test)))]
69impl_known_layout!(T => Unalign<T>);
70
71safety_comment! {
72 /// SAFETY:
73 /// - `Unalign<T>` is `repr(packed)`, so it is unaligned regardless of the
74 /// alignment of `T`, and so we don't require that `T: Unaligned`
75 /// - `Unalign<T>` has the same bit validity as `T`, and so it is
76 /// `FromZeroes`, `FromBytes`, or `AsBytes` exactly when `T` is as well.
77 impl_or_verify!(T => Unaligned for Unalign<T>);
78 impl_or_verify!(T: FromZeroes => FromZeroes for Unalign<T>);
79 impl_or_verify!(T: FromBytes => FromBytes for Unalign<T>);
80 impl_or_verify!(T: AsBytes => AsBytes for Unalign<T>);
81}
82
83// Note that `Unalign: Clone` only if `T: Copy`. Since the inner `T` may not be
84// aligned, there's no way to safely call `T::clone`, and so a `T: Clone` bound
85// is not sufficient to implement `Clone` for `Unalign`.
86impl<T: Copy> Clone for Unalign<T> {
87 #[inline(always)]
88 fn clone(&self) -> Unalign<T> {
89 *self
90 }
91}
92
93impl<T> Unalign<T> {
94 /// Constructs a new `Unalign`.
95 #[inline(always)]
96 pub const fn new(val: T) -> Unalign<T> {
97 Unalign(val)
98 }
99
100 /// Consumes `self`, returning the inner `T`.
101 #[inline(always)]
102 pub const fn into_inner(self) -> T {
103 // Use this instead of `mem::transmute` since the latter can't tell
104 // that `Unalign<T>` and `T` have the same size.
105 #[repr(C)]
106 union Transmute<T> {
107 u: ManuallyDrop<Unalign<T>>,
108 t: ManuallyDrop<T>,
109 }
110
111 // SAFETY: Since `Unalign` is `#[repr(C, packed)]`, it has the same
112 // layout as `T`. `ManuallyDrop<U>` is guaranteed to have the same
113 // layout as `U`, and so `ManuallyDrop<Unalign<T>>` has the same layout
114 // as `ManuallyDrop<T>`. Since `Transmute<T>` is `#[repr(C)]`, its `t`
115 // and `u` fields both start at the same offset (namely, 0) within the
116 // union.
117 //
118 // We do this instead of just destructuring in order to prevent
119 // `Unalign`'s `Drop::drop` from being run, since dropping is not
120 // supported in `const fn`s.
121 //
122 // TODO(https://github.com/rust-lang/rust/issues/73255): Destructure
123 // instead of using unsafe.
124 unsafe { ManuallyDrop::into_inner(Transmute { u: ManuallyDrop::new(self) }.t) }
125 }
126
127 /// Attempts to return a reference to the wrapped `T`, failing if `self` is
128 /// not properly aligned.
129 ///
130 /// If `self` does not satisfy `mem::align_of::<T>()`, then it is unsound to
131 /// return a reference to the wrapped `T`, and `try_deref` returns `None`.
132 ///
133 /// If `T: Unaligned`, then `Unalign<T>` implements [`Deref`], and callers
134 /// may prefer [`Deref::deref`], which is infallible.
135 #[inline(always)]
136 pub fn try_deref(&self) -> Option<&T> {
137 if !crate::util::aligned_to::<_, T>(self) {
138 return None;
139 }
140
141 // SAFETY: `deref_unchecked`'s safety requirement is that `self` is
142 // aligned to `align_of::<T>()`, which we just checked.
143 unsafe { Some(self.deref_unchecked()) }
144 }
145
146 /// Attempts to return a mutable reference to the wrapped `T`, failing if
147 /// `self` is not properly aligned.
148 ///
149 /// If `self` does not satisfy `mem::align_of::<T>()`, then it is unsound to
150 /// return a reference to the wrapped `T`, and `try_deref_mut` returns
151 /// `None`.
152 ///
153 /// If `T: Unaligned`, then `Unalign<T>` implements [`DerefMut`], and
154 /// callers may prefer [`DerefMut::deref_mut`], which is infallible.
155 #[inline(always)]
156 pub fn try_deref_mut(&mut self) -> Option<&mut T> {
157 if !crate::util::aligned_to::<_, T>(&*self) {
158 return None;
159 }
160
161 // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is
162 // aligned to `align_of::<T>()`, which we just checked.
163 unsafe { Some(self.deref_mut_unchecked()) }
164 }
165
166 /// Returns a reference to the wrapped `T` without checking alignment.
167 ///
168 /// If `T: Unaligned`, then `Unalign<T>` implements[ `Deref`], and callers
169 /// may prefer [`Deref::deref`], which is safe.
170 ///
171 /// # Safety
172 ///
173 /// If `self` does not satisfy `mem::align_of::<T>()`, then
174 /// `self.deref_unchecked()` may cause undefined behavior.
175 #[inline(always)]
176 pub const unsafe fn deref_unchecked(&self) -> &T {
177 // SAFETY: `Unalign<T>` is `repr(transparent)`, so there is a valid `T`
178 // at the same memory location as `self`. It has no alignment guarantee,
179 // but the caller has promised that `self` is properly aligned, so we
180 // know that it is sound to create a reference to `T` at this memory
181 // location.
182 //
183 // We use `mem::transmute` instead of `&*self.get_ptr()` because
184 // dereferencing pointers is not stable in `const` on our current MSRV
185 // (1.56 as of this writing).
186 unsafe { mem::transmute(self) }
187 }
188
189 /// Returns a mutable reference to the wrapped `T` without checking
190 /// alignment.
191 ///
192 /// If `T: Unaligned`, then `Unalign<T>` implements[ `DerefMut`], and
193 /// callers may prefer [`DerefMut::deref_mut`], which is safe.
194 ///
195 /// # Safety
196 ///
197 /// If `self` does not satisfy `mem::align_of::<T>()`, then
198 /// `self.deref_mut_unchecked()` may cause undefined behavior.
199 #[inline(always)]
200 pub unsafe fn deref_mut_unchecked(&mut self) -> &mut T {
201 // SAFETY: `self.get_mut_ptr()` returns a raw pointer to a valid `T` at
202 // the same memory location as `self`. It has no alignment guarantee,
203 // but the caller has promised that `self` is properly aligned, so we
204 // know that the pointer itself is aligned, and thus that it is sound to
205 // create a reference to a `T` at this memory location.
206 unsafe { &mut *self.get_mut_ptr() }
207 }
208
209 /// Gets an unaligned raw pointer to the inner `T`.
210 ///
211 /// # Safety
212 ///
213 /// The returned raw pointer is not necessarily aligned to
214 /// `align_of::<T>()`. Most functions which operate on raw pointers require
215 /// those pointers to be aligned, so calling those functions with the result
216 /// of `get_ptr` will be undefined behavior if alignment is not guaranteed
217 /// using some out-of-band mechanism. In general, the only functions which
218 /// are safe to call with this pointer are those which are explicitly
219 /// documented as being sound to use with an unaligned pointer, such as
220 /// [`read_unaligned`].
221 ///
222 /// [`read_unaligned`]: core::ptr::read_unaligned
223 #[inline(always)]
224 pub const fn get_ptr(&self) -> *const T {
225 ptr::addr_of!(self.0)
226 }
227
228 /// Gets an unaligned mutable raw pointer to the inner `T`.
229 ///
230 /// # Safety
231 ///
232 /// The returned raw pointer is not necessarily aligned to
233 /// `align_of::<T>()`. Most functions which operate on raw pointers require
234 /// those pointers to be aligned, so calling those functions with the result
235 /// of `get_ptr` will be undefined behavior if alignment is not guaranteed
236 /// using some out-of-band mechanism. In general, the only functions which
237 /// are safe to call with this pointer are those which are explicitly
238 /// documented as being sound to use with an unaligned pointer, such as
239 /// [`read_unaligned`].
240 ///
241 /// [`read_unaligned`]: core::ptr::read_unaligned
242 // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`.
243 #[inline(always)]
244 pub fn get_mut_ptr(&mut self) -> *mut T {
245 ptr::addr_of_mut!(self.0)
246 }
247
248 /// Sets the inner `T`, dropping the previous value.
249 // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`.
250 #[inline(always)]
251 pub fn set(&mut self, t: T) {
252 *self = Unalign::new(t);
253 }
254
255 /// Updates the inner `T` by calling a function on it.
256 ///
257 /// If [`T: Unaligned`], then `Unalign<T>` implements [`DerefMut`], and that
258 /// impl should be preferred over this method when performing updates, as it
259 /// will usually be faster and more ergonomic.
260 ///
261 /// For large types, this method may be expensive, as it requires copying
262 /// `2 * size_of::<T>()` bytes. \[1\]
263 ///
264 /// \[1\] Since the inner `T` may not be aligned, it would not be sound to
265 /// invoke `f` on it directly. Instead, `update` moves it into a
266 /// properly-aligned location in the local stack frame, calls `f` on it, and
267 /// then moves it back to its original location in `self`.
268 ///
269 /// [`T: Unaligned`]: Unaligned
270 #[inline]
271 pub fn update<O, F: FnOnce(&mut T) -> O>(&mut self, f: F) -> O {
272 // On drop, this moves `copy` out of itself and uses `ptr::write` to
273 // overwrite `slf`.
274 struct WriteBackOnDrop<T> {
275 copy: ManuallyDrop<T>,
276 slf: *mut Unalign<T>,
277 }
278
279 impl<T> Drop for WriteBackOnDrop<T> {
280 fn drop(&mut self) {
281 // SAFETY: We never use `copy` again as required by
282 // `ManuallyDrop::take`.
283 let copy = unsafe { ManuallyDrop::take(&mut self.copy) };
284 // SAFETY: `slf` is the raw pointer value of `self`. We know it
285 // is valid for writes and properly aligned because `self` is a
286 // mutable reference, which guarantees both of these properties.
287 unsafe { ptr::write(self.slf, Unalign::new(copy)) };
288 }
289 }
290
291 // SAFETY: We know that `self` is valid for reads, properly aligned, and
292 // points to an initialized `Unalign<T>` because it is a mutable
293 // reference, which guarantees all of these properties.
294 //
295 // Since `T: !Copy`, it would be unsound in the general case to allow
296 // both the original `Unalign<T>` and the copy to be used by safe code.
297 // We guarantee that the copy is used to overwrite the original in the
298 // `Drop::drop` impl of `WriteBackOnDrop`. So long as this `drop` is
299 // called before any other safe code executes, soundness is upheld.
300 // While this method can terminate in two ways (by returning normally or
301 // by unwinding due to a panic in `f`), in both cases, `write_back` is
302 // dropped - and its `drop` called - before any other safe code can
303 // execute.
304 let copy = unsafe { ptr::read(self) }.into_inner();
305 let mut write_back = WriteBackOnDrop { copy: ManuallyDrop::new(copy), slf: self };
306
307 let ret = f(&mut write_back.copy);
308
309 drop(write_back);
310 ret
311 }
312}
313
314impl<T: Copy> Unalign<T> {
315 /// Gets a copy of the inner `T`.
316 // TODO(https://github.com/rust-lang/rust/issues/57349): Make this `const`.
317 #[inline(always)]
318 pub fn get(&self) -> T {
319 let Unalign(val: T) = *self;
320 val
321 }
322}
323
324impl<T: Unaligned> Deref for Unalign<T> {
325 type Target = T;
326
327 #[inline(always)]
328 fn deref(&self) -> &T {
329 // SAFETY: `deref_unchecked`'s safety requirement is that `self` is
330 // aligned to `align_of::<T>()`. `T: Unaligned` guarantees that
331 // `align_of::<T>() == 1`, and all pointers are one-aligned because all
332 // addresses are divisible by 1.
333 unsafe { self.deref_unchecked() }
334 }
335}
336
337impl<T: Unaligned> DerefMut for Unalign<T> {
338 #[inline(always)]
339 fn deref_mut(&mut self) -> &mut T {
340 // SAFETY: `deref_mut_unchecked`'s safety requirement is that `self` is
341 // aligned to `align_of::<T>()`. `T: Unaligned` guarantees that
342 // `align_of::<T>() == 1`, and all pointers are one-aligned because all
343 // addresses are divisible by 1.
344 unsafe { self.deref_mut_unchecked() }
345 }
346}
347
348impl<T: Unaligned + PartialOrd> PartialOrd<Unalign<T>> for Unalign<T> {
349 #[inline(always)]
350 fn partial_cmp(&self, other: &Unalign<T>) -> Option<Ordering> {
351 PartialOrd::partial_cmp(self.deref(), other:other.deref())
352 }
353}
354
355impl<T: Unaligned + Ord> Ord for Unalign<T> {
356 #[inline(always)]
357 fn cmp(&self, other: &Unalign<T>) -> Ordering {
358 Ord::cmp(self.deref(), other:other.deref())
359 }
360}
361
362impl<T: Unaligned + PartialEq> PartialEq<Unalign<T>> for Unalign<T> {
363 #[inline(always)]
364 fn eq(&self, other: &Unalign<T>) -> bool {
365 PartialEq::eq(self.deref(), other:other.deref())
366 }
367}
368
369impl<T: Unaligned + Eq> Eq for Unalign<T> {}
370
371impl<T: Unaligned + Hash> Hash for Unalign<T> {
372 #[inline(always)]
373 fn hash<H>(&self, state: &mut H)
374 where
375 H: Hasher,
376 {
377 self.deref().hash(state);
378 }
379}
380
381impl<T: Unaligned + Debug> Debug for Unalign<T> {
382 #[inline(always)]
383 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
384 Debug::fmt(self.deref(), f)
385 }
386}
387
388impl<T: Unaligned + Display> Display for Unalign<T> {
389 #[inline(always)]
390 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
391 Display::fmt(self.deref(), f)
392 }
393}
394
395#[cfg(test)]
396mod tests {
397 use core::panic::AssertUnwindSafe;
398
399 use super::*;
400 use crate::util::testutil::*;
401
402 /// A `T` which is guaranteed not to satisfy `align_of::<A>()`.
403 ///
404 /// It must be the case that `align_of::<T>() < align_of::<A>()` in order
405 /// fot this type to work properly.
406 #[repr(C)]
407 struct ForceUnalign<T, A> {
408 // The outer struct is aligned to `A`, and, thanks to `repr(C)`, `t` is
409 // placed at the minimum offset that guarantees its alignment. If
410 // `align_of::<T>() < align_of::<A>()`, then that offset will be
411 // guaranteed *not* to satisfy `align_of::<A>()`.
412 _u: u8,
413 t: T,
414 _a: [A; 0],
415 }
416
417 impl<T, A> ForceUnalign<T, A> {
418 const fn new(t: T) -> ForceUnalign<T, A> {
419 ForceUnalign { _u: 0, t, _a: [] }
420 }
421 }
422
423 #[test]
424 fn test_unalign() {
425 // Test methods that don't depend on alignment.
426 let mut u = Unalign::new(AU64(123));
427 assert_eq!(u.get(), AU64(123));
428 assert_eq!(u.into_inner(), AU64(123));
429 assert_eq!(u.get_ptr(), <*const _>::cast::<AU64>(&u));
430 assert_eq!(u.get_mut_ptr(), <*mut _>::cast::<AU64>(&mut u));
431 u.set(AU64(321));
432 assert_eq!(u.get(), AU64(321));
433
434 // Test methods that depend on alignment (when alignment is satisfied).
435 let mut u: Align<_, AU64> = Align::new(Unalign::new(AU64(123)));
436 assert_eq!(u.t.try_deref(), Some(&AU64(123)));
437 assert_eq!(u.t.try_deref_mut(), Some(&mut AU64(123)));
438 // SAFETY: The `Align<_, AU64>` guarantees proper alignment.
439 assert_eq!(unsafe { u.t.deref_unchecked() }, &AU64(123));
440 // SAFETY: The `Align<_, AU64>` guarantees proper alignment.
441 assert_eq!(unsafe { u.t.deref_mut_unchecked() }, &mut AU64(123));
442 *u.t.try_deref_mut().unwrap() = AU64(321);
443 assert_eq!(u.t.get(), AU64(321));
444
445 // Test methods that depend on alignment (when alignment is not
446 // satisfied).
447 let mut u: ForceUnalign<_, AU64> = ForceUnalign::new(Unalign::new(AU64(123)));
448 assert_eq!(u.t.try_deref(), None);
449 assert_eq!(u.t.try_deref_mut(), None);
450
451 // Test methods that depend on `T: Unaligned`.
452 let mut u = Unalign::new(123u8);
453 assert_eq!(u.try_deref(), Some(&123));
454 assert_eq!(u.try_deref_mut(), Some(&mut 123));
455 assert_eq!(u.deref(), &123);
456 assert_eq!(u.deref_mut(), &mut 123);
457 *u = 21;
458 assert_eq!(u.get(), 21);
459
460 // Test that some `Unalign` functions and methods are `const`.
461 const _UNALIGN: Unalign<u64> = Unalign::new(0);
462 const _UNALIGN_PTR: *const u64 = _UNALIGN.get_ptr();
463 const _U64: u64 = _UNALIGN.into_inner();
464 // Make sure all code is considered "used".
465 //
466 // TODO(https://github.com/rust-lang/rust/issues/104084): Remove this
467 // attribute.
468 #[allow(dead_code)]
469 const _: () = {
470 let x: Align<_, AU64> = Align::new(Unalign::new(AU64(123)));
471 // Make sure that `deref_unchecked` is `const`.
472 //
473 // SAFETY: The `Align<_, AU64>` guarantees proper alignment.
474 let au64 = unsafe { x.t.deref_unchecked() };
475 match au64 {
476 AU64(123) => {}
477 _ => unreachable!(),
478 }
479 };
480 }
481
482 #[test]
483 fn test_unalign_update() {
484 let mut u = Unalign::new(AU64(123));
485 u.update(|a| a.0 += 1);
486 assert_eq!(u.get(), AU64(124));
487
488 // Test that, even if the callback panics, the original is still
489 // correctly overwritten. Use a `Box` so that Miri is more likely to
490 // catch any unsoundness (which would likely result in two `Box`es for
491 // the same heap object, which is the sort of thing that Miri would
492 // probably catch).
493 let mut u = Unalign::new(Box::new(AU64(123)));
494 let res = std::panic::catch_unwind(AssertUnwindSafe(|| {
495 u.update(|a| {
496 a.0 += 1;
497 panic!();
498 })
499 }));
500 assert!(res.is_err());
501 assert_eq!(u.into_inner(), Box::new(AU64(124)));
502 }
503}
504