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
9/// Documents multiple unsafe blocks with a single safety comment.
10///
11/// Invoked as:
12///
13/// ```rust,ignore
14/// safety_comment! {
15/// // Non-doc comments come first.
16/// /// SAFETY:
17/// /// Safety comment starts on its own line.
18/// macro_1!(args);
19/// macro_2! { args };
20/// /// SAFETY:
21/// /// Subsequent safety comments are allowed but not required.
22/// macro_3! { args };
23/// }
24/// ```
25///
26/// The macro invocations are emitted, each decorated with the following
27/// attribute: `#[allow(clippy::undocumented_unsafe_blocks)]`.
28macro_rules! safety_comment {
29 (#[doc = r" SAFETY:"] $($(#[$attr:meta])* $macro:ident!$args:tt;)*) => {
30 #[allow(clippy::undocumented_unsafe_blocks, unused_attributes)]
31 const _: () = { $($(#[$attr])* $macro!$args;)* };
32 }
33}
34
35/// Unsafely implements trait(s) for a type.
36///
37/// # Safety
38///
39/// The trait impl must be sound.
40///
41/// When implementing `TryFromBytes`:
42/// - If no `is_bit_valid` impl is provided, then it must be valid for
43/// `is_bit_valid` to unconditionally return `true`. In other words, it must
44/// be the case that any initialized sequence of bytes constitutes a valid
45/// instance of `$ty`.
46/// - If an `is_bit_valid` impl is provided, then the impl of `is_bit_valid`
47/// must only return `true` if its argument refers to a valid `$ty`.
48macro_rules! unsafe_impl {
49 // Implement `$trait` for `$ty` with no bounds.
50 ($(#[$attr:meta])* $ty:ty: $trait:ident $(; |$candidate:ident| $is_bit_valid:expr)?) => {
51 $(#[$attr])*
52 unsafe impl $trait for $ty {
53 unsafe_impl!(@method $trait $(; |$candidate| $is_bit_valid)?);
54 }
55 };
56
57 // Implement all `$traits` for `$ty` with no bounds.
58 //
59 // The 2 arms under this one are there so we can apply
60 // N attributes for each one of M trait implementations.
61 // The simple solution of:
62 //
63 // ($(#[$attrs:meta])* $ty:ty: $($traits:ident),*) => {
64 // $( unsafe_impl!( $(#[$attrs])* $ty: $traits ) );*
65 // }
66 //
67 // Won't work. The macro processor sees that the outer repetition
68 // contains both $attrs and $traits and expects them to match the same
69 // amount of fragments.
70 //
71 // To solve this we must:
72 // 1. Pack the attributes into a single token tree fragment we can match over.
73 // 2. Expand the traits.
74 // 3. Unpack and expand the attributes.
75 ($(#[$attrs:meta])* $ty:ty: $($traits:ident),*) => {
76 unsafe_impl!(@impl_traits_with_packed_attrs { $(#[$attrs])* } $ty: $($traits),*)
77 };
78
79 (@impl_traits_with_packed_attrs $attrs:tt $ty:ty: $($traits:ident),*) => {
80 $( unsafe_impl!(@unpack_attrs $attrs $ty: $traits); )*
81 };
82
83 (@unpack_attrs { $(#[$attrs:meta])* } $ty:ty: $traits:ident) => {
84 unsafe_impl!($(#[$attrs])* $ty: $traits);
85 };
86
87 // This arm is identical to the following one, except it contains a
88 // preceding `const`. If we attempt to handle these with a single arm, there
89 // is an inherent ambiguity between `const` (the keyword) and `const` (the
90 // ident match for `$tyvar:ident`).
91 //
92 // To explain how this works, consider the following invocation:
93 //
94 // unsafe_impl!(const N: usize, T: ?Sized + Copy => Clone for Foo<T>);
95 //
96 // In this invocation, here are the assignments to meta-variables:
97 //
98 // |---------------|------------|
99 // | Meta-variable | Assignment |
100 // |---------------|------------|
101 // | $constname | N |
102 // | $constty | usize |
103 // | $tyvar | T |
104 // | $optbound | Sized |
105 // | $bound | Copy |
106 // | $trait | Clone |
107 // | $ty | Foo<T> |
108 // |---------------|------------|
109 //
110 // The following arm has the same behavior with the exception of the lack of
111 // support for a leading `const` parameter.
112 (
113 $(#[$attr:meta])*
114 const $constname:ident : $constty:ident $(,)?
115 $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*
116 => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?
117 ) => {
118 unsafe_impl!(
119 @inner
120 $(#[$attr])*
121 @const $constname: $constty,
122 $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)*
123 => $trait for $ty $(; |$candidate| $is_bit_valid)?
124 );
125 };
126 (
127 $(#[$attr:meta])*
128 $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*
129 => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?
130 ) => {
131 unsafe_impl!(
132 @inner
133 $(#[$attr])*
134 $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)*
135 => $trait for $ty $(; |$candidate| $is_bit_valid)?
136 );
137 };
138 (
139 @inner
140 $(#[$attr:meta])*
141 $(@const $constname:ident : $constty:ident,)*
142 $($tyvar:ident $(: $(? $optbound:ident +)* + $($bound:ident +)* )?,)*
143 => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?
144 ) => {
145 $(#[$attr])*
146 #[allow(non_local_definitions)]
147 unsafe impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?),* $(, const $constname: $constty,)*> $trait for $ty {
148 unsafe_impl!(@method $trait $(; |$candidate| $is_bit_valid)?);
149 }
150 };
151
152 (@method TryFromBytes ; |$candidate:ident| $is_bit_valid:expr) => {
153 #[allow(clippy::missing_inline_in_public_items, dead_code)]
154 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
155 fn only_derive_is_allowed_to_implement_this_trait() {}
156
157 #[inline]
158 fn is_bit_valid<AA: crate::pointer::invariant::Reference>($candidate: Maybe<'_, Self, AA>) -> bool {
159 $is_bit_valid
160 }
161 };
162 (@method TryFromBytes) => {
163 #[allow(clippy::missing_inline_in_public_items)]
164 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
165 fn only_derive_is_allowed_to_implement_this_trait() {}
166 #[inline(always)] fn is_bit_valid<AA: crate::pointer::invariant::Reference>(_: Maybe<'_, Self, AA>) -> bool { true }
167 };
168 (@method $trait:ident) => {
169 #[allow(clippy::missing_inline_in_public_items, dead_code)]
170 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
171 fn only_derive_is_allowed_to_implement_this_trait() {}
172 };
173 (@method $trait:ident; |$_candidate:ident| $_is_bit_valid:expr) => {
174 compile_error!("Can't provide `is_bit_valid` impl for trait other than `TryFromBytes`");
175 };
176}
177
178/// Implements `$trait` for `$ty` where `$ty: TransmuteFrom<$repr>` (and
179/// vice-versa).
180///
181/// Calling this macro is safe; the internals of the macro emit appropriate
182/// trait bounds which ensure that the given impl is sound.
183macro_rules! impl_for_transmute_from {
184 (
185 $(#[$attr:meta])*
186 $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?)?
187 => $trait:ident for $ty:ty [$($unsafe_cell:ident)? <$repr:ty>]
188 ) => {
189 $(#[$attr])*
190 #[allow(non_local_definitions)]
191
192 // SAFETY: `is_trait<T, R>` (defined and used below) requires `T:
193 // TransmuteFrom<R>`, `R: TransmuteFrom<T>`, and `R: $trait`. It is
194 // called using `$ty` and `$repr`, ensuring that `$ty` and `$repr` have
195 // equivalent bit validity, and ensuring that `$repr: $trait`. The
196 // supported traits - `TryFromBytes`, `FromZeros`, `FromBytes`, and
197 // `IntoBytes` - are defined only in terms of the bit validity of a
198 // type. Therefore, `$repr: $trait` ensures that `$ty: $trait` is sound.
199 unsafe impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?)?> $trait for $ty {
200 #[allow(dead_code, clippy::missing_inline_in_public_items)]
201 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
202 fn only_derive_is_allowed_to_implement_this_trait() {
203 use crate::pointer::{*, invariant::Valid};
204
205 impl_for_transmute_from!(@assert_is_supported_trait $trait);
206
207 fn is_trait<T, R>()
208 where
209 T: TransmuteFrom<R, Valid, Valid> + ?Sized,
210 R: TransmuteFrom<T, Valid, Valid> + ?Sized,
211 R: $trait,
212 {
213 }
214
215 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
216 fn f<$($tyvar $(: $(? $optbound +)* $($bound +)*)?)?>() {
217 is_trait::<$ty, $repr>();
218 }
219 }
220
221 impl_for_transmute_from!(
222 @is_bit_valid
223 $(<$tyvar $(: $(? $optbound +)* $($bound +)*)?>)?
224 $trait for $ty [$($unsafe_cell)? <$repr>]
225 );
226 }
227 };
228 (@assert_is_supported_trait TryFromBytes) => {};
229 (@assert_is_supported_trait FromZeros) => {};
230 (@assert_is_supported_trait FromBytes) => {};
231 (@assert_is_supported_trait IntoBytes) => {};
232 (
233 @is_bit_valid
234 $(<$tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?>)?
235 TryFromBytes for $ty:ty [UnsafeCell<$repr:ty>]
236 ) => {
237 #[inline]
238 fn is_bit_valid<A: crate::pointer::invariant::Reference>(candidate: Maybe<'_, Self, A>) -> bool {
239 let c: Maybe<'_, Self, crate::pointer::invariant::Exclusive> = candidate.into_exclusive_or_pme();
240 let c: Maybe<'_, $repr, _> = c.transmute::<_, _, (_, (_, (BecauseExclusive, BecauseExclusive)))>();
241 // SAFETY: This macro ensures that `$repr` and `Self` have the same
242 // size and bit validity. Thus, a bit-valid instance of `$repr` is
243 // also a bit-valid instance of `Self`.
244 <$repr as TryFromBytes>::is_bit_valid(c)
245 }
246 };
247 (
248 @is_bit_valid
249 $(<$tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?>)?
250 TryFromBytes for $ty:ty [<$repr:ty>]
251 ) => {
252 #[inline]
253 fn is_bit_valid<A: crate::pointer::invariant::Reference>(candidate: Maybe<'_, Self, A>) -> bool {
254 // SAFETY: This macro ensures that `$repr` and `Self` have the same
255 // size and bit validity. Thus, a bit-valid instance of `$repr` is
256 // also a bit-valid instance of `Self`.
257 <$repr as TryFromBytes>::is_bit_valid(candidate.transmute())
258 }
259 };
260 (
261 @is_bit_valid
262 $(<$tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?>)?
263 $trait:ident for $ty:ty [$($unsafe_cell:ident)? <$repr:ty>]
264 ) => {
265 // Trait other than `TryFromBytes`; no `is_bit_valid` impl.
266 };
267}
268
269/// Implements a trait for a type, bounding on each memeber of the power set of
270/// a set of type variables. This is useful for implementing traits for tuples
271/// or `fn` types.
272///
273/// The last argument is the name of a macro which will be called in every
274/// `impl` block, and is expected to expand to the name of the type for which to
275/// implement the trait.
276///
277/// For example, the invocation:
278/// ```ignore
279/// unsafe_impl_for_power_set!(A, B => Foo for type!(...))
280/// ```
281/// ...expands to:
282/// ```ignore
283/// unsafe impl Foo for type!() { ... }
284/// unsafe impl<B> Foo for type!(B) { ... }
285/// unsafe impl<A, B> Foo for type!(A, B) { ... }
286/// ```
287macro_rules! unsafe_impl_for_power_set {
288 (
289 $first:ident $(, $rest:ident)* $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)
290 $(; |$candidate:ident| $is_bit_valid:expr)?
291 ) => {
292 unsafe_impl_for_power_set!(
293 $($rest),* $(-> $ret)? => $trait for $macro!(...)
294 $(; |$candidate| $is_bit_valid)?
295 );
296 unsafe_impl_for_power_set!(
297 @impl $first $(, $rest)* $(-> $ret)? => $trait for $macro!(...)
298 $(; |$candidate| $is_bit_valid)?
299 );
300 };
301 (
302 $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)
303 $(; |$candidate:ident| $is_bit_valid:expr)?
304 ) => {
305 unsafe_impl_for_power_set!(
306 @impl $(-> $ret)? => $trait for $macro!(...)
307 $(; |$candidate| $is_bit_valid)?
308 );
309 };
310 (
311 @impl $($vars:ident),* $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)
312 $(; |$candidate:ident| $is_bit_valid:expr)?
313 ) => {
314 unsafe_impl!(
315 $($vars,)* $($ret)? => $trait for $macro!($($vars),* $(-> $ret)?)
316 $(; |$candidate| $is_bit_valid)?
317 );
318 };
319}
320
321/// Expands to an `Option<extern "C" fn>` type with the given argument types and
322/// return type. Designed for use with `unsafe_impl_for_power_set`.
323macro_rules! opt_extern_c_fn {
324 ($($args:ident),* -> $ret:ident) => { Option<extern "C" fn($($args),*) -> $ret> };
325}
326
327/// Expands to a `Option<fn>` type with the given argument types and return
328/// type. Designed for use with `unsafe_impl_for_power_set`.
329macro_rules! opt_fn {
330 ($($args:ident),* -> $ret:ident) => { Option<fn($($args),*) -> $ret> };
331}
332
333/// Implements trait(s) for a type or verifies the given implementation by
334/// referencing an existing (derived) implementation.
335///
336/// This macro exists so that we can provide zerocopy-derive as an optional
337/// dependency and still get the benefit of using its derives to validate that
338/// our trait impls are sound.
339///
340/// When compiling without `--cfg 'feature = "derive"` and without `--cfg test`,
341/// `impl_or_verify!` emits the provided trait impl. When compiling with either
342/// of those cfgs, it is expected that the type in question is deriving the
343/// traits instead. In this case, `impl_or_verify!` emits code which validates
344/// that the given trait impl is at least as restrictive as the the impl emitted
345/// by the custom derive. This has the effect of confirming that the impl which
346/// is emitted when the `derive` feature is disabled is actually sound (on the
347/// assumption that the impl emitted by the custom derive is sound).
348///
349/// The caller is still required to provide a safety comment (e.g. using the
350/// `safety_comment!` macro) . The reason for this restriction is that, while
351/// `impl_or_verify!` can guarantee that the provided impl is sound when it is
352/// compiled with the appropriate cfgs, there is no way to guarantee that it is
353/// ever compiled with those cfgs. In particular, it would be possible to
354/// accidentally place an `impl_or_verify!` call in a context that is only ever
355/// compiled when the `derive` feature is disabled. If that were to happen,
356/// there would be nothing to prevent an unsound trait impl from being emitted.
357/// Requiring a safety comment reduces the likelihood of emitting an unsound
358/// impl in this case, and also provides useful documentation for readers of the
359/// code.
360///
361/// Finally, if a `TryFromBytes::is_bit_valid` impl is provided, it must adhere
362/// to the safety preconditions of [`unsafe_impl!`].
363///
364/// ## Example
365///
366/// ```rust,ignore
367/// // Note that these derives are gated by `feature = "derive"`
368/// #[cfg_attr(any(feature = "derive", test), derive(FromZeros, FromBytes, IntoBytes, Unaligned))]
369/// #[repr(transparent)]
370/// struct Wrapper<T>(T);
371///
372/// safety_comment! {
373/// /// SAFETY:
374/// /// `Wrapper<T>` is `repr(transparent)`, so it is sound to implement any
375/// /// zerocopy trait if `T` implements that trait.
376/// impl_or_verify!(T: FromZeros => FromZeros for Wrapper<T>);
377/// impl_or_verify!(T: FromBytes => FromBytes for Wrapper<T>);
378/// impl_or_verify!(T: IntoBytes => IntoBytes for Wrapper<T>);
379/// impl_or_verify!(T: Unaligned => Unaligned for Wrapper<T>);
380/// }
381/// ```
382macro_rules! impl_or_verify {
383 // The following two match arms follow the same pattern as their
384 // counterparts in `unsafe_impl!`; see the documentation on those arms for
385 // more details.
386 (
387 const $constname:ident : $constty:ident $(,)?
388 $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*
389 => $trait:ident for $ty:ty
390 ) => {
391 impl_or_verify!(@impl { unsafe_impl!(
392 const $constname: $constty, $($tyvar $(: $(? $optbound +)* $($bound +)*)?),* => $trait for $ty
393 ); });
394 impl_or_verify!(@verify $trait, {
395 impl<const $constname: $constty, $($tyvar $(: $(? $optbound +)* $($bound +)*)?),*> Subtrait for $ty {}
396 });
397 };
398 (
399 $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*
400 => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?
401 ) => {
402 impl_or_verify!(@impl { unsafe_impl!(
403 $($tyvar $(: $(? $optbound +)* $($bound +)*)?),* => $trait for $ty
404 $(; |$candidate| $is_bit_valid)?
405 ); });
406 impl_or_verify!(@verify $trait, {
407 impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?),*> Subtrait for $ty {}
408 });
409 };
410 (@impl $impl_block:tt) => {
411 #[cfg(not(any(feature = "derive", test)))]
412 const _: () = { $impl_block };
413 };
414 (@verify $trait:ident, $impl_block:tt) => {
415 #[cfg(any(feature = "derive", test))]
416 const _: () = {
417 trait Subtrait: $trait {}
418 $impl_block
419 };
420 };
421}
422
423/// Implements `KnownLayout` for a sized type.
424macro_rules! impl_known_layout {
425 ($(const $constvar:ident : $constty:ty, $tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {
426 $(impl_known_layout!(@inner const $constvar: $constty, $tyvar $(: ?$optbound)? => $ty);)*
427 };
428 ($($tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {
429 $(impl_known_layout!(@inner , $tyvar $(: ?$optbound)? => $ty);)*
430 };
431 ($($(#[$attrs:meta])* $ty:ty),*) => { $(impl_known_layout!(@inner , => $(#[$attrs])* $ty);)* };
432 (@inner $(const $constvar:ident : $constty:ty)? , $($tyvar:ident $(: ?$optbound:ident)?)? => $(#[$attrs:meta])* $ty:ty) => {
433 const _: () = {
434 use core::ptr::NonNull;
435
436 #[allow(non_local_definitions)]
437 $(#[$attrs])*
438 // SAFETY: Delegates safety to `DstLayout::for_type`.
439 unsafe impl<$($tyvar $(: ?$optbound)?)? $(, const $constvar : $constty)?> KnownLayout for $ty {
440 #[allow(clippy::missing_inline_in_public_items)]
441 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
442 fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}
443
444 type PointerMetadata = ();
445
446 // SAFETY: `CoreMaybeUninit<T>::LAYOUT` and `T::LAYOUT` are
447 // identical because `CoreMaybeUninit<T>` has the same size and
448 // alignment as `T` [1], and `CoreMaybeUninit` admits
449 // uninitialized bytes in all positions.
450 //
451 // [1] Per https://doc.rust-lang.org/1.81.0/std/mem/union.MaybeUninit.html#layout-1:
452 //
453 // `MaybeUninit<T>` is guaranteed to have the same size,
454 // alignment, and ABI as `T`
455 type MaybeUninit = core::mem::MaybeUninit<Self>;
456
457 const LAYOUT: crate::DstLayout = crate::DstLayout::for_type::<$ty>();
458
459 // SAFETY: `.cast` preserves address and provenance.
460 //
461 // TODO(#429): Add documentation to `.cast` that promises that
462 // it preserves provenance.
463 #[inline(always)]
464 fn raw_from_ptr_len(bytes: NonNull<u8>, _meta: ()) -> NonNull<Self> {
465 bytes.cast::<Self>()
466 }
467
468 #[inline(always)]
469 fn pointer_to_metadata(_ptr: *mut Self) -> () {
470 }
471 }
472 };
473 };
474}
475
476/// Implements `KnownLayout` for a type in terms of the implementation of
477/// another type with the same representation.
478///
479/// # Safety
480///
481/// - `$ty` and `$repr` must have the same:
482/// - Fixed prefix size
483/// - Alignment
484/// - (For DSTs) trailing slice element size
485/// - It must be valid to perform an `as` cast from `*mut $repr` to `*mut $ty`,
486/// and this operation must preserve referent size (ie, `size_of_val_raw`).
487macro_rules! unsafe_impl_known_layout {
488 ($($tyvar:ident: ?Sized + KnownLayout =>)? #[repr($repr:ty)] $ty:ty) => {
489 const _: () = {
490 use core::ptr::NonNull;
491
492 #[allow(non_local_definitions)]
493 unsafe impl<$($tyvar: ?Sized + KnownLayout)?> KnownLayout for $ty {
494 #[allow(clippy::missing_inline_in_public_items, dead_code)]
495 #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]
496 fn only_derive_is_allowed_to_implement_this_trait() {}
497
498 type PointerMetadata = <$repr as KnownLayout>::PointerMetadata;
499 type MaybeUninit = <$repr as KnownLayout>::MaybeUninit;
500
501 const LAYOUT: DstLayout = <$repr as KnownLayout>::LAYOUT;
502
503 // SAFETY: All operations preserve address and provenance.
504 // Caller has promised that the `as` cast preserves size.
505 //
506 // TODO(#429): Add documentation to `NonNull::new_unchecked`
507 // that it preserves provenance.
508 #[inline(always)]
509 fn raw_from_ptr_len(bytes: NonNull<u8>, meta: <$repr as KnownLayout>::PointerMetadata) -> NonNull<Self> {
510 #[allow(clippy::as_conversions)]
511 let ptr = <$repr>::raw_from_ptr_len(bytes, meta).as_ptr() as *mut Self;
512 // SAFETY: `ptr` was converted from `bytes`, which is non-null.
513 unsafe { NonNull::new_unchecked(ptr) }
514 }
515
516 #[inline(always)]
517 fn pointer_to_metadata(ptr: *mut Self) -> Self::PointerMetadata {
518 #[allow(clippy::as_conversions)]
519 let ptr = ptr as *mut $repr;
520 <$repr>::pointer_to_metadata(ptr)
521 }
522 }
523 };
524 };
525}
526
527/// Uses `align_of` to confirm that a type or set of types have alignment 1.
528///
529/// Note that `align_of<T>` requires `T: Sized`, so this macro doesn't work for
530/// unsized types.
531macro_rules! assert_unaligned {
532 ($($tys:ty),*) => {
533 $(
534 // We only compile this assertion under `cfg(test)` to avoid taking
535 // an extra non-dev dependency (and making this crate more expensive
536 // to compile for our dependents).
537 #[cfg(test)]
538 static_assertions::const_assert_eq!(core::mem::align_of::<$tys>(), 1);
539 )*
540 };
541}
542
543/// Emits a function definition as either `const fn` or `fn` depending on
544/// whether the current toolchain version supports `const fn` with generic trait
545/// bounds.
546macro_rules! maybe_const_trait_bounded_fn {
547 // This case handles both `self` methods (where `self` is by value) and
548 // non-method functions. Each `$args` may optionally be followed by `:
549 // $arg_tys:ty`, which can be omitted for `self`.
550 ($(#[$attr:meta])* $vis:vis const fn $name:ident($($args:ident $(: $arg_tys:ty)?),* $(,)?) $(-> $ret_ty:ty)? $body:block) => {
551 #[cfg(zerocopy_generic_bounds_in_const_fn_1_61_0)]
552 $(#[$attr])* $vis const fn $name($($args $(: $arg_tys)?),*) $(-> $ret_ty)? $body
553
554 #[cfg(not(zerocopy_generic_bounds_in_const_fn_1_61_0))]
555 $(#[$attr])* $vis fn $name($($args $(: $arg_tys)?),*) $(-> $ret_ty)? $body
556 };
557}
558
559/// Either panic (if the current Rust toolchain supports panicking in `const
560/// fn`) or evaluate a constant that will cause an array indexing error whose
561/// error message will include the format string.
562///
563/// The type that this expression evaluates to must be `Copy`, or else the
564/// non-panicking desugaring will fail to compile.
565macro_rules! const_panic {
566 (@non_panic $($_arg:tt)+) => {{
567 // This will type check to whatever type is expected based on the call
568 // site.
569 let panic: [_; 0] = [];
570 // This will always fail (since we're indexing into an array of size 0.
571 #[allow(unconditional_panic)]
572 panic[0]
573 }};
574 ($($arg:tt)+) => {{
575 #[cfg(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)]
576 panic!($($arg)+);
577 #[cfg(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0))]
578 const_panic!(@non_panic $($arg)+)
579 }};
580}
581
582/// Either assert (if the current Rust toolchain supports panicking in `const
583/// fn`) or evaluate the expression and, if it evaluates to `false`, call
584/// `const_panic!`. This is used in place of `assert!` in const contexts to
585/// accommodate old toolchains.
586macro_rules! const_assert {
587 ($e:expr) => {{
588 #[cfg(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)]
589 assert!($e);
590 #[cfg(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0))]
591 {
592 let e = $e;
593 if !e {
594 let _: () = const_panic!(@non_panic concat!("assertion failed: ", stringify!($e)));
595 }
596 }
597 }};
598 ($e:expr, $($args:tt)+) => {{
599 #[cfg(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)]
600 assert!($e, $($args)+);
601 #[cfg(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0))]
602 {
603 let e = $e;
604 if !e {
605 let _: () = const_panic!(@non_panic concat!("assertion failed: ", stringify!($e), ": ", stringify!($arg)), $($args)*);
606 }
607 }
608 }};
609}
610
611/// Like `const_assert!`, but relative to `debug_assert!`.
612macro_rules! const_debug_assert {
613 ($e:expr $(, $msg:expr)?) => {{
614 #[cfg(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)]
615 debug_assert!($e $(, $msg)?);
616 #[cfg(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0))]
617 {
618 // Use this (rather than `#[cfg(debug_assertions)]`) to ensure that
619 // `$e` is always compiled even if it will never be evaluated at
620 // runtime.
621 if cfg!(debug_assertions) {
622 let e = $e;
623 if !e {
624 let _: () = const_panic!(@non_panic concat!("assertion failed: ", stringify!($e) $(, ": ", $msg)?));
625 }
626 }
627 }
628 }}
629}
630
631/// Either invoke `unreachable!()` or `loop {}` depending on whether the Rust
632/// toolchain supports panicking in `const fn`.
633macro_rules! const_unreachable {
634 () => {{
635 #[cfg(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)]
636 unreachable!();
637
638 #[cfg(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0))]
639 loop {}
640 }};
641}
642
643/// Asserts at compile time that `$condition` is true for `Self` or the given
644/// `$tyvar`s. Unlike `const_assert`, this is *strictly* a compile-time check;
645/// it cannot be evaluated in a runtime context. The condition is checked after
646/// monomorphization and, upon failure, emits a compile error.
647macro_rules! static_assert {
648 (Self $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )? => $condition:expr $(, $args:tt)*) => {{
649 trait StaticAssert {
650 const ASSERT: bool;
651 }
652
653 impl<T $(: $(? $optbound +)* $($bound +)*)?> StaticAssert for T {
654 const ASSERT: bool = {
655 const_assert!($condition $(, $args)*);
656 $condition
657 };
658 }
659
660 const_assert!(<Self as StaticAssert>::ASSERT);
661 }};
662 ($($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),* => $condition:expr $(, $args:tt)*) => {{
663 trait StaticAssert {
664 const ASSERT: bool;
665 }
666
667 impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?,)*> StaticAssert for ($($tyvar,)*) {
668 const ASSERT: bool = {
669 const_assert!($condition $(, $args)*);
670 $condition
671 };
672 }
673
674 const_assert!(<($($tyvar,)*) as StaticAssert>::ASSERT);
675 }};
676}
677
678/// Assert at compile time that `tyvar` does not have a zero-sized DST
679/// component.
680macro_rules! static_assert_dst_is_not_zst {
681 ($tyvar:ident) => {{
682 use crate::KnownLayout;
683 static_assert!($tyvar: ?Sized + KnownLayout => {
684 let dst_is_zst = match $tyvar::LAYOUT.size_info {
685 crate::SizeInfo::Sized { .. } => false,
686 crate::SizeInfo::SliceDst(TrailingSliceLayout { elem_size, .. }) => {
687 elem_size == 0
688 }
689 };
690 !dst_is_zst
691 }, "cannot call this method on a dynamically-sized type whose trailing slice element is zero-sized");
692 }}
693}
694
695macro_rules! cast {
696 () => {
697 |p| {
698 // SAFETY: `NonNull::as_ptr` returns a non-null pointer, so the
699 // argument to `NonNull::new_unchecked` is also non-null.
700 #[allow(clippy::as_conversions, unused_unsafe)]
701 #[allow(clippy::undocumented_unsafe_blocks)] // Clippy false positive
702 return unsafe {
703 core::ptr::NonNull::new_unchecked(core::ptr::NonNull::as_ptr(p) as *mut _)
704 };
705 }
706 };
707 ($p:ident) => {
708 cast!()($p)
709 };
710}
711
712/// Implements `TransmuteFrom` and `SizeEq` for `T` and `$wrapper<T>`.
713///
714/// # Safety
715///
716/// `T` and `$wrapper<T>` must have the same bit validity, and must have the
717/// same size in the sense of `SizeEq`.
718macro_rules! unsafe_impl_for_transparent_wrapper {
719 (T $(: ?$optbound:ident)? => $wrapper:ident<T>) => {
720 const _: () = {
721 use core::ptr::NonNull;
722 use crate::pointer::{TransmuteFrom, SizeEq, invariant::Valid};
723
724 // SAFETY: The caller promises that `T` and `$wrapper<T>` have the
725 // same bit validity.
726 unsafe impl<T $(: ?$optbound)?> TransmuteFrom<T, Valid, Valid> for $wrapper<T> {}
727 // SAFETY: See previous safety comment.
728 unsafe impl<T $(: ?$optbound)?> TransmuteFrom<$wrapper<T>, Valid, Valid> for T {}
729 // SAFETY: The caller promises that `T` and `$wrapper<T>` satisfy
730 // `SizeEq`.
731 unsafe impl<T $(: ?$optbound)?> SizeEq<T> for $wrapper<T> {
732 fn cast_from_raw(t: NonNull<T>) -> NonNull<$wrapper<T>> {
733 cast!(t)
734 }
735 }
736 // SAFETY: See previous safety comment.
737 unsafe impl<T $(: ?$optbound)?> SizeEq<$wrapper<T>> for T {
738 fn cast_from_raw(t: NonNull<$wrapper<T>>) -> NonNull<T> {
739 cast!(t)
740 }
741 }
742 };
743
744 // So that this macro must be invoked inside `safety_comment!` or else
745 // it will generate a `clippy::undocumented_unsafe_blocks` warning.
746 #[allow(unused_unsafe)]
747 const _: () = unsafe {};
748 };
749}
750
751macro_rules! impl_transitive_transmute_from {
752 ($($tyvar:ident $(: ?$optbound:ident)?)? => $t:ty => $u:ty => $v:ty) => {
753 const _: () = {
754 use core::ptr::NonNull;
755 use crate::pointer::{TransmuteFrom, SizeEq, invariant::Valid};
756
757 // SAFETY: Since `$u: SizeEq<$t>` and `$v: SizeEq<U>`, this impl is
758 // transitively sound.
759 unsafe impl<$($tyvar $(: ?$optbound)?)?> SizeEq<$t> for $v
760 where
761 $u: SizeEq<$t>,
762 $v: SizeEq<$u>,
763 {
764 fn cast_from_raw(t: NonNull<$t>) -> NonNull<$v> {
765 cast!(t)
766 }
767 }
768
769 // SAFETY: Since `$u: TransmuteFrom<$t, Valid, Valid>`, it is sound
770 // to transmute a bit-valid `$t` to a bit-valid `$u`. Since `$v:
771 // TransmuteFrom<$u, Valid, Valid>`, it is sound to transmute that
772 // bit-valid `$u` to a bit-valid `$v`.
773 unsafe impl<$($tyvar $(: ?$optbound)?)?> TransmuteFrom<$t, Valid, Valid> for $v
774 where
775 $u: TransmuteFrom<$t, Valid, Valid>,
776 $v: TransmuteFrom<$u, Valid, Valid>,
777 {}
778 };
779 };
780}
781
782macro_rules! impl_size_eq {
783 ($t:ty, $u:ty) => {
784 const _: () = {
785 use crate::pointer::SizeEq;
786 use core::ptr::NonNull;
787
788 static_assert!(=> mem::size_of::<$t>() == mem::size_of::<$u>());
789
790 // SAFETY: We've asserted that their sizes are equal.
791 unsafe impl SizeEq<$t> for $u {
792 fn cast_from_raw(t: NonNull<$t>) -> NonNull<$u> {
793 cast!(t)
794 }
795 }
796 // SAFETY: We've asserted that their sizes are equal.
797 unsafe impl SizeEq<$u> for $t {
798 fn cast_from_raw(u: NonNull<$u>) -> NonNull<$t> {
799 cast!(u)
800 }
801 }
802 };
803 };
804}
805