1 // SPDX-License-Identifier: Apache-2.0 OR MIT
2
3 //! This module contains API-internal items fo
4 //!
5 //! These items must not be used outside of
6 //! - `kernel/init.rs`
7 //! - `macros/pin_data.rs`
8 //! - `macros/pinned_drop.rs`
9
10 use super::*;
11
12 /// See the [nomicon] for what subtyping is. S
13 ///
14 /// [nomicon]: https://doc.rust-lang.org/nomic
15 /// [this table]: https://doc.rust-lang.org/no
16 pub(super) type Invariant<T> = PhantomData<fn(
17
18 /// This is the module-internal type implement
19 /// type, since the closure needs to fulfill t
20 /// `__pinned_init`/`__init` functions.
21 pub(crate) struct InitClosure<F, T: ?Sized, E>
22
23 // SAFETY: While constructing the `InitClosure
24 // `__init` invariants.
25 unsafe impl<T: ?Sized, F, E> Init<T, E> for In
26 where
27 F: FnOnce(*mut T) -> Result<(), E>,
28 {
29 #[inline]
30 unsafe fn __init(self, slot: *mut T) -> Re
31 (self.0)(slot)
32 }
33 }
34
35 // SAFETY: While constructing the `InitClosure
36 // `__pinned_init` invariants.
37 unsafe impl<T: ?Sized, F, E> PinInit<T, E> for
38 where
39 F: FnOnce(*mut T) -> Result<(), E>,
40 {
41 #[inline]
42 unsafe fn __pinned_init(self, slot: *mut T
43 (self.0)(slot)
44 }
45 }
46
47 /// This trait is only implemented via the `#[
48 /// the pin projections within the initializer
49 ///
50 /// # Safety
51 ///
52 /// Only the `init` module is allowed to use t
53 pub unsafe trait HasPinData {
54 type PinData: PinData;
55
56 unsafe fn __pin_data() -> Self::PinData;
57 }
58
59 /// Marker trait for pinning data of structs.
60 ///
61 /// # Safety
62 ///
63 /// Only the `init` module is allowed to use t
64 pub unsafe trait PinData: Copy {
65 type Datee: ?Sized + HasPinData;
66
67 /// Type inference helper function.
68 fn make_closure<F, O, E>(self, f: F) -> F
69 where
70 F: FnOnce(*mut Self::Datee) -> Result<
71 {
72 f
73 }
74 }
75
76 /// This trait is automatically implemented fo
77 /// inference help as `HasPinData`.
78 ///
79 /// # Safety
80 ///
81 /// Only the `init` module is allowed to use t
82 pub unsafe trait HasInitData {
83 type InitData: InitData;
84
85 unsafe fn __init_data() -> Self::InitData;
86 }
87
88 /// Same function as `PinData`, but for arbitr
89 ///
90 /// # Safety
91 ///
92 /// Only the `init` module is allowed to use t
93 pub unsafe trait InitData: Copy {
94 type Datee: ?Sized + HasInitData;
95
96 /// Type inference helper function.
97 fn make_closure<F, O, E>(self, f: F) -> F
98 where
99 F: FnOnce(*mut Self::Datee) -> Result<
100 {
101 f
102 }
103 }
104
105 pub struct AllData<T: ?Sized>(PhantomData<fn(B
106
107 impl<T: ?Sized> Clone for AllData<T> {
108 fn clone(&self) -> Self {
109 *self
110 }
111 }
112
113 impl<T: ?Sized> Copy for AllData<T> {}
114
115 unsafe impl<T: ?Sized> InitData for AllData<T>
116 type Datee = T;
117 }
118
119 unsafe impl<T: ?Sized> HasInitData for T {
120 type InitData = AllData<T>;
121
122 unsafe fn __init_data() -> Self::InitData
123 AllData(PhantomData)
124 }
125 }
126
127 /// Stack initializer helper type. Use [`stack
128 ///
129 /// # Invariants
130 ///
131 /// If `self.is_init` is true, then `self.valu
132 ///
133 /// [`stack_pin_init`]: kernel::stack_pin_init
134 pub struct StackInit<T> {
135 value: MaybeUninit<T>,
136 is_init: bool,
137 }
138
139 impl<T> Drop for StackInit<T> {
140 #[inline]
141 fn drop(&mut self) {
142 if self.is_init {
143 // SAFETY: As we are being dropped
144 // true, `self.value` is initializ
145 unsafe { self.value.assume_init_dr
146 }
147 }
148 }
149
150 impl<T> StackInit<T> {
151 /// Creates a new [`StackInit<T>`] that is
152 /// primitive.
153 ///
154 /// [`stack_pin_init`]: kernel::stack_pin_
155 #[inline]
156 pub fn uninit() -> Self {
157 Self {
158 value: MaybeUninit::uninit(),
159 is_init: false,
160 }
161 }
162
163 /// Initializes the contents and returns t
164 #[inline]
165 pub fn init<E>(self: Pin<&mut Self>, init:
166 // SAFETY: We never move out of `this`
167 let this = unsafe { Pin::into_inner_un
168 // The value is currently initialized,
169 // the memory (this is a safety guaran
170 if this.is_init {
171 this.is_init = false;
172 // SAFETY: `this.is_init` was true
173 unsafe { this.value.assume_init_dr
174 }
175 // SAFETY: The memory slot is valid an
176 unsafe { init.__pinned_init(this.value
177 // INVARIANT: `this.value` is initiali
178 this.is_init = true;
179 // SAFETY: The slot is now pinned, sin
180 Ok(unsafe { Pin::new_unchecked(this.va
181 }
182 }
183
184 /// When a value of this type is dropped, it d
185 ///
186 /// Can be forgotten to prevent the drop.
187 pub struct DropGuard<T: ?Sized> {
188 ptr: *mut T,
189 }
190
191 impl<T: ?Sized> DropGuard<T> {
192 /// Creates a new [`DropGuard<T>`]. It wil
193 ///
194 /// # Safety
195 ///
196 /// `ptr` must be a valid pointer.
197 ///
198 /// It is the callers responsibility that
199 /// - has not been dropped,
200 /// - is not accessible by any other means
201 /// - will not be dropped by any other mea
202 #[inline]
203 pub unsafe fn new(ptr: *mut T) -> Self {
204 Self { ptr }
205 }
206 }
207
208 impl<T: ?Sized> Drop for DropGuard<T> {
209 #[inline]
210 fn drop(&mut self) {
211 // SAFETY: A `DropGuard` can only be c
212 // ensuring that this operation is saf
213 unsafe { ptr::drop_in_place(self.ptr)
214 }
215 }
216
217 /// Token used by `PinnedDrop` to prevent call
218 /// created struct. This is needed, because th
219 /// manually.
220 pub struct OnlyCallFromDrop(());
221
222 impl OnlyCallFromDrop {
223 /// # Safety
224 ///
225 /// This function should only be called fr
226 /// delegate the destruction to the pinned
227 pub unsafe fn new() -> Self {
228 Self(())
229 }
230 }
231
232 /// Initializer that always fails.
233 ///
234 /// Used by [`assert_pinned!`].
235 ///
236 /// [`assert_pinned!`]: crate::assert_pinned
237 pub struct AlwaysFail<T: ?Sized> {
238 _t: PhantomData<T>,
239 }
240
241 impl<T: ?Sized> AlwaysFail<T> {
242 /// Creates a new initializer that always
243 pub fn new() -> Self {
244 Self { _t: PhantomData }
245 }
246 }
247
248 impl<T: ?Sized> Default for AlwaysFail<T> {
249 fn default() -> Self {
250 Self::new()
251 }
252 }
253
254 // SAFETY: `__pinned_init` always fails, which
255 unsafe impl<T: ?Sized> PinInit<T, ()> for Alwa
256 unsafe fn __pinned_init(self, _slot: *mut
257 Err(())
258 }
259 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.