xref: /linux/rust/zerocopy-derive/derive/project.rs (revision 486b257357c23743d9729ea715136d105fff461e)
1 // SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT
2 //
3 // Copyright 2026 The Fuchsia Authors
4 //
5 // Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
6 // <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
7 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
8 // This file may not be copied, modified, or distributed except according to
9 // those terms.
10 
11 use proc_macro2::TokenStream;
12 use quote::quote;
13 use syn::{
14     parse_quote, spanned::Spanned as _, Data, DataEnum, DeriveInput, Error, Expr, Fields, Ident,
15     Index, Type,
16 };
17 
18 use crate::{
19     repr::{EnumRepr, StructUnionRepr},
20     util::{
21         const_block, generate_tag_enum, Client, Ctx, DataExt, FieldBounds, FieldProjection,
22         ImplBlockBuilder, Trait,
23     },
24 };
25 
26 pub(crate) fn tag_ident(variant: &Ident) -> Ident {
27     ident!(("___ZEROCOPY_TAG_{}", variant), variant.span())
28 }
29 
30 pub(crate) fn variant_struct_ident(variant: &Ident) -> Ident {
31     ident!(("___ZerocopyVariantStruct_{}", variant), variant.span())
32 }
33 
34 pub(crate) fn variants_union_field_ident(variant: &Ident) -> Ident {
35     ident!(("__field_{}", variant), variant.span())
36 }
37 
38 /// Generates a constant for the tag associated with each variant of the enum.
39 /// When we match on the enum's tag, each arm matches one of these constants. We
40 /// have to use constants here because:
41 ///
42 /// - The type that we're matching on is not the type of the tag, it's an
43 ///   integer of the same size as the tag type and with the same bit patterns.
44 /// - We can't read the enum tag as an enum because the bytes may not represent
45 ///   a valid variant.
46 /// - Patterns do not currently support const expressions, so we have to assign
47 ///   these constants to names rather than use them inline in the `match`
48 ///   statement.
49 pub(crate) fn generate_tag_consts(data: &DataEnum) -> TokenStream {
50     let tags = data.variants.iter().map(|variant| {
51         let variant_ident = &variant.ident;
52         let tag = tag_ident(variant_ident);
53 
54         quote! {
55             // This casts the enum variant to its discriminant, and then
56             // converts the discriminant to the target integral type via a
57             // numeric cast [1].
58             //
59             // Because these are the same size, this is defined to be a no-op
60             // and therefore is a lossless conversion [2].
61             //
62             // [1] Per https://doc.rust-lang.org/1.81.0/reference/expressions/operator-expr.html#enum-cast:
63             //
64             //   Casts an enum to its discriminant.
65             //
66             // [2] Per https://doc.rust-lang.org/1.81.0/reference/expressions/operator-expr.html#numeric-cast:
67             //
68             //   Casting between two integers of the same size (e.g. i32 -> u32)
69             //   is a no-op.
70             const #tag: ___ZerocopyTagPrimitive =
71                 ___ZerocopyTag::#variant_ident as ___ZerocopyTagPrimitive;
72         }
73     });
74 
75     quote! {
76         #(#tags)*
77     }
78 }
79 
80 #[derive(Copy, Clone, Eq, PartialEq)]
81 enum Validity {
82     Uninit,
83     Initialized,
84     Safe,
85 }
86 
87 impl Validity {
88     fn as_type(self, ctx: &Ctx) -> Type {
89         let zerocopy_crate = &ctx.zerocopy_crate;
90         match self {
91             Validity::Uninit => parse_quote!(#zerocopy_crate::invariant::Uninit),
92             Validity::Initialized => {
93                 parse_quote!(#zerocopy_crate::invariant::Initialized)
94             }
95             Validity::Safe => parse_quote!(#zerocopy_crate::invariant::Safe),
96         }
97     }
98 
99     /// Computes the output validity of projecting a struct or union field, or
100     /// returns `None` if that projection must not be generated.
101     ///
102     /// Struct fields preserve all three validity invariants. Union fields
103     /// preserve `Uninit` and `Initialized`. No projection is generated from a
104     /// `Safe` union.
105     fn output_validity_for_struct_or_union(self, data: &Data) -> Option<Self> {
106         match (data, self) {
107             (Data::Struct(_), validity) => Some(validity),
108             (Data::Union(_), validity @ (Validity::Uninit | Validity::Initialized)) => {
109                 Some(validity)
110             }
111             (Data::Union(_), Validity::Safe) => None,
112             (Data::Enum(_), _) => unreachable!(),
113         }
114     }
115 }
116 
117 /// Returns the projection variant ID for the struct or union described by
118 /// `ctx`.
119 ///
120 /// This intentionally does not handle enums: an enum field's variant ID
121 /// identifies its source variant rather than the representation of its
122 /// containing type.
123 pub(crate) fn struct_union_variant_id(ctx: &Ctx) -> Box<Expr> {
124     let zerocopy_crate = &ctx.zerocopy_crate;
125     match &ctx.ast.data {
126         Data::Struct(_) => parse_quote!({ #zerocopy_crate::STRUCT_VARIANT_ID }),
127         Data::Union(_) => {
128             if StructUnionRepr::from_attrs(&ctx.ast.attrs).map(|repr| repr.is_c()).unwrap() {
129                 parse_quote!({ #zerocopy_crate::REPR_C_UNION_VARIANT_ID })
130             } else {
131                 parse_quote!({ #zerocopy_crate::UNION_VARIANT_ID })
132             }
133         }
134         Data::Enum(_) => unreachable!("struct_union_variant_id called for enum"),
135     }
136 }
137 
138 /// Generates field projection implementations for a struct or union.
139 ///
140 /// `repr(C)` unions use `REPR_C_UNION_VARIANT_ID`, so their projections
141 /// additionally implement `pointer::cast::Cast`. Other unions use
142 /// `UNION_VARIANT_ID`.
143 pub(crate) fn derive_projection_struct_union(
144     ctx: &Ctx,
145     data: &dyn DataExt,
146     client: Client,
147 ) -> TokenStream {
148     let fields = ctx.ast.data.fields();
149     if fields.is_empty() {
150         return quote! {};
151     }
152 
153     let field_tokens = fields.iter().map(|(vis, ident, _)| {
154         let ident = ident!(("__z{}", ident), ident.span());
155         quote! {
156             #vis enum #ident {}
157         }
158     });
159 
160     let zerocopy_crate = &ctx.zerocopy_crate;
161     let variant_id = struct_union_variant_id(ctx);
162 
163     let core = ctx.core_path();
164     let has_tag = ImplBlockBuilder::new(ctx, data, Trait::HasTag { client }, FieldBounds::None)
165         .inner_extras(quote! {
166             type Tag = ();
167             type ProjectToTag = #zerocopy_crate::pointer::cast::CastToUnit;
168         })
169         .build();
170 
171     let has_fields = fields.iter().map(move |(_, ident, ty)| {
172         let field_token = ident!(("__z{}", ident), ident.span());
173         let projection = FieldProjection {
174             variant_id: variant_id.clone(),
175             field: parse_quote!(#field_token),
176             field_id: parse_quote!({ #zerocopy_crate::ident_id!(#ident) }),
177         };
178         let has_field_trait = Trait::HasField { client, projection: projection.clone() };
179         let has_field_path = has_field_trait.crate_path(ctx);
180         let has_field = ImplBlockBuilder::new(ctx, data, has_field_trait, FieldBounds::None)
181             .inner_extras(quote! {
182                 type Type = #ty;
183 
184                 #[inline(always)]
185                 fn project(
186                     slf: #zerocopy_crate::pointer::PtrInner<'_, Self>,
187                 ) -> *mut <Self as #has_field_path>::Type {
188                     let slf = slf.as_ptr();
189                     // SAFETY: By invariant on `PtrInner`, `slf` is a non-null
190                     // pointer whose referent is zero-sized or lives in a valid
191                     // allocation. Since `#ident` is a struct or union field of
192                     // `Self`, this projection preserves or shrinks the referent
193                     // size, and so the resulting referent also fits in the same
194                     // allocation.
195                     unsafe { #core::ptr::addr_of_mut!((*slf).#ident) }
196                 }
197             })
198             .build();
199 
200         let derive_project_field = |input_validity: Validity| {
201             let output_validity =
202                 match input_validity.output_validity_for_struct_or_union(&ctx.ast.data) {
203                     Some(output_validity) => output_validity.as_type(ctx),
204                     None => return TokenStream::new(),
205                 };
206             let input_validity = input_validity.as_type(ctx);
207             let projection_preserves_alignment = StructUnionRepr::from_attrs(&ctx.ast.attrs)
208                 .map(|repr| repr.get_packed().is_none())
209                 .unwrap();
210             let output_alignment = if projection_preserves_alignment {
211                 quote! { ___ZcAlignment }
212             } else {
213                 quote! { #zerocopy_crate::invariant::Unaligned }
214             };
215             ImplBlockBuilder::new(
216                 ctx,
217                 data,
218                 Trait::ProjectField {
219                     client,
220                     projection: projection.clone(),
221                     invariants: parse_quote!((___ZcAliasing, ___ZcAlignment, #input_validity)),
222                 },
223                 FieldBounds::None,
224             )
225             .param_extras(vec![
226                 parse_quote!(___ZcAliasing: #zerocopy_crate::invariant::Aliasing),
227                 parse_quote!(___ZcAlignment: #zerocopy_crate::invariant::Alignment),
228             ])
229             .inner_extras(quote! {
230                 // SAFETY: Struct and union projections do not depend on the value of
231                 // the referent, and are therefore infallible.
232                 type Error = #zerocopy_crate::util::macro_util::core_reexport::convert::Infallible;
233 
234                 // SAFETY: Projection preserves aliasing. It also preserves
235                 // alignment unless the containing type is packed. `Validity`
236                 // determines whether a projection is emitted and, if so,
237                 // computes its output validity: struct fields preserve validity;
238                 // union fields preserve `Uninit` and `Initialized`, and no
239                 // projection is emitted for `Safe` union input.
240                 type Invariants = (___ZcAliasing, #output_alignment, #output_validity);
241             })
242             .build()
243         };
244 
245         let project_uninit = derive_project_field(Validity::Uninit);
246         let project_initialized = derive_project_field(Validity::Initialized);
247         let project_safe = derive_project_field(Validity::Safe);
248 
249         quote! {
250             #has_field
251             #project_uninit
252             #project_initialized
253             #project_safe
254         }
255     });
256 
257     const_block(field_tokens.into_iter().chain(Some(has_tag)).chain(has_fields).map(Some))
258 }
259 
260 pub(crate) fn derive_enum(
261     ctx: &Ctx,
262     data: &DataEnum,
263     client: Client,
264 ) -> Result<TokenStream, Error> {
265     // With no fields, there are no `HasField` or `ProjectField` impls to emit,
266     // and therefore no representation requirement to enforce.
267     if data.fields().is_empty() {
268         return Ok(TokenStream::new());
269     }
270 
271     let repr = EnumRepr::from_attrs(&ctx.ast.attrs)?;
272     let (outer_tag_type, inner_tag_type) = if repr.is_c() {
273         (quote! { ___ZerocopyTag }, quote! { () })
274     } else if repr.is_primitive() {
275         (quote! { () }, quote! { ___ZerocopyTag })
276     } else {
277         return Err(Error::new(
278             ctx.ast.span(),
279             "must have #[repr(C)] or #[repr(Int)] attribute in order to guarantee this type's memory layout",
280         ));
281     };
282 
283     let zerocopy_crate = &ctx.zerocopy_crate;
284     let core = &ctx.core_path();
285     let client_path = &client.crate_path(ctx);
286     let has_tag_trait = Trait::HasTag { client };
287     let has_tag_path = &has_tag_trait.crate_path(ctx);
288     let infallible =
289         quote! { #zerocopy_crate::util::macro_util::core_reexport::convert::Infallible };
290     let tag_enum = generate_tag_enum(ctx, &repr, data);
291     let tag_consts = generate_tag_consts(data);
292 
293     let generics = &ctx.ast.generics;
294     let (impl_generics, ref ty_generics, where_clause) = generics.split_for_impl();
295 
296     // Synthesize a `repr(C)` struct for each fieldful variant. We must do this
297     // because Rust does not provide an `addr_of!` that works on enums.
298     let variant_structs = data.variants.iter().filter_map(move |variant| {
299         if matches!(variant.fields, Fields::Unit) {
300             return None;
301         }
302 
303         let ident = variant_struct_ident(&variant.ident);
304         let field_types = variant.fields.iter().map(|field| &field.ty);
305         let enum_name = &ctx.ast.ident;
306         let variant_struct: DeriveInput = parse_quote! {
307             #[repr(C)]
308             struct #ident #impl_generics (
309                 #core::mem::MaybeUninit<___ZerocopyInnerTag>,
310                 #(#field_types,)*
311                 #core::marker::PhantomData<#enum_name #ty_generics>,
312             ) #where_clause;
313         };
314 
315         let projections = derive_projection_struct_union(
316             &ctx.with_input(&variant_struct),
317             &variant_struct.data,
318             client,
319         );
320 
321         Some(quote! {
322             #variant_struct
323             #projections
324         })
325     });
326 
327     // Synthesize a `repr(C)` union encompassing all synthesized variants.
328     let variants_union = {
329         let fields = data.variants.iter().filter_map(|variant| {
330             if matches!(variant.fields, Fields::Unit) {
331                 return None;
332             }
333             let field_name = variants_union_field_ident(&variant.ident);
334             let variant_struct = variant_struct_ident(&variant.ident);
335             Some(quote! {
336                 #field_name: #core::mem::ManuallyDrop<#variant_struct #ty_generics>,
337             })
338         });
339 
340         let variants_union: DeriveInput = parse_quote! {
341             #[repr(C)]
342             union ___ZerocopyVariants #generics {
343                 #(#fields)*
344                 // A fieldless enum produces no variant structs, but a union must
345                 // have at least one field. This unit does not affect `repr(C)`
346                 // layout.
347                 __nonempty: (),
348             }
349         };
350         let projections = derive_projection_struct_union(
351             &ctx.with_input(&variants_union),
352             &variants_union.data,
353             client,
354         );
355 
356         quote! {
357             #variants_union
358             #projections
359         }
360     };
361 
362     // Synthesize a `repr(C)` struct that pairs the the tag with the synthesized
363     // variants union. In practice, the actual tag storage may be here, or
364     // inside the synthesized variant structs, depending on the `repr` of the
365     // enum.
366     let raw_enum: DeriveInput = parse_quote! {
367         #[repr(C)]
368         struct ___ZerocopyRawEnum #generics {
369             tag: ___ZerocopyOuterTag,
370             variants: ___ZerocopyVariants #ty_generics,
371         }
372     };
373 
374     let raw_projections =
375         derive_projection_struct_union(&ctx.with_input(&raw_enum), &raw_enum.data, client);
376 
377     let has_tag = ImplBlockBuilder::new(ctx, data, has_tag_trait, FieldBounds::None)
378         .inner_extras(quote! {
379             type Tag = ___ZerocopyTag;
380             type ProjectToTag = #zerocopy_crate::pointer::cast::CastSized;
381         })
382         .build();
383 
384     let aliasing_param: &syn::GenericParam =
385         &parse_quote!(___ZcAliasing: #zerocopy_crate::invariant::Aliasing);
386     let reference_param: &syn::GenericParam =
387         &parse_quote!(___ZcAliasing: #zerocopy_crate::invariant::Reference);
388     let alignment_param: &syn::GenericParam =
389         &parse_quote!(___ZcAlignment: #zerocopy_crate::invariant::Alignment);
390 
391     let has_fields = data.variants().into_iter().flat_map(|(variant, fields)| {
392         let variant_ident = &variant.unwrap().ident;
393         let variants_union_field = variants_union_field_ident(variant_ident);
394         let infallible = &infallible;
395 
396         fields.into_iter().enumerate().map(move |(idx, (vis, ident, ty))| {
397             // Rust does not presently support explicit visibility modifiers on
398             // enum fields. Keep this assertion so that a future language
399             // change cannot silently invalidate the visibility invariant.
400             assert!(matches!(vis, syn::Visibility::Inherited));
401             let projection = FieldProjection {
402                 variant_id: parse_quote!({ #zerocopy_crate::ident_id!(#variant_ident) }),
403                 field: parse_quote!(()),
404                 field_id: parse_quote!({ #zerocopy_crate::ident_id!(#ident) }),
405             };
406             // The generated variant struct's first field is its inner tag.
407             let variant_struct_field_index = Index::from(idx + 1);
408             let has_field_trait = Trait::HasField {
409                 client,
410                 projection: projection.clone(),
411             };
412             let has_field_path = has_field_trait.crate_path(ctx);
413             let has_field = ImplBlockBuilder::new(ctx, data, has_field_trait, FieldBounds::None)
414                 .inner_extras(quote! {
415                     type Type = #ty;
416 
417                     #[inline(always)]
418                     fn project(
419                         slf: #zerocopy_crate::pointer::PtrInner<'_, Self>,
420                     ) -> *mut <Self as #has_field_path>::Type {
421                         use #zerocopy_crate::pointer::cast::{CastSized, Projection};
422 
423                         slf.project::<___ZerocopyRawEnum #ty_generics, CastSized>()
424                             .project::<_, Projection<#client_path, _, { #zerocopy_crate::STRUCT_VARIANT_ID }, { #zerocopy_crate::ident_id!(variants) }>>()
425                             .project::<_, Projection<#client_path, _, { #zerocopy_crate::REPR_C_UNION_VARIANT_ID }, { #zerocopy_crate::ident_id!(#variants_union_field) }>>()
426                             .project::<_, Projection<#client_path, _, { #zerocopy_crate::STRUCT_VARIANT_ID }, { #zerocopy_crate::ident_id!(value) }>>()
427                             .project::<_, Projection<#client_path, _, { #zerocopy_crate::STRUCT_VARIANT_ID }, { #zerocopy_crate::ident_id!(#variant_struct_field_index) }>>()
428                             .as_ptr()
429                     }
430                 })
431                 .build();
432 
433             // SAFETY: `projection` is constructed from the current field and
434             // `variant_ident`, and that same `variant_ident` selects the
435             // variants union field through which `has_field` projects. Thus the
436             // `HasField` impl, `ProjectField` impls, and valid projection's tag
437             // check all identify the same enum field. `idx` is the current
438             // field's zero-based position, and the generated variant struct
439             // prepends its inner tag before reproducing the enum fields in
440             // source order, so `idx + 1` selects that same field. The assertion
441             // above enforces that `repr` is `repr(C)` or a primitive
442             // representation; `___ZerocopyRawEnum` and its nested types model
443             // exactly the representations specified by [1] and [2]. Those
444             // representations use `repr(C)` structs for variant fields, so field
445             // projection preserves alignment. Each `ProjectField` impl preserves
446             // the input validity. The `Uninit` and `Initialized` projections are
447             // infallible because those validity invariants do not depend on the
448             // enum's tag. The `Safe` projection first checks that the tag
449             // selects `variant_ident`; its `Reference` aliasing bound prevents
450             // mutation of the tag between that check and field projection. The
451             // corresponding `HasTag` impl projects to the raw representation's
452             // tag using `CastSized`.
453             //
454             // [1] Per https://doc.rust-lang.org/1.56.0/reference/type-layout.html#reprc-enums-with-fields:
455             //
456             //   The representation of a `repr(C)` enum with fields is a
457             //   `repr(C)` struct with two fields [...]: a `repr(C)` version of
458             //   the enum with all fields removed ("the tag") [and] a `repr(C)`
459             //   union of `repr(C)` structs for the fields of each variant [...].
460             //
461             // [2] Per https://doc.rust-lang.org/1.56.0/reference/type-layout.html#primitive-representation-of-enums-with-fields:
462             //
463             //   The representation of a primitive representation enum is a
464             //   `repr(C)` union of `repr(C)` structs for each variant with a
465             //   field. The first field of each struct in the union is [...] the
466             //   tag and the remaining fields are the fields of that variant.
467             let derive_enum_project_field = |validity| {
468                 let (error, is_projectable, aliasing_bound) = if validity == Validity::Safe {
469                     assert!(!matches!(validity, Validity::Uninit | Validity::Initialized));
470                     (
471                         quote! { () },
472                         quote! {
473                             #[inline(always)]
474                             fn is_projectable(
475                                 tag: #zerocopy_crate::pointer::Ptr<
476                                     '_,
477                                     <Self as #has_tag_path>::Tag,
478                                     (
479                                         #zerocopy_crate::invariant::Shared,
480                                         ___ZcAlignment,
481                                         #zerocopy_crate::invariant::Safe,
482                                     ),
483                                 >,
484                             ) -> #core::result::Result<(), ()> {
485                                 let tag = tag.read::<#zerocopy_crate::BecauseImmutable>();
486                                 if tag == ___ZerocopyTag::#variant_ident {
487                                     #core::result::Result::Ok(())
488                                 } else {
489                                     #core::result::Result::Err(())
490                                 }
491                             }
492                         },
493                         reference_param.clone(),
494                     )
495                 } else {
496                     (infallible.clone(), quote! {}, aliasing_param.clone())
497                 };
498 
499                 let validity = validity.as_type(ctx);
500                 let invariants: Box<Type> =
501                     parse_quote!((___ZcAliasing, ___ZcAlignment, #validity));
502                 let project_field_trait = Trait::ProjectField {
503                     client,
504                     projection: projection.clone(),
505                     invariants: invariants.clone(),
506                 };
507 
508                 ImplBlockBuilder::new(ctx, data, project_field_trait, FieldBounds::None)
509                     .param_extras(vec![aliasing_bound.clone(), alignment_param.clone()])
510                     .inner_extras(quote! {
511                         type Error = #error;
512                         type Invariants = #invariants;
513                         #is_projectable
514                     })
515                     .build()
516             };
517 
518             let project_uninit = derive_enum_project_field(Validity::Uninit);
519             let project_initialized = derive_enum_project_field(Validity::Initialized);
520             let project_valid = derive_enum_project_field(Validity::Safe);
521 
522             quote! {
523                 #has_field
524                 #project_uninit
525                 #project_initialized
526                 #project_valid
527             }
528         })
529     });
530 
531     Ok(quote! {
532         #tag_enum
533 
534         type ___ZerocopyTagPrimitive = #zerocopy_crate::util::macro_util::SizeToTag<
535             { #core::mem::size_of::<___ZerocopyTag>() },
536         >;
537 
538         #tag_consts
539 
540         type ___ZerocopyOuterTag = #outer_tag_type;
541         type ___ZerocopyInnerTag = #inner_tag_type;
542 
543         #(#variant_structs)*
544         #variants_union
545 
546         #raw_enum
547         #raw_projections
548 
549         #has_tag
550         #(#has_fields)*
551     })
552 }
553 
554 pub(crate) fn derive(ctx: &Ctx, _top_level: Trait) -> Result<TokenStream, Error> {
555     match &ctx.ast.data {
556         Data::Struct(strct) => {
557             Ok(derive_projection_struct_union(ctx, strct, Client::ProjectDerive))
558         }
559         Data::Union(unn) => Ok(derive_projection_struct_union(ctx, unn, Client::ProjectDerive)),
560         Data::Enum(enm) => {
561             let projections = derive_enum(ctx, enm, Client::ProjectDerive)?;
562             if projections.is_empty() {
563                 Ok(projections)
564             } else {
565                 Ok(const_block([Some(projections)]))
566             }
567         }
568     }
569 }
570