1 // SPDX-License-Identifier: Apache-2.0 OR MIT
2
3 //! This module provides the macros that actua
4 //! `pinned_drop`. It also contains `__init_in
5 //! macros.
6 //!
7 //! These macros should never be called direct
8 //! in a certain format which is internal. If
9 //! safe code! Use the public facing macros in
10 //!
11 //! This architecture has been chosen because
12 //! would make matters a lot easier for implem
13 //!
14 //! # Macro expansion example
15 //!
16 //! This section is intended for readers tryin
17 //! `pin_init!` macros from `init.rs`.
18 //!
19 //! We will look at the following example:
20 //!
21 //! ```rust,ignore
22 //! # use kernel::init::*;
23 //! # use core::pin::Pin;
24 //! #[pin_data]
25 //! #[repr(C)]
26 //! struct Bar<T> {
27 //! #[pin]
28 //! t: T,
29 //! pub x: usize,
30 //! }
31 //!
32 //! impl<T> Bar<T> {
33 //! fn new(t: T) -> impl PinInit<Self> {
34 //! pin_init!(Self { t, x: 0 })
35 //! }
36 //! }
37 //!
38 //! #[pin_data(PinnedDrop)]
39 //! struct Foo {
40 //! a: usize,
41 //! #[pin]
42 //! b: Bar<u32>,
43 //! }
44 //!
45 //! #[pinned_drop]
46 //! impl PinnedDrop for Foo {
47 //! fn drop(self: Pin<&mut Self>) {
48 //! pr_info!("{self:p} is getting drop
49 //! }
50 //! }
51 //!
52 //! let a = 42;
53 //! let initializer = pin_init!(Foo {
54 //! a,
55 //! b <- Bar::new(36),
56 //! });
57 //! ```
58 //!
59 //! This example includes the most common and
60 //!
61 //! Below you can find individual section abou
62 //! general things we need to take into accoun
63 //! - use global paths, similarly to file path
64 //! this ensures that the correct item is us
65 //! and then their own `panic!` inside to ex
66 //! - macro `unsafe` hygiene: we need to ensur
67 //! expressions inside of an `unsafe` block
68 //! `unsafe` operations without an associate
69 //!
70 //! ## `#[pin_data]` on `Bar`
71 //!
72 //! This macro is used to specify which fields
73 //! is placed on the struct definition and all
74 //!
75 //! Here is the definition of `Bar` from our e
76 //!
77 //! ```rust,ignore
78 //! # use kernel::init::*;
79 //! #[pin_data]
80 //! #[repr(C)]
81 //! struct Bar<T> {
82 //! #[pin]
83 //! t: T,
84 //! pub x: usize,
85 //! }
86 //! ```
87 //!
88 //! This expands to the following code:
89 //!
90 //! ```rust,ignore
91 //! // Firstly the normal definition of the st
92 //! #[repr(C)]
93 //! struct Bar<T> {
94 //! t: T,
95 //! pub x: usize,
96 //! }
97 //! // Then an anonymous constant is defined,
98 //! // types that we define inside:
99 //! const _: () = {
100 //! // We define the pin-data carrying str
101 //! // since we need to implement access f
102 //! // type.
103 //! struct __ThePinData<T> {
104 //! __phantom: ::core::marker::Phantom
105 //! }
106 //! // We implement `Copy` for the pin-dat
107 //! // `self` by value.
108 //! impl<T> ::core::clone::Clone for __The
109 //! fn clone(&self) -> Self {
110 //! *self
111 //! }
112 //! }
113 //! impl<T> ::core::marker::Copy for __The
114 //! // For every field of `Bar`, the pin-d
115 //! // and accessor (`pub` or `pub(crate)`
116 //! // field (`slot`) and a `PinInit` or `
117 //! // (if pinning is structural for the f
118 //! #[allow(dead_code)]
119 //! impl<T> __ThePinData<T> {
120 //! unsafe fn t<E>(
121 //! self,
122 //! slot: *mut T,
123 //! // Since `t` is `#[pin]`, this
124 //! init: impl ::kernel::init::Pin
125 //! ) -> ::core::result::Result<(), E>
126 //! unsafe { ::kernel::init::PinIn
127 //! }
128 //! pub unsafe fn x<E>(
129 //! self,
130 //! slot: *mut usize,
131 //! // Since `x` is not `#[pin]`,
132 //! init: impl ::kernel::init::Ini
133 //! ) -> ::core::result::Result<(), E>
134 //! unsafe { ::kernel::init::Init:
135 //! }
136 //! }
137 //! // Implement the internal `HasPinData`
138 //! // that we constructed above.
139 //! unsafe impl<T> ::kernel::init::__inter
140 //! type PinData = __ThePinData<T>;
141 //! unsafe fn __pin_data() -> Self::Pi
142 //! __ThePinData {
143 //! __phantom: ::core::marker:
144 //! }
145 //! }
146 //! }
147 //! // Implement the internal `PinData` tr
148 //! // struct. This is important to ensure
149 //! // function without using `unsafe`.
150 //! unsafe impl<T> ::kernel::init::__inter
151 //! type Datee = Bar<T>;
152 //! }
153 //! // Now we only want to implement `Unpi
154 //! // `Unpin`. In other words, whether `B
155 //! // fields (those marked with `#[pin]`)
156 //! // case no such fields exist, hence th
157 //! // for two reasons:
158 //! // - `__phantom`: every generic must b
159 //! // are used, we declare all and then
160 //! // - `__phantom_pin`: uses the `'__pin
161 //! // over it. The lifetime is needed t
162 //! // not be trivial, e.g. the user has
163 //! // unconditionally `!Unpin` and resu
164 //! // into accepting these bounds regar
165 //! #[allow(dead_code)]
166 //! struct __Unpin<'__pin, T> {
167 //! __phantom_pin: ::core::marker::Pha
168 //! __phantom: ::core::marker::Phantom
169 //! // Our only `#[pin]` field is `t`.
170 //! t: T,
171 //! }
172 //! #[doc(hidden)]
173 //! impl<'__pin, T> ::core::marker::Unpin
174 //! where
175 //! __Unpin<'__pin, T>: ::core::marker
176 //! {}
177 //! // Now we need to ensure that `Bar` do
178 //! // access to `&mut self` inside of `dr
179 //! // UB with only safe code, so we disal
180 //! // a direct impl and a blanket impleme
181 //! trait MustNotImplDrop {}
182 //! // Normally `Drop` bounds do not have
183 //! // (normally people want to know if a
184 //! // to know if it has any kind of custo
185 //! #[allow(drop_bounds)]
186 //! impl<T: ::core::ops::Drop> MustNotImpl
187 //! impl<T> MustNotImplDrop for Bar<T> {}
188 //! // Here comes a convenience check, if
189 //! // `#[pin_data]`, then this will error
190 //! // for safety, but a good sanity check
191 //! #[allow(non_camel_case_types)]
192 //! trait UselessPinnedDropImpl_you_need_t
193 //! impl<
194 //! T: ::kernel::init::PinnedDrop,
195 //! > UselessPinnedDropImpl_you_need_to_sp
196 //! impl<T> UselessPinnedDropImpl_you_need
197 //! };
198 //! ```
199 //!
200 //! ## `pin_init!` in `impl Bar`
201 //!
202 //! This macro creates an pin-initializer for
203 //! annotated by `#[pin_data]`.
204 //!
205 //! Here is the impl on `Bar` defining the new
206 //!
207 //! ```rust,ignore
208 //! impl<T> Bar<T> {
209 //! fn new(t: T) -> impl PinInit<Self> {
210 //! pin_init!(Self { t, x: 0 })
211 //! }
212 //! }
213 //! ```
214 //!
215 //! This expands to the following code:
216 //!
217 //! ```rust,ignore
218 //! impl<T> Bar<T> {
219 //! fn new(t: T) -> impl PinInit<Self> {
220 //! {
221 //! // We do not want to allow arb
222 //! // return type and shadow it l
223 //! // there will be no possibilit
224 //! struct __InitOk;
225 //! // Get the data about fields f
226 //! // - the function is unsafe, h
227 //! // - we `use` the `HasPinData`
228 //! // scope.
229 //! let data = unsafe {
230 //! use ::kernel::init::__inte
231 //! Self::__pin_data()
232 //! };
233 //! // Ensure that `data` really i
234 //! let init = ::kernel::init::__i
235 //! _,
236 //! __InitOk,
237 //! ::core::convert::Infallibl
238 //! >(data, move |slot| {
239 //! {
240 //! // Shadow the structur
241 //! // tries to write `ret
242 //! // since that will ref
243 //! // above.
244 //! struct __InitOk;
245 //! // This is the expansi
246 //! {
247 //! unsafe { ::core::p
248 //! }
249 //! // Since initializatio
250 //! // error type is `Infa
251 //! // is an error later.
252 //! // dropped and has not
253 //! let __t_guard = unsafe
254 //! ::pinned_init::__i
255 //! };
256 //! // Expansion of `x: 0,
257 //! // Since this can be a
258 //! // of the `unsafe` blo
259 //! {
260 //! let x = 0;
261 //! unsafe { ::core::p
262 //! }
263 //! // We again create a `
264 //! let __x_guard = unsafe
265 //! ::kernel::init::__
266 //! };
267 //! // Since initializatio
268 //! // the guards. This is
269 //! // `&DropGuard`.
270 //! ::core::mem::forget(__
271 //! ::core::mem::forget(__
272 //! // Here we use the typ
273 //! // initialized exactly
274 //! // executed, but still
275 //! // Additionally we abu
276 //! // for the struct. Thi
277 //! // accessible from thi
278 //! #[allow(unreachable_co
279 //! let _ = || {
280 //! unsafe {
281 //! ::core::ptr::w
282 //! slot,
283 //! Self {
284 //! // We
285 //! // her
286 //! // one
287 //! t: ::c
288 //! x: ::c
289 //! },
290 //! );
291 //! };
292 //! };
293 //! }
294 //! // We leave the scope abov
295 //! // `__InitOk` that we need
296 //! Ok(__InitOk)
297 //! });
298 //! // Change the return type from
299 //! let init = move |
300 //! slot,
301 //! | -> ::core::result::Result<()
302 //! init(slot).map(|__InitOk|
303 //! };
304 //! // Construct the initializer.
305 //! let init = unsafe {
306 //! ::kernel::init::pin_init_f
307 //! _,
308 //! ::core::convert::Infal
309 //! >(init)
310 //! };
311 //! init
312 //! }
313 //! }
314 //! }
315 //! ```
316 //!
317 //! ## `#[pin_data]` on `Foo`
318 //!
319 //! Since we already took a look at `#[pin_dat
320 //! differences/new things in the expansion of
321 //!
322 //! ```rust,ignore
323 //! #[pin_data(PinnedDrop)]
324 //! struct Foo {
325 //! a: usize,
326 //! #[pin]
327 //! b: Bar<u32>,
328 //! }
329 //! ```
330 //!
331 //! This expands to the following code:
332 //!
333 //! ```rust,ignore
334 //! struct Foo {
335 //! a: usize,
336 //! b: Bar<u32>,
337 //! }
338 //! const _: () = {
339 //! struct __ThePinData {
340 //! __phantom: ::core::marker::Phantom
341 //! }
342 //! impl ::core::clone::Clone for __ThePin
343 //! fn clone(&self) -> Self {
344 //! *self
345 //! }
346 //! }
347 //! impl ::core::marker::Copy for __ThePin
348 //! #[allow(dead_code)]
349 //! impl __ThePinData {
350 //! unsafe fn b<E>(
351 //! self,
352 //! slot: *mut Bar<u32>,
353 //! init: impl ::kernel::init::Pin
354 //! ) -> ::core::result::Result<(), E>
355 //! unsafe { ::kernel::init::PinIn
356 //! }
357 //! unsafe fn a<E>(
358 //! self,
359 //! slot: *mut usize,
360 //! init: impl ::kernel::init::Ini
361 //! ) -> ::core::result::Result<(), E>
362 //! unsafe { ::kernel::init::Init:
363 //! }
364 //! }
365 //! unsafe impl ::kernel::init::__internal
366 //! type PinData = __ThePinData;
367 //! unsafe fn __pin_data() -> Self::Pi
368 //! __ThePinData {
369 //! __phantom: ::core::marker:
370 //! }
371 //! }
372 //! }
373 //! unsafe impl ::kernel::init::__internal
374 //! type Datee = Foo;
375 //! }
376 //! #[allow(dead_code)]
377 //! struct __Unpin<'__pin> {
378 //! __phantom_pin: ::core::marker::Pha
379 //! __phantom: ::core::marker::Phantom
380 //! b: Bar<u32>,
381 //! }
382 //! #[doc(hidden)]
383 //! impl<'__pin> ::core::marker::Unpin for
384 //! where
385 //! __Unpin<'__pin>: ::core::marker::U
386 //! {}
387 //! // Since we specified `PinnedDrop` as
388 //! // implement `PinnedDrop`. Thus we do
389 //! // before, instead we implement `Drop`
390 //! impl ::core::ops::Drop for Foo {
391 //! fn drop(&mut self) {
392 //! // Since we are getting droppe
393 //! // can assume that we never mo
394 //! let pinned = unsafe { ::core::
395 //! // Create the unsafe token tha
396 //! // type is only allowed to be
397 //! let token = unsafe { ::kernel:
398 //! ::kernel::init::PinnedDrop::dr
399 //! }
400 //! }
401 //! };
402 //! ```
403 //!
404 //! ## `#[pinned_drop]` on `impl PinnedDrop fo
405 //!
406 //! This macro is used to implement the `Pinne
407 //! extra parameter that should not be used at
408 //!
409 //! Here is the `PinnedDrop` impl for `Foo`:
410 //!
411 //! ```rust,ignore
412 //! #[pinned_drop]
413 //! impl PinnedDrop for Foo {
414 //! fn drop(self: Pin<&mut Self>) {
415 //! pr_info!("{self:p} is getting drop
416 //! }
417 //! }
418 //! ```
419 //!
420 //! This expands to the following code:
421 //!
422 //! ```rust,ignore
423 //! // `unsafe`, full path and the token param
424 //! unsafe impl ::kernel::init::PinnedDrop for
425 //! fn drop(self: Pin<&mut Self>, _: ::ker
426 //! pr_info!("{self:p} is getting drop
427 //! }
428 //! }
429 //! ```
430 //!
431 //! ## `pin_init!` on `Foo`
432 //!
433 //! Since we already took a look at `pin_init!
434 //! of `pin_init!` on `Foo`:
435 //!
436 //! ```rust,ignore
437 //! let a = 42;
438 //! let initializer = pin_init!(Foo {
439 //! a,
440 //! b <- Bar::new(36),
441 //! });
442 //! ```
443 //!
444 //! This expands to the following code:
445 //!
446 //! ```rust,ignore
447 //! let a = 42;
448 //! let initializer = {
449 //! struct __InitOk;
450 //! let data = unsafe {
451 //! use ::kernel::init::__internal::Ha
452 //! Foo::__pin_data()
453 //! };
454 //! let init = ::kernel::init::__internal:
455 //! _,
456 //! __InitOk,
457 //! ::core::convert::Infallible,
458 //! >(data, move |slot| {
459 //! {
460 //! struct __InitOk;
461 //! {
462 //! unsafe { ::core::ptr::writ
463 //! }
464 //! let __a_guard = unsafe {
465 //! ::kernel::init::__internal
466 //! };
467 //! let init = Bar::new(36);
468 //! unsafe { data.b(::core::addr_o
469 //! let __b_guard = unsafe {
470 //! ::kernel::init::__internal
471 //! };
472 //! ::core::mem::forget(__b_guard)
473 //! ::core::mem::forget(__a_guard)
474 //! #[allow(unreachable_code, clip
475 //! let _ = || {
476 //! unsafe {
477 //! ::core::ptr::write(
478 //! slot,
479 //! Foo {
480 //! a: ::core::pan
481 //! b: ::core::pan
482 //! },
483 //! );
484 //! };
485 //! };
486 //! }
487 //! Ok(__InitOk)
488 //! });
489 //! let init = move |
490 //! slot,
491 //! | -> ::core::result::Result<(), ::core
492 //! init(slot).map(|__InitOk| ())
493 //! };
494 //! let init = unsafe {
495 //! ::kernel::init::pin_init_from_clos
496 //! };
497 //! init
498 //! };
499 //! ```
500
501 /// Creates a `unsafe impl<...> PinnedDrop for
502 ///
503 /// See [`PinnedDrop`] for more information.
504 #[doc(hidden)]
505 #[macro_export]
506 macro_rules! __pinned_drop {
507 (
508 @impl_sig($($impl_sig:tt)*),
509 @impl_body(
510 $(#[$($attr:tt)*])*
511 fn drop($($sig:tt)*) {
512 $($inner:tt)*
513 }
514 ),
515 ) => {
516 unsafe $($impl_sig)* {
517 // Inherit all attributes and the
518 $(#[$($attr)*])*
519 fn drop($($sig)*, _: $crate::init:
520 $($inner)*
521 }
522 }
523 }
524 }
525
526 /// This macro first parses the struct definit
527 /// fields. Afterwards it declares the struct
528 #[doc(hidden)]
529 #[macro_export]
530 macro_rules! __pin_data {
531 // Proc-macro entry point, this is supplie
532 (parse_input:
533 @args($($pinned_drop:ident)?),
534 @sig(
535 $(#[$($struct_attr:tt)*])*
536 $vis:vis struct $name:ident
537 $(where $($whr:tt)*)?
538 ),
539 @impl_generics($($impl_generics:tt)*),
540 @ty_generics($($ty_generics:tt)*),
541 @decl_generics($($decl_generics:tt)*),
542 @body({ $($fields:tt)* }),
543 ) => {
544 // We now use token munching to iterat
545 // identify fields marked with `#[pin]
546 // wants these to be structurally pinn
547 // 'not pinned fields'. Additionally w
548 // order to declare the struct.
549 //
550 // In this call we also put some expla
551 $crate::__pin_data!(find_pinned_fields
552 // Attributes on the struct itself
553 // struct definition.
554 @struct_attrs($(#[$($struct_attr)*
555 // The visibility of the struct.
556 @vis($vis),
557 // The name of the struct.
558 @name($name),
559 // The 'impl generics', the generi
560 // of an `impl<$ty_generics>` bloc
561 @impl_generics($($impl_generics)*)
562 // The 'ty generics', the generics
563 @ty_generics($($ty_generics)*),
564 // The 'decl generics', the generi
565 // definition.
566 @decl_generics($($decl_generics)*)
567 // The where clause of any impl bl
568 @where($($($whr)*)?),
569 // The remaining fields tokens tha
570 // We add a `,` at the end to ensu
571 @fields_munch($($fields)* ,),
572 // The pinned fields.
573 @pinned(),
574 // The not pinned fields.
575 @not_pinned(),
576 // All fields.
577 @fields(),
578 // The accumulator containing all
579 @accum(),
580 // Contains `yes` or `` to indicat
581 @is_pinned(),
582 // The proc-macro argument, this s
583 @pinned_drop($($pinned_drop)?),
584 );
585 };
586 (find_pinned_fields:
587 @struct_attrs($($struct_attrs:tt)*),
588 @vis($vis:vis),
589 @name($name:ident),
590 @impl_generics($($impl_generics:tt)*),
591 @ty_generics($($ty_generics:tt)*),
592 @decl_generics($($decl_generics:tt)*),
593 @where($($whr:tt)*),
594 // We found a PhantomPinned field, thi
595 @fields_munch($field:ident : $($($(::)
596 @pinned($($pinned:tt)*),
597 @not_pinned($($not_pinned:tt)*),
598 @fields($($fields:tt)*),
599 @accum($($accum:tt)*),
600 // This field is not pinned.
601 @is_pinned(),
602 @pinned_drop($($pinned_drop:ident)?),
603 ) => {
604 ::core::compile_error!(concat!(
605 "The field `",
606 stringify!($field),
607 "` of type `PhantomPinned` only ha
608 ));
609 $crate::__pin_data!(find_pinned_fields
610 @struct_attrs($($struct_attrs)*),
611 @vis($vis),
612 @name($name),
613 @impl_generics($($impl_generics)*)
614 @ty_generics($($ty_generics)*),
615 @decl_generics($($decl_generics)*)
616 @where($($whr)*),
617 @fields_munch($($rest)*),
618 @pinned($($pinned)* $($accum)* $fi
619 @not_pinned($($not_pinned)*),
620 @fields($($fields)* $($accum)* $fi
621 @accum(),
622 @is_pinned(),
623 @pinned_drop($($pinned_drop)?),
624 );
625 };
626 (find_pinned_fields:
627 @struct_attrs($($struct_attrs:tt)*),
628 @vis($vis:vis),
629 @name($name:ident),
630 @impl_generics($($impl_generics:tt)*),
631 @ty_generics($($ty_generics:tt)*),
632 @decl_generics($($decl_generics:tt)*),
633 @where($($whr:tt)*),
634 // We reached the field declaration.
635 @fields_munch($field:ident : $type:ty,
636 @pinned($($pinned:tt)*),
637 @not_pinned($($not_pinned:tt)*),
638 @fields($($fields:tt)*),
639 @accum($($accum:tt)*),
640 // This field is pinned.
641 @is_pinned(yes),
642 @pinned_drop($($pinned_drop:ident)?),
643 ) => {
644 $crate::__pin_data!(find_pinned_fields
645 @struct_attrs($($struct_attrs)*),
646 @vis($vis),
647 @name($name),
648 @impl_generics($($impl_generics)*)
649 @ty_generics($($ty_generics)*),
650 @decl_generics($($decl_generics)*)
651 @where($($whr)*),
652 @fields_munch($($rest)*),
653 @pinned($($pinned)* $($accum)* $fi
654 @not_pinned($($not_pinned)*),
655 @fields($($fields)* $($accum)* $fi
656 @accum(),
657 @is_pinned(),
658 @pinned_drop($($pinned_drop)?),
659 );
660 };
661 (find_pinned_fields:
662 @struct_attrs($($struct_attrs:tt)*),
663 @vis($vis:vis),
664 @name($name:ident),
665 @impl_generics($($impl_generics:tt)*),
666 @ty_generics($($ty_generics:tt)*),
667 @decl_generics($($decl_generics:tt)*),
668 @where($($whr:tt)*),
669 // We reached the field declaration.
670 @fields_munch($field:ident : $type:ty,
671 @pinned($($pinned:tt)*),
672 @not_pinned($($not_pinned:tt)*),
673 @fields($($fields:tt)*),
674 @accum($($accum:tt)*),
675 // This field is not pinned.
676 @is_pinned(),
677 @pinned_drop($($pinned_drop:ident)?),
678 ) => {
679 $crate::__pin_data!(find_pinned_fields
680 @struct_attrs($($struct_attrs)*),
681 @vis($vis),
682 @name($name),
683 @impl_generics($($impl_generics)*)
684 @ty_generics($($ty_generics)*),
685 @decl_generics($($decl_generics)*)
686 @where($($whr)*),
687 @fields_munch($($rest)*),
688 @pinned($($pinned)*),
689 @not_pinned($($not_pinned)* $($acc
690 @fields($($fields)* $($accum)* $fi
691 @accum(),
692 @is_pinned(),
693 @pinned_drop($($pinned_drop)?),
694 );
695 };
696 (find_pinned_fields:
697 @struct_attrs($($struct_attrs:tt)*),
698 @vis($vis:vis),
699 @name($name:ident),
700 @impl_generics($($impl_generics:tt)*),
701 @ty_generics($($ty_generics:tt)*),
702 @decl_generics($($decl_generics:tt)*),
703 @where($($whr:tt)*),
704 // We found the `#[pin]` attr.
705 @fields_munch(#[pin] $($rest:tt)*),
706 @pinned($($pinned:tt)*),
707 @not_pinned($($not_pinned:tt)*),
708 @fields($($fields:tt)*),
709 @accum($($accum:tt)*),
710 @is_pinned($($is_pinned:ident)?),
711 @pinned_drop($($pinned_drop:ident)?),
712 ) => {
713 $crate::__pin_data!(find_pinned_fields
714 @struct_attrs($($struct_attrs)*),
715 @vis($vis),
716 @name($name),
717 @impl_generics($($impl_generics)*)
718 @ty_generics($($ty_generics)*),
719 @decl_generics($($decl_generics)*)
720 @where($($whr)*),
721 @fields_munch($($rest)*),
722 // We do not include `#[pin]` in t
723 // attribute that is defined somew
724 @pinned($($pinned)*),
725 @not_pinned($($not_pinned)*),
726 @fields($($fields)*),
727 @accum($($accum)*),
728 // Set this to `yes`.
729 @is_pinned(yes),
730 @pinned_drop($($pinned_drop)?),
731 );
732 };
733 (find_pinned_fields:
734 @struct_attrs($($struct_attrs:tt)*),
735 @vis($vis:vis),
736 @name($name:ident),
737 @impl_generics($($impl_generics:tt)*),
738 @ty_generics($($ty_generics:tt)*),
739 @decl_generics($($decl_generics:tt)*),
740 @where($($whr:tt)*),
741 // We reached the field declaration wi
742 // visibility and put it into `$accum`
743 @fields_munch($fvis:vis $field:ident $
744 @pinned($($pinned:tt)*),
745 @not_pinned($($not_pinned:tt)*),
746 @fields($($fields:tt)*),
747 @accum($($accum:tt)*),
748 @is_pinned($($is_pinned:ident)?),
749 @pinned_drop($($pinned_drop:ident)?),
750 ) => {
751 $crate::__pin_data!(find_pinned_fields
752 @struct_attrs($($struct_attrs)*),
753 @vis($vis),
754 @name($name),
755 @impl_generics($($impl_generics)*)
756 @ty_generics($($ty_generics)*),
757 @decl_generics($($decl_generics)*)
758 @where($($whr)*),
759 @fields_munch($field $($rest)*),
760 @pinned($($pinned)*),
761 @not_pinned($($not_pinned)*),
762 @fields($($fields)*),
763 @accum($($accum)* $fvis),
764 @is_pinned($($is_pinned)?),
765 @pinned_drop($($pinned_drop)?),
766 );
767 };
768 (find_pinned_fields:
769 @struct_attrs($($struct_attrs:tt)*),
770 @vis($vis:vis),
771 @name($name:ident),
772 @impl_generics($($impl_generics:tt)*),
773 @ty_generics($($ty_generics:tt)*),
774 @decl_generics($($decl_generics:tt)*),
775 @where($($whr:tt)*),
776 // Some other attribute, just put it i
777 @fields_munch(#[$($attr:tt)*] $($rest:
778 @pinned($($pinned:tt)*),
779 @not_pinned($($not_pinned:tt)*),
780 @fields($($fields:tt)*),
781 @accum($($accum:tt)*),
782 @is_pinned($($is_pinned:ident)?),
783 @pinned_drop($($pinned_drop:ident)?),
784 ) => {
785 $crate::__pin_data!(find_pinned_fields
786 @struct_attrs($($struct_attrs)*),
787 @vis($vis),
788 @name($name),
789 @impl_generics($($impl_generics)*)
790 @ty_generics($($ty_generics)*),
791 @decl_generics($($decl_generics)*)
792 @where($($whr)*),
793 @fields_munch($($rest)*),
794 @pinned($($pinned)*),
795 @not_pinned($($not_pinned)*),
796 @fields($($fields)*),
797 @accum($($accum)* #[$($attr)*]),
798 @is_pinned($($is_pinned)?),
799 @pinned_drop($($pinned_drop)?),
800 );
801 };
802 (find_pinned_fields:
803 @struct_attrs($($struct_attrs:tt)*),
804 @vis($vis:vis),
805 @name($name:ident),
806 @impl_generics($($impl_generics:tt)*),
807 @ty_generics($($ty_generics:tt)*),
808 @decl_generics($($decl_generics:tt)*),
809 @where($($whr:tt)*),
810 // We reached the end of the fields, p
811 // before and the user is also allowed
812 @fields_munch($(,)?),
813 @pinned($($pinned:tt)*),
814 @not_pinned($($not_pinned:tt)*),
815 @fields($($fields:tt)*),
816 @accum(),
817 @is_pinned(),
818 @pinned_drop($($pinned_drop:ident)?),
819 ) => {
820 // Declare the struct with all fields
821 $($struct_attrs)*
822 $vis struct $name <$($decl_generics)*>
823 where $($whr)*
824 {
825 $($fields)*
826 }
827
828 // We put the rest into this const ite
829 // outside.
830 const _: () = {
831 // We declare this struct which wi
832 // it will be invariant over all g
833 // struct.
834 $vis struct __ThePinData<$($impl_g
835 where $($whr)*
836 {
837 __phantom: ::core::marker::Pha
838 fn($name<$($ty_generics)*>
839 >,
840 }
841
842 impl<$($impl_generics)*> ::core::c
843 where $($whr)*
844 {
845 fn clone(&self) -> Self { *sel
846 }
847
848 impl<$($impl_generics)*> ::core::m
849 where $($whr)*
850 {}
851
852 // Make all projection functions.
853 $crate::__pin_data!(make_pin_data:
854 @pin_data(__ThePinData),
855 @impl_generics($($impl_generic
856 @ty_generics($($ty_generics)*)
857 @where($($whr)*),
858 @pinned($($pinned)*),
859 @not_pinned($($not_pinned)*),
860 );
861
862 // SAFETY: We have added the corre
863 // we also use the least restricti
864 unsafe impl<$($impl_generics)*>
865 $crate::init::__internal::HasP
866 where $($whr)*
867 {
868 type PinData = __ThePinData<$(
869
870 unsafe fn __pin_data() -> Self
871 __ThePinData { __phantom:
872 }
873 }
874
875 unsafe impl<$($impl_generics)*>
876 $crate::init::__internal::PinD
877 where $($whr)*
878 {
879 type Datee = $name<$($ty_gener
880 }
881
882 // This struct will be used for th
883 // fields are relevant whether the
884 #[allow(dead_code)]
885 struct __Unpin <'__pin, $($impl_ge
886 where $($whr)*
887 {
888 __phantom_pin: ::core::marker:
889 __phantom: ::core::marker::Pha
890 fn($name<$($ty_generics)*>
891 >,
892 // Only the pinned fields.
893 $($pinned)*
894 }
895
896 #[doc(hidden)]
897 impl<'__pin, $($impl_generics)*> :
898 where
899 __Unpin<'__pin, $($ty_generics
900 $($whr)*
901 {}
902
903 // We need to disallow normal `Dro
904 // whether `PinnedDrop` was specif
905 $crate::__pin_data!(drop_preventio
906 @name($name),
907 @impl_generics($($impl_generic
908 @ty_generics($($ty_generics)*)
909 @where($($whr)*),
910 @pinned_drop($($pinned_drop)?)
911 );
912 };
913 };
914 // When no `PinnedDrop` was specified, the
915 (drop_prevention:
916 @name($name:ident),
917 @impl_generics($($impl_generics:tt)*),
918 @ty_generics($($ty_generics:tt)*),
919 @where($($whr:tt)*),
920 @pinned_drop(),
921 ) => {
922 // We prevent this by creating a trait
923 // `Drop`. Additionally we will implem
924 // if it also implements `Drop`
925 trait MustNotImplDrop {}
926 #[allow(drop_bounds)]
927 impl<T: ::core::ops::Drop> MustNotImpl
928 impl<$($impl_generics)*> MustNotImplDr
929 where $($whr)* {}
930 // We also take care to prevent users
931 // They might implement `PinnedDrop` c
932 // `PinnedDrop` as the parameter to `#
933 #[allow(non_camel_case_types)]
934 trait UselessPinnedDropImpl_you_need_t
935 impl<T: $crate::init::PinnedDrop>
936 UselessPinnedDropImpl_you_need_to_
937 impl<$($impl_generics)*>
938 UselessPinnedDropImpl_you_need_to_
939 where $($whr)* {}
940 };
941 // When `PinnedDrop` was specified we just
942 (drop_prevention:
943 @name($name:ident),
944 @impl_generics($($impl_generics:tt)*),
945 @ty_generics($($ty_generics:tt)*),
946 @where($($whr:tt)*),
947 @pinned_drop(PinnedDrop),
948 ) => {
949 impl<$($impl_generics)*> ::core::ops::
950 where $($whr)*
951 {
952 fn drop(&mut self) {
953 // SAFETY: Since this is a des
954 // terminates, since it is ina
955 let pinned = unsafe { ::core::
956 // SAFETY: Since this is a dro
957 // pinned destructor of this t
958 let token = unsafe { $crate::i
959 $crate::init::PinnedDrop::drop
960 }
961 }
962 };
963 // If some other parameter was specified,
964 (drop_prevention:
965 @name($name:ident),
966 @impl_generics($($impl_generics:tt)*),
967 @ty_generics($($ty_generics:tt)*),
968 @where($($whr:tt)*),
969 @pinned_drop($($rest:tt)*),
970 ) => {
971 compile_error!(
972 "Wrong parameters to `#[pin_data]`
973 stringify!($($rest)*),
974 );
975 };
976 (make_pin_data:
977 @pin_data($pin_data:ident),
978 @impl_generics($($impl_generics:tt)*),
979 @ty_generics($($ty_generics:tt)*),
980 @where($($whr:tt)*),
981 @pinned($($(#[$($p_attr:tt)*])* $pvis:
982 @not_pinned($($(#[$($attr:tt)*])* $fvi
983 ) => {
984 // For every field, we create a projec
985 // field is structurally pinned, then
986 // structurally pinned, then it can be
987 //
988 // The functions are `unsafe` to preve
989 #[allow(dead_code)]
990 impl<$($impl_generics)*> $pin_data<$($
991 where $($whr)*
992 {
993 $(
994 $(#[$($p_attr)*])*
995 $pvis unsafe fn $p_field<E>(
996 self,
997 slot: *mut $p_type,
998 init: impl $crate::init::P
999 ) -> ::core::result::Result<()
1000 unsafe { $crate::init::Pi
1001 }
1002 )*
1003 $(
1004 $(#[$($attr)*])*
1005 $fvis unsafe fn $field<E>(
1006 self,
1007 slot: *mut $type,
1008 init: impl $crate::init::
1009 ) -> ::core::result::Result<(
1010 unsafe { $crate::init::In
1011 }
1012 )*
1013 }
1014 };
1015 }
1016
1017 /// The internal init macro. Do not call manu
1018 ///
1019 /// This is called by the `{try_}{pin_}init!`
1020 ///
1021 /// This macro has multiple internal call con
1022 /// - nothing: this is the base case and call
1023 /// - `with_update_parsed`: when the `..Zeroa
1024 /// - `init_slot`: recursively creates the co
1025 /// - `make_initializer`: recursively create
1026 /// field has been initialized exactly once
1027 #[doc(hidden)]
1028 #[macro_export]
1029 macro_rules! __init_internal {
1030 (
1031 @this($($this:ident)?),
1032 @typ($t:path),
1033 @fields($($fields:tt)*),
1034 @error($err:ty),
1035 // Either `PinData` or `InitData`, `$
1036 // case.
1037 @data($data:ident, $($use_data:ident)
1038 // `HasPinData` or `HasInitData`.
1039 @has_data($has_data:ident, $get_data:
1040 // `pin_init_from_closure` or `init_f
1041 @construct_closure($construct_closure
1042 @munch_fields(),
1043 ) => {
1044 $crate::__init_internal!(with_update_
1045 @this($($this)?),
1046 @typ($t),
1047 @fields($($fields)*),
1048 @error($err),
1049 @data($data, $($use_data)?),
1050 @has_data($has_data, $get_data),
1051 @construct_closure($construct_clo
1052 @zeroed(), // Nothing means defau
1053 )
1054 };
1055 (
1056 @this($($this:ident)?),
1057 @typ($t:path),
1058 @fields($($fields:tt)*),
1059 @error($err:ty),
1060 // Either `PinData` or `InitData`, `$
1061 // case.
1062 @data($data:ident, $($use_data:ident)
1063 // `HasPinData` or `HasInitData`.
1064 @has_data($has_data:ident, $get_data:
1065 // `pin_init_from_closure` or `init_f
1066 @construct_closure($construct_closure
1067 @munch_fields(..Zeroable::zeroed()),
1068 ) => {
1069 $crate::__init_internal!(with_update_
1070 @this($($this)?),
1071 @typ($t),
1072 @fields($($fields)*),
1073 @error($err),
1074 @data($data, $($use_data)?),
1075 @has_data($has_data, $get_data),
1076 @construct_closure($construct_clo
1077 @zeroed(()), // `()` means zero a
1078 )
1079 };
1080 (
1081 @this($($this:ident)?),
1082 @typ($t:path),
1083 @fields($($fields:tt)*),
1084 @error($err:ty),
1085 // Either `PinData` or `InitData`, `$
1086 // case.
1087 @data($data:ident, $($use_data:ident)
1088 // `HasPinData` or `HasInitData`.
1089 @has_data($has_data:ident, $get_data:
1090 // `pin_init_from_closure` or `init_f
1091 @construct_closure($construct_closure
1092 @munch_fields($ignore:tt $($rest:tt)*
1093 ) => {
1094 $crate::__init_internal!(
1095 @this($($this)?),
1096 @typ($t),
1097 @fields($($fields)*),
1098 @error($err),
1099 @data($data, $($use_data)?),
1100 @has_data($has_data, $get_data),
1101 @construct_closure($construct_clo
1102 @munch_fields($($rest)*),
1103 )
1104 };
1105 (with_update_parsed:
1106 @this($($this:ident)?),
1107 @typ($t:path),
1108 @fields($($fields:tt)*),
1109 @error($err:ty),
1110 // Either `PinData` or `InitData`, `$
1111 // case.
1112 @data($data:ident, $($use_data:ident)
1113 // `HasPinData` or `HasInitData`.
1114 @has_data($has_data:ident, $get_data:
1115 // `pin_init_from_closure` or `init_f
1116 @construct_closure($construct_closure
1117 @zeroed($($init_zeroed:expr)?),
1118 ) => {{
1119 // We do not want to allow arbitrary
1120 // type and shadow it later when we i
1121 // no possibility of returning withou
1122 struct __InitOk;
1123 // Get the data about fields from the
1124 let data = unsafe {
1125 use $crate::init::__internal::$ha
1126 // Here we abuse `paste!` to reto
1127 // information that is associated
1128 // cannot be used in this positio
1129 // code.
1130 ::kernel::macros::paste!($t::$get
1131 };
1132 // Ensure that `data` really is of ty
1133 let init = $crate::init::__internal::
1134 data,
1135 move |slot| {
1136 {
1137 // Shadow the structure s
1138 struct __InitOk;
1139 // If `$init_zeroed` is p
1140 // error when fields are
1141 // check that the type ac
1142 $({
1143 fn assert_zeroable<T:
1144 // Ensure that the st
1145 assert_zeroable(slot)
1146 // SAFETY: The type i
1147 unsafe { ::core::ptr:
1148 $init_zeroed // This
1149 })?
1150 // Create the `this` so i
1151 // expressions creating t
1152 $(let $this = unsafe { ::
1153 // Initialize every field
1154 $crate::__init_internal!(
1155 @data(data),
1156 @slot(slot),
1157 @guards(),
1158 @munch_fields($($fiel
1159 );
1160 // We use unreachable cod
1161 // once, this struct init
1162 // very natural error mes
1163 #[allow(unreachable_code,
1164 let _ = || {
1165 $crate::__init_intern
1166 @slot(slot),
1167 @type_name($t),
1168 @munch_fields($($
1169 @acc(),
1170 );
1171 };
1172 }
1173 Ok(__InitOk)
1174 }
1175 );
1176 let init = move |slot| -> ::core::res
1177 init(slot).map(|__InitOk| ())
1178 };
1179 let init = unsafe { $crate::init::$co
1180 init
1181 }};
1182 (init_slot($($use_data:ident)?):
1183 @data($data:ident),
1184 @slot($slot:ident),
1185 @guards($($guards:ident,)*),
1186 @munch_fields($(..Zeroable::zeroed())
1187 ) => {
1188 // Endpoint of munching, no fields ar
1189 // have been initialized. Therefore w
1190 $(::core::mem::forget($guards);)*
1191 };
1192 (init_slot($use_data:ident): // `use_data
1193 @data($data:ident),
1194 @slot($slot:ident),
1195 @guards($($guards:ident,)*),
1196 // In-place initialization syntax.
1197 @munch_fields($field:ident <- $val:ex
1198 ) => {
1199 let init = $val;
1200 // Call the initializer.
1201 //
1202 // SAFETY: `slot` is valid, because w
1203 // return when an error/panic occurs.
1204 // We also use the `data` to require
1205 unsafe { $data.$field(::core::ptr::ad
1206 // Create the drop guard:
1207 //
1208 // We rely on macro hygiene to make i
1209 // We use `paste!` to create new hygi
1210 ::kernel::macros::paste! {
1211 // SAFETY: We forget the guard la
1212 let [< __ $field _guard >] = unsa
1213 $crate::init::__internal::Dro
1214 };
1215
1216 $crate::__init_internal!(init_slo
1217 @data($data),
1218 @slot($slot),
1219 @guards([< __ $field _guard >
1220 @munch_fields($($rest)*),
1221 );
1222 }
1223 };
1224 (init_slot(): // No `use_data`, so we use
1225 @data($data:ident),
1226 @slot($slot:ident),
1227 @guards($($guards:ident,)*),
1228 // In-place initialization syntax.
1229 @munch_fields($field:ident <- $val:ex
1230 ) => {
1231 let init = $val;
1232 // Call the initializer.
1233 //
1234 // SAFETY: `slot` is valid, because w
1235 // return when an error/panic occurs.
1236 unsafe { $crate::init::Init::__init(i
1237 // Create the drop guard:
1238 //
1239 // We rely on macro hygiene to make i
1240 // We use `paste!` to create new hygi
1241 ::kernel::macros::paste! {
1242 // SAFETY: We forget the guard la
1243 let [< __ $field _guard >] = unsa
1244 $crate::init::__internal::Dro
1245 };
1246
1247 $crate::__init_internal!(init_slo
1248 @data($data),
1249 @slot($slot),
1250 @guards([< __ $field _guard >
1251 @munch_fields($($rest)*),
1252 );
1253 }
1254 };
1255 (init_slot($($use_data:ident)?):
1256 @data($data:ident),
1257 @slot($slot:ident),
1258 @guards($($guards:ident,)*),
1259 // Init by-value.
1260 @munch_fields($field:ident $(: $val:e
1261 ) => {
1262 {
1263 $(let $field = $val;)?
1264 // Initialize the field.
1265 //
1266 // SAFETY: The memory at `slot` i
1267 unsafe { ::core::ptr::write(::cor
1268 }
1269 // Create the drop guard:
1270 //
1271 // We rely on macro hygiene to make i
1272 // We use `paste!` to create new hygi
1273 ::kernel::macros::paste! {
1274 // SAFETY: We forget the guard la
1275 let [< __ $field _guard >] = unsa
1276 $crate::init::__internal::Dro
1277 };
1278
1279 $crate::__init_internal!(init_slo
1280 @data($data),
1281 @slot($slot),
1282 @guards([< __ $field _guard >
1283 @munch_fields($($rest)*),
1284 );
1285 }
1286 };
1287 (make_initializer:
1288 @slot($slot:ident),
1289 @type_name($t:path),
1290 @munch_fields(..Zeroable::zeroed() $(
1291 @acc($($acc:tt)*),
1292 ) => {
1293 // Endpoint, nothing more to munch, c
1294 // `..Zeroable::zeroed()`, the slot w
1295 // not been overwritten are thus zero
1296 // actually accessible by using the s
1297 // We are inside of a closure that is
1298 // get the correct type inference her
1299 #[allow(unused_assignments)]
1300 unsafe {
1301 let mut zeroed = ::core::mem::zer
1302 // We have to use type inference
1303 // not get executed, so it has no
1304 ::core::ptr::write($slot, zeroed)
1305 zeroed = ::core::mem::zeroed();
1306 // Here we abuse `paste!` to reto
1307 // information that is associated
1308 // cannot be used in this positio
1309 // code.
1310 ::kernel::macros::paste!(
1311 ::core::ptr::write($slot, $t
1312 $($acc)*
1313 ..zeroed
1314 });
1315 );
1316 }
1317 };
1318 (make_initializer:
1319 @slot($slot:ident),
1320 @type_name($t:path),
1321 @munch_fields($(,)?),
1322 @acc($($acc:tt)*),
1323 ) => {
1324 // Endpoint, nothing more to munch, c
1325 // Since we are in the closure that i
1326 // We abuse `slot` to get the correct
1327 unsafe {
1328 // Here we abuse `paste!` to reto
1329 // information that is associated
1330 // cannot be used in this positio
1331 // code.
1332 ::kernel::macros::paste!(
1333 ::core::ptr::write($slot, $t
1334 $($acc)*
1335 });
1336 );
1337 }
1338 };
1339 (make_initializer:
1340 @slot($slot:ident),
1341 @type_name($t:path),
1342 @munch_fields($field:ident <- $val:ex
1343 @acc($($acc:tt)*),
1344 ) => {
1345 $crate::__init_internal!(make_initial
1346 @slot($slot),
1347 @type_name($t),
1348 @munch_fields($($rest)*),
1349 @acc($($acc)* $field: ::core::pan
1350 );
1351 };
1352 (make_initializer:
1353 @slot($slot:ident),
1354 @type_name($t:path),
1355 @munch_fields($field:ident $(: $val:e
1356 @acc($($acc:tt)*),
1357 ) => {
1358 $crate::__init_internal!(make_initial
1359 @slot($slot),
1360 @type_name($t),
1361 @munch_fields($($rest)*),
1362 @acc($($acc)* $field: ::core::pan
1363 );
1364 };
1365 }
1366
1367 #[doc(hidden)]
1368 #[macro_export]
1369 macro_rules! __derive_zeroable {
1370 (parse_input:
1371 @sig(
1372 $(#[$($struct_attr:tt)*])*
1373 $vis:vis struct $name:ident
1374 $(where $($whr:tt)*)?
1375 ),
1376 @impl_generics($($impl_generics:tt)*)
1377 @ty_generics($($ty_generics:tt)*),
1378 @body({
1379 $(
1380 $(#[$($field_attr:tt)*])*
1381 $field:ident : $field_ty:ty
1382 ),* $(,)?
1383 }),
1384 ) => {
1385 // SAFETY: Every field type implement
1386 #[automatically_derived]
1387 unsafe impl<$($impl_generics)*> $crat
1388 where
1389 $($($whr)*)?
1390 {}
1391 const _: () = {
1392 fn assert_zeroable<T: ?::core::ma
1393 fn ensure_zeroable<$($impl_generi
1394 where $($($whr)*)?
1395 {
1396 $(assert_zeroable::<$field_ty
1397 }
1398 };
1399 };
1400 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.