support bit fields for C interop

[rust-highfive]

Bitfields are commonly encountered when interacting with C code. Since many of the details of the behavior of bitfields are left to the implementation, it is hard to write cross-platform rust code that uses bitfields correctly. (Source: #1449)

Prior RFCs and other citations:

• Add language support for bitfields #1449
  • This RFC was judged to be very-close to what we would want, but with certain specific details that needed to be included; a follow-up that takes a similar approach but addresses those questions would be welcome.
• support bit fields for C interop rust#8680

[mzabaluev]

Wondering if there could be a Rust feature of ranges for integer types, generally useful to automatically check value domain at runtime and possible optimization hints:

let ascii: u8 match 0x00 ... 0x7F = 'a' as u8;

Then it could be reused to represent bitfields:

#[repr(C)]
struct PackedToBits {
    some_bits: u8 match 0 ... 3  // equivalent to `uint8_t some_bits: 2` in C
}

[bgamari]

@mzabaluev in my opinion ranged integers is an orthogonal issue to bit fields which would be best treated with a combination of type-level naturals and either a macro or CTFE and custom literals,

/// An integer of a given parametrized width (less than 64 bits, of course)
struct NarrowInt<Width: int>(u64)

/// This trait would be used by the compiler to support custom literals. A macro could also be used here although this trait might provide better ergonomics.
trait FromNumber {
    /// `static` here denotes a CTFE-able function. The `Option` allows the compiler to throw an error on out-of-bound literals
    pub fn static from_number(val: i64) -> Option<Self>;
}

impl<Width> FromNumber for RangedInt<Width> {
    pub fn static from_number(val: i64) -> Option<Self> { ... }
}

[mzabaluev]

@bgamari I think ranged types could provide a superset over bit width limited types. The range might as well be parameterized, if Rust allows expression parameters for types as your example suggests.
With syntactic support, it could be possible to define more complex restrictions (using Unicode as a contrived example):

type unichar = u32 match 0 ... 0xD7FF | 0xE000 ... 0x10FFFF;

[mzabaluev]

Pulling from a forum post, the ideation to add a sub-specifier to #[repr(C)]:

#[repr(C; bitfields(foo: 2, bar: 1))]
struct A {
    foo: c_uint,
    bar: c_uint
}

As FFI should be the only application for bit fields in Rust, setting them could be considered unsafe, to punt on the implications of exceeding the range besides trimming the value to the bit width.

[vitiral]

For general rust use, I don't understand why you couldn't just have the syntax

#[repr(pack_bool)]  // only pack the bool values
struct A {
    flag1: bool,
    flag2: bool,
    flag3: bool,
    value1: u16,
    flag4: bool,    // allowed to be out of order
    flag5: bool,
    value2: u32,
}

And the compiler would just know what to do -- packing bool (bit) values together into whatever made the most sense for the target archetecture and reading them correctly. This would be most useful for embedded platforms, but might find use outside of them as well.

For FFI layer stuff, there should be some attribute to tell the compiler the order you want things packed in, for instance:

#[repr(ordered, packed)]
struct A {
    flag1: bool,
    flag2: bool,
    flag3: bool,
    flag4: bool,    // not allowed to be out of order
    flag5: bool,
    value1: u16,
    value2: u32,
}

For repr(ordered, packed) structs, the data layout would be well defined according to a spec.

[vitiral]

I also don't understand why setting or reading bits in bit fields should be considered unsafe. If it follows the same structure as the rest of rust code (i.e. resides in a struct) I don't see why setting individual bits should be any more unsafe than setting bytes.

[burdges]

Appears corrode has grown interested in this : jameysharp/corrode#75

[retep998]

This is how I handle bitfields in winapi. Note that this likely won't work with non-windows platforms because only Windows has simple sane rules for bitfields.

macro_rules! BITFIELD {
    ($base:ident $field:ident: $fieldtype:ty [
        $($thing:ident $set_thing:ident[$r:expr],)+
    ]) => {
        impl $base {$(
            #[inline]
            pub fn $thing(&self) -> $fieldtype {
                let size = $crate::core::mem::size_of::<$fieldtype>() * 8;
                self.$field << (size - $r.end) >> (size - $r.end + $r.start)
            }
            #[inline]
            pub fn $set_thing(&mut self, val: $fieldtype) {
                let mask = ((1 << ($r.end - $r.start)) - 1) << $r.start;
                self.$field &= !mask;
                self.$field |= (val << $r.start) & mask;
            }
        )+}
    }
}

STRUCT!{struct WOW64_LDT_ENTRY_Bits {
    BitFields: DWORD,
}}
BITFIELD!(WOW64_LDT_ENTRY_Bits BitFields: DWORD [
    BaseMid set_BaseMid[0..8],
    Type set_Type[8..13],
    Dpl set_Dpl[13..15],
    Pres set_Pres[15..16],
    LimitHi set_LimitHi[16..20],
    Sys set_Sys[20..21],
    Reserved_0 set_Reserved_0[21..22],
    Default_Big set_Default_Big[22..23],
    Granularity set_Granularity[23..24],
    BaseHi set_BaseHi[24..32],
]);

[nagisa]

A draft I had written almost a year ago would allow doing bitfields.