Derive Macro FromBytes

#[derive(FromBytes)]

Analyzes whether a type is FromBytes.

This derive analyzes, at compile time, whether the annotated type satisfies the safety conditions of FromBytes and implements FromBytes if it is sound to do so. This derive can be applied to structs, enums, and unions; e.g.:

#[derive(FromZeroes, FromBytes)]
struct MyStruct {
    ...
}

#[derive(FromZeroes, FromBytes)]
#[repr(u8)]
enum MyEnum {
    ...
}

#[derive(FromZeroes, FromBytes)]
union MyUnion {
    ...
}

Analysis

This section describes, roughly, the analysis performed by this derive to determine whether it is sound to implement FromBytes for a given type. Unless you are modifying the implementation of this derive, or attempting to manually implement FromBytes for a type yourself, you don’t need to read this section.

If a type has the following properties, then this derive can implement FromBytes for that type:

• If the type is a struct, all of its fields must be FromBytes.
• If the type is an enum:
  • It must be a C-like enum (meaning that all variants have no fields).
  • It must have a defined representation (reprs C, u8, u16, u32, u64, usize, i8, i16, i32, i64, or isize).
  • The maximum number of discriminants must be used (so that every possible bit pattern is a valid one). Be very careful when using the C, usize, or isize representations, as their size is platform-dependent.
• The type must not contain any UnsafeCells (this is required in order for it to be sound to construct a &[u8] and a &T to the same region of memory). The type may contain references or pointers to UnsafeCells so long as those values can themselves be initialized from zeroes (FromBytes is not currently implemented for, e.g., Option<*const UnsafeCell<_>>, but it could be one day).

This analysis is subject to change. Unsafe code may only rely on the documented safety conditions of FromBytes, and must not rely on the implementation details of this derive.

Why isn’t an explicit representation required for structs?

Neither this derive, nor the safety conditions of FromBytes, requires that structs are marked with #[repr(C)].

Per the Rust reference,

The representation of a type can change the padding between fields, but does not change the layout of the fields themselves.

Since the layout of structs only consists of padding bytes and field bytes, a struct is soundly FromBytes if:

1. its padding is soundly FromBytes, and
2. its fields are soundly FromBytes.

The answer to the first question is always yes: padding bytes do not have any validity constraints. A discussion of this question in the Unsafe Code Guidelines Working Group concluded that it would be virtually unimaginable for future versions of rustc to add validity constraints to padding bytes.

Whether a struct is soundly FromBytes therefore solely depends on whether its fields are FromBytes.