C2Rust-Bitfields Crate

C2Rust-Bitfields enables you to write structs containing bitfields. It has three primary goals:

  • Byte compatibility with equivalent C bitfield structs
  • The ability to take references/pointers to non bitfield fields
  • Provide methods to read from and write to bitfields

We currently provides a single custom derive, BitfieldStruct, as well as a dependent field attribute bitfield.

Requirements

  • Rust 1.30+
  • Rust Stable, Beta, or Nightly
  • Little Endian Architecture

Example

Suppose you want to write a super compact date struct which only takes up three bytes. In C this would look like this:

1. struct date {
2. unsigned char day: 5;
3. unsigned char month: 4;
4. unsigned short year: 15;
5. } __attribute__((packed));

Clang helpfully provides us with this information:

1. *** Dumping AST Record Layout
2. 0 | struct date
3. 0:0-4 |   unsigned char day
4. 0:5-8 |   unsigned char month
5. 1:1-15 |   unsigned short year
6. | [sizeof=3, align=1]

And this is enough to build our rust struct:

1. extern crate libc;

3. #[repr(C, align(1))]
4. #[derive(BitfieldStruct)]
5. struct Date {
6. #[bitfield(name = "day", ty = "libc::c_uchar", bits = "0..=4")]
7. #[bitfield(name = "month", ty = "libc::c_uchar", bits = "5..=8")]
8. #[bitfield(name = "year", ty = "libc::c_ushort", bits = "9..=23")]
9. day_month_year: [u8; 3]
10. }

12. fn main() {
13. let mut date = Date {
14. day_month_year: [0; 3]
15. };

17. date.set_day(18);
18. date.set_month(7);
19. date.set_year(2000);

21. assert_eq!(date.day(), 18);
22. assert_eq!(date.month(), 7);
23. assert_eq!(date.year(), 2000);
24. }

Furthermore, C bitfield rules for overflow and signed integers are taken into account.

This crate can generate no_std compatible code when the no_std feature flagis provided.

Tests

Since rust doesn't support a build.rs exclusively for tests, you must manually compile the c test code and link it in.

1. $ clang tests/bitfields.c -c -fPIC -o tests/bitfields.o
2. $ ar -rc tests/libtest.a tests/bitfields.o
3. $ RUSTFLAGS="-L `pwd`/tests" cargo test

Acknowledgements

This crate is inspired by the rust-bitfield, packed_struct, and bindgen crates.