xref: /qemu/rust/qemu-api/src/zeroable.rs (revision 590faa03ee64b4221d1be39949190e82e361efb7)
1 // SPDX-License-Identifier: GPL-2.0-or-later
2 
3 /// Encapsulates the requirement that
4 /// `MaybeUninit::<Self>::zeroed().assume_init()` does not cause undefined
5 /// behavior.  This trait in principle could be implemented as just:
6 ///
7 /// ```
8 /// pub unsafe trait Zeroable {
9 ///     const ZERO: Self = unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() };
10 /// }
11 /// ```
12 ///
13 /// The need for a manual implementation is only because `zeroed()` cannot
14 /// be used as a `const fn` prior to Rust 1.75.0. Once we can assume a new
15 /// enough version of the compiler, we could provide a `#[derive(Zeroable)]`
16 /// macro to check at compile-time that all struct fields are Zeroable, and
17 /// use the above blanket implementation of the `ZERO` constant.
18 ///
19 /// # Safety
20 ///
21 /// Because the implementation of `ZERO` is manual, it does not make
22 /// any assumption on the safety of `zeroed()`.  However, other users of the
23 /// trait could use it that way.  Do not add this trait to a type unless
24 /// all-zeroes is a valid value for the type.  In particular, remember that
25 /// raw pointers can be zero, but references and `NonNull<T>` cannot
26 pub unsafe trait Zeroable: Default {
27     const ZERO: Self;
28 }
29 
30 /// A macro that acts similarly to [`core::mem::zeroed()`], only is const
31 ///
32 /// ## Safety
33 ///
34 /// Similar to `core::mem::zeroed()`, except this zeroes padding bits. Zeroed
35 /// padding usually isn't relevant to safety, but might be if a C union is used.
36 ///
37 /// Just like for `core::mem::zeroed()`, an all zero byte pattern might not
38 /// be a valid value for a type, as is the case for references `&T` and `&mut
39 /// T`. Reference types trigger a (denied by default) lint and cause immediate
40 /// undefined behavior if the lint is ignored
41 ///
42 /// ```rust compile_fail
43 /// use const_zero::const_zero;
44 /// // error: any use of this value will cause an error
45 /// // note: `#[deny(const_err)]` on by default
46 /// const STR: &str = unsafe{const_zero!(&'static str)};
47 /// ```
48 ///
49 /// `const_zero` does not work on unsized types:
50 ///
51 /// ```rust compile_fail
52 /// use const_zero::const_zero;
53 /// // error[E0277]: the size for values of type `[u8]` cannot be known at compilation time
54 /// const BYTES: [u8] = unsafe{const_zero!([u8])};
55 /// ```
56 /// ## Differences with `core::mem::zeroed`
57 ///
58 /// `const_zero` zeroes padding bits, while `core::mem::zeroed` doesn't
59 macro_rules! const_zero {
60     // This macro to produce a type-generic zero constant is taken from the
61     // const_zero crate (v0.1.1):
62     //
63     //     https://docs.rs/const-zero/latest/src/const_zero/lib.rs.html
64     //
65     // and used under MIT license
66     ($type_:ty) => {{
67         const TYPE_SIZE: ::core::primitive::usize = ::core::mem::size_of::<$type_>();
68         union TypeAsBytes {
69             bytes: [::core::primitive::u8; TYPE_SIZE],
70             inner: ::core::mem::ManuallyDrop<$type_>,
71         }
72         const ZERO_BYTES: TypeAsBytes = TypeAsBytes {
73             bytes: [0; TYPE_SIZE],
74         };
75         ::core::mem::ManuallyDrop::<$type_>::into_inner(ZERO_BYTES.inner)
76     }};
77 }
78 
79 /// A wrapper to implement the `Zeroable` trait through the `const_zero` macro.
80 macro_rules! impl_zeroable {
81     ($type:ty) => {
82         unsafe impl Zeroable for $type {
83             const ZERO: Self = unsafe { const_zero!($type) };
84         }
85     };
86 }
87 
88 // bindgen does not derive Default here
89 #[allow(clippy::derivable_impls)]
90 impl Default for crate::bindings::VMStateFlags {
91     fn default() -> Self {
92         Self(0)
93     }
94 }
95 
96 impl_zeroable!(crate::bindings::Property__bindgen_ty_1);
97 impl_zeroable!(crate::bindings::Property);
98 impl_zeroable!(crate::bindings::VMStateFlags);
99 impl_zeroable!(crate::bindings::VMStateField);
100 impl_zeroable!(crate::bindings::VMStateDescription);
101 impl_zeroable!(crate::bindings::MemoryRegionOps__bindgen_ty_1);
102 impl_zeroable!(crate::bindings::MemoryRegionOps__bindgen_ty_2);
103 impl_zeroable!(crate::bindings::MemoryRegionOps);
104