Do you need IntoBytes support on unions? Let us know!

[joshlf]

Tracking issue: #1792

TL;DR: If you want to use IntoBytes with union types, upvote this discussion!

In 0.8, we've restricted #[derive (IntoBytes)] so that it only supports unions when —-cfg zerocopy_derive_union_into_bytes is
passed. Union bit validity is up in the air, and it's not currently guaranteed that implementing IntoBytes on unions will remain
sound on all future Rust versions.

The exact bit validity of unions is actively being discussed, and we're advocating for bit validity requirements that will permit IntoBytes on unions to be sound.

If you would like to use IntoBytes with unions, please let us know by upvoting this discussion or by commenting. We will use
this as evidence that there is demand for this feature, and try to persuade Rust to adopt the necessary union bit validity
requirements. Please do not spam other threads besides this one, especially threads in rust-lang repositories. Let's be friendly
participants in this discussion 🙂

[anp]

It looks like Fuchsia currently uses IntoBytes on some #[repr(C)] unions. We generate the wrappers with bindgen and the referenced types include unions.

EDIT: My initial search was too narrow, we also do this when we generate bindings to the Linux uapi.

[joshlf]

Fuchsia is the reason for the --cfg escape hatch 🙂

But yes, good to have this use case recorded. Thanks!

[phy1729]

The ppv-lite86 crate uses AsBytes/IntoByes on a union at https://github.com/cryptocorrosion/cryptocorrosion/blob/16e2fe894fc39944c2625d735fff3d697d052e42/utils-simd/ppv-lite86/src/x86_64/mod.rs#L110-L112.

[a1akris]

The ppv-lite86 crate uses AsBytes/IntoByes on a union at https://github.com/cryptocorrosion/cryptocorrosion/blob/16e2fe894fc39944c2625d735fff3d697d052e42/utils-simd/ppv-lite86/src/x86_64/mod.rs#L110-L112.

I have a similar usage to this one in a private project for versioned binary blobs. The classic approach

#[derive(TryFromBytes, Immutable, IntoBytes)]
#[repr(C)]
pub enum Blob {
    V1(BlobV1),
    V2(BlobV2),
}

doesn't work because enums cannot be packed so I have to rewrite them as

#[derive(TryFromBytes, Immutable, IntoBytes)]
#[repr(C, packed)]
pub struct Blob {
    version: BlobVersion,
    blob: BlobUnion
}

#[derive(TryFromBytes, IntoBytes, Immutable)]
#[repr(u8)]
pub enum BlobVersion {
    V1,
    V2,
}

#[derive(TryFromBytes, IntoBytes, Immutable)]
union BlobUnion {
    v1: BlobV1,
    v2: BlobV2,
}

with some extra code for conversions.

Also, --cfg doesn't work for me on 0.8.9 for some reason so currently I put all this boilerplate in a macro where I implement

unsafe impl IntoBytes for BlobUnion

myself and there every field type is checked by fn is_into_bytes<T: Immutable + IntoBytes>().

[pmj]

I'm using this in a device driver; the vendor supplies C header files with nested struct/union definitions for the various messages the device understands.

It looks something like this:

struct DeviceMessage
{
    uint32_t signature; // Can be DEVICE_MESSAGE_DISPLAY, DEVICE_MESSAGE_AUDIO, etc.
    // […more shared fields…]

    union
    {
        struct
        {
            uint8_t parameter;
            uint8_t reserved[7];
        } display;
        struct
        {
            uint8_t flags;
            uint8_t index;
            uint8_t reserved[6];
        } audio;
        // […]
    } message_specific;
};

The ability to just import these definitions into the rust code with bindgen and emit the byte stream with IntoBytes saves me from error-prone manual translation.

In my particular case, there is no padding. Every byte is accounted for in every branch, because we don't want to send a buffer containing uninitialised bytes to the device. So I could happily live with this only working with the subset of well-defined unions.

For what it's worth, I'd also be entirely fine with implementing IntoBytes myself for types containing unions, if it was documented how I should go about this. However, the stern warning of

Do not implement this trait yourself! Instead, use `#[derive(IntoBytes)]

has led me to not pursue this approach for now. (Although I suspect I will have to do something about this soon because the --cfg flag approach is incredibly annoying; cargo doesn't seem to be able to reliably set it from Cargo.toml files, so it always needs to be passed in via environment variables.)