Finish bitfield test suite

Author: dtolnay

bitfield/tests/01-specifier-types.rs

@@ -40,7 +40,10 @@
 //
 // Create a trait called bitfield::Specifier with an associated constant BITS,
 // and write a function-like procedural macro to define some types B1 through
-// B64 with corresponding impls of the Specifier trait.
+// B64 with corresponding impls of the Specifier trait. The B* types can be
+// anything since we don't need them to carry any meaning outside of a
+// #[bitfield] struct definition; an uninhabited enum like `pub enum B1 {}`
+// would work best.
 //
 // Be aware that crates that have the "proc-macro" crate type are not allowed to
 // export anything other than procedural macros. The project skeleton for this

bitfield/tests/03-INCOMPLETE

@@ -0,0 +1,37 @@
+// Generate getters and setters that manipulate the right range of bits
+// corresponding to each field. Refer to the bitfield project introduction in
+// the readme for a diagram of how the bit-level mapping is expected to work;
+// the diagram uses the same field sizes as the struct in the test case below.
+//
+// Depending on your implementation, it's possible that this will require adding
+// some associated types, associated constants, or associated functions to your
+// bitfield::Specifier trait next to the existing Specifier::BITS constant, but
+// it may not.
+//
+// If it's easier for now, you can use u64 as the argument type for all the
+// setters and return type for all the getters. We will follow up with a more
+// precise signature in a later test case.
+
+use bitfield::*;
+
+#[bitfield]
+pub struct MyFourBytes {
+    a: B1,
+    b: B3,
+    c: B4,
+    d: B24,
+}
+
+fn main() {
+    let mut bitfield = MyFourBytes::new();
+    assert_eq!(0, bitfield.get_a());
+    assert_eq!(0, bitfield.get_b());
+    assert_eq!(0, bitfield.get_c());
+    assert_eq!(0, bitfield.get_d());
+
+    bitfield.set_c(14);
+    assert_eq!(0, bitfield.get_a());
+    assert_eq!(0, bitfield.get_b());
+    assert_eq!(14, bitfield.get_c());
+    assert_eq!(0, bitfield.get_d());
+}

bitfield/tests/03-accessors.rs

@@ -0,0 +1,61 @@
+// Make it so that a bitfield with a size not a multiple of 8 bits will not
+// compile.
+//
+// Aim to make the error message as relevant and free of distractions as you can
+// get. The stderr file next to this test case should give some idea as to the
+// approach taken by the reference implementation for this project, but feel
+// free to overwrite the stderr file to match the implementation you come up
+// with.
+//
+// ---
+// Tangent
+//
+// There is only one profound insight about Rust macro development, and this
+// test case begins to touch on it: what makes someone an "expert at macros"
+// mostly has nothing to do with how good they are "at macros".
+//
+// 95% of what enables people to write powerful and user-friendly macro
+// libraries is in their mastery of everything else about Rust outside of
+// macros, and their creativity to put together ordinary language features in
+// interesting ways that may not occur in handwritten code.
+//
+// You may occasionally come across procedural macros that you feel are really
+// advanced or magical. If you ever feel this way, I encourage you to take a
+// closer look and you'll discover that as far as the macro implementation
+// itself is concerned, none of those libraries are doing anything remotely
+// interesting. They always just parse some input in a boring way, crawl some
+// syntax trees in a boring way to find out about the input, and paste together
+// some output code in a boring way exactly like what you've been doing so far.
+// In fact once you've made it this far in the workshop, it's okay to assume you
+// basically know everything there is to know about the mechanics of writing
+// procedural macros.
+//
+// To the extent that there are any tricks to macro development, all of them
+// revolve around *what* code the macros emit, not *how* the macros emit the
+// code. This realization can be surprising to people who entered into macro
+// development with a vague notion of procedural macros as a "compiler plugin"
+// which they imagine must imply all sorts of complicated APIs for *how* to
+// integrate with the rest of the compiler. That's not how it works. The only
+// thing macros do is emit code that could have been written by hand. If you
+// couldn't have come up with some piece of tricky code from one of those
+// magical macros, learning more "about macros" won't change that; but learning
+// more about every other part of Rust will. Inversely, once you come up with
+// what code you want to generate, writing the macro to generate it is generally
+// the easy part.
+
+use bitfield::*;
+
+type A = B1;
+type B = B3;
+type C = B4;
+type D = B23;
+
+#[bitfield]
+pub struct NotQuiteFourBytes {
+    a: A,
+    b: B,
+    c: C,
+    d: D,
+}
+
+fn main() {}

bitfield/tests/04-multiple-of-8bits.rs

@@ -0,0 +1,7 @@
+error[E0277]: the trait bound `bitfield::checks::SevenMod8: bitfield::checks::TotalSizeIsMultipleOfEightBits` is not satisfied
+  --> $DIR/04-multiple-of-8bits.rs:53:1
+   |
+53 | #[bitfield]
+   | ^^^^^^^^^^^ the trait `bitfield::checks::TotalSizeIsMultipleOfEightBits` is not implemented for `bitfield::checks::SevenMod8`
+
+For more information about this error, try `rustc --explain E0277`.

bitfield/tests/04-multiple-of-8bits.stderr

@@ -0,0 +1,47 @@
+// For getters and setters, we would like for the signature to be in terms of
+// the narrowest unsigned integer type that can hold the right number of bits.
+// That means the accessors for B1 through B8 would use u8, B9 through B16 would
+// use u16 etc.
+
+use bitfield::*;
+use std::mem::size_of_val;
+
+type A = B1;
+type B = B3;
+type C = B4;
+type D = B24;
+
+#[bitfield]
+pub struct MyFourBytes {
+    a: A,
+    b: B,
+    c: C,
+    d: D,
+}
+
+fn main() {
+    let mut x = MyFourBytes::new();
+
+    // I am testing the signatures in this roundabout way to avoid making it
+    // possible to pass this test with a generic signature that is inconvenient
+    // for callers, such as `fn get_a<T: From<u64>>(&self) -> T`.
+
+    let a = 1;
+    x.set_a(a); // expect fn(&mut MyFourBytes, u8)
+    let b = 1;
+    x.set_b(b);
+    let c = 1;
+    x.set_c(c);
+    let d = 1;
+    x.set_d(d); // expect fn(&mut MyFourBytes, u32)
+
+    assert_eq!(size_of_val(&a), 1);
+    assert_eq!(size_of_val(&b), 1);
+    assert_eq!(size_of_val(&c), 1);
+    assert_eq!(size_of_val(&d), 4);
+
+    assert_eq!(size_of_val(&x.get_a()), 1); // expect fn(&MyFourBytes) -> u8
+    assert_eq!(size_of_val(&x.get_b()), 1);
+    assert_eq!(size_of_val(&x.get_c()), 1);
+    assert_eq!(size_of_val(&x.get_d()), 4); // expect fn(&MyFourBytes) -> u32
+}

bitfield/tests/05-accessor-signatures.rs

@@ -0,0 +1,91 @@
+// For some bitfield members, working with them as enums will make more sense to
+// the user than working with them as integers. We will require enums that have
+// a power-of-two number of variants so that they exhaustively cover a fixed
+// range of bits.
+//
+//     // Works like B3, but getter and setter signatures will use
+//     // the enum instead of u8.
+//     #[derive(BitfieldSpecifier)]
+//     enum DeliveryMode {
+//         Fixed = 0b000,
+//         Lowest = 0b001,
+//         SMI = 0b010,
+//         RemoteRead = 0b011,
+//         NMI = 0b100,
+//         Init = 0b101,
+//         Startup = 0b110,
+//         External = 0b111,
+//     }
+//
+// For this test case it is okay to require that every enum variant has an
+// explicit discriminant that is an integer literal. We will relax this
+// requirement in a later test case.
+//
+// Optionally if you are interested, come up with a way to support enums with a
+// number of variants that is not a power of two, but this is not necessary for
+// the test suite. Maybe there could be a #[bits = N] attribute that determines
+// the bit width of the specifier, and the getter (only for such enums) would
+// return Result<T, Unrecognized> with the raw value accessible through the
+// error type as u64:
+//
+//     #[derive(BitfieldSpecifier)]
+//     #[bits = 4]
+//     enum SmallPrime {
+//         Two = 0b0010,
+//         Three = 0b0011,
+//         Five = 0b0101,
+//         Seven = 0b0111,
+//         Eleven = 0b1011,
+//         Thirteen = 0b1101,
+//     }
+//
+//     ...
+//     let mut bitfield = MyBitfield::new();
+//     assert_eq!(0, bitfield.small_prime().unwrap_err().raw_value());
+//
+//     bitfield.set_small_prime(SmallPrime::Seven);
+//     let p = bitfield.small_prime().unwrap_or(SmallPrime::Two);
+
+use bitfield::*;
+
+#[bitfield]
+pub struct RedirectionTableEntry {
+    acknowledged: bool,
+    trigger_mode: TriggerMode,
+    delivery_mode: DeliveryMode,
+    reserved: B3,
+}
+
+#[derive(BitfieldSpecifier, Debug, PartialEq)]
+pub enum TriggerMode {
+    Edge = 0,
+    Level = 1,
+}
+
+#[derive(BitfieldSpecifier, Debug, PartialEq)]
+pub enum DeliveryMode {
+    Fixed = 0b000,
+    Lowest = 0b001,
+    SMI = 0b010,
+    RemoteRead = 0b011,
+    NMI = 0b100,
+    Init = 0b101,
+    Startup = 0b110,
+    External = 0b111,
+}
+
+fn main() {
+    assert_eq!(std::mem::size_of::<RedirectionTableEntry>(), 1);
+
+    // Initialized to all 0 bits.
+    let mut entry = RedirectionTableEntry::new();
+    assert_eq!(entry.get_acknowledged(), false);
+    assert_eq!(entry.get_trigger_mode(), TriggerMode::Edge);
+    assert_eq!(entry.get_delivery_mode(), DeliveryMode::Fixed);
+
+    entry.set_acknowledged(true);
+    entry.set_delivery_mode(DeliveryMode::SMI);
+    assert_eq!(entry.get_acknowledged(), true);
+    assert_eq!(entry.get_trigger_mode(), TriggerMode::Edge);
+    assert_eq!(entry.get_delivery_mode(), DeliveryMode::SMI);
+}

bitfield/tests/06-enums.rs

@@ -0,0 +1,49 @@
+// For bitfield use limited to a single binary, such as a space optimization for
+// some in-memory data structure, we may not care what exact bit representation
+// is used for enums.
+//
+// Make your BitfieldSpecifier derive macro for enums use the underlying
+// discriminant determined by the Rust compiler as the bit representation. Do
+// not assume that the compiler uses any particular scheme like PREV+1 for
+// implicit discriminants; make sure your implementation respects Rust's choice
+// of discriminant regardless of what scheme Rust uses. This is important for
+// performance so that the getter and setter both compile down to very simple
+// machine code after optimizations.
+//
+// Do not worry about what happens if discriminants are outside of the range
+// 0..2^BITS. We will do a compile-time check in a later test case to ensure
+// they are in range.
+
+use bitfield::*;
+
+#[bitfield]
+pub struct RedirectionTableEntry {
+    delivery_mode: DeliveryMode,
+    reserved: B5,
+}
+
+const F: isize = 3;
+const G: isize = 0;
+
+#[derive(BitfieldSpecifier, Debug, PartialEq)]
+pub enum DeliveryMode {
+    Fixed = F,
+    Lowest,
+    SMI,
+    RemoteRead,
+    NMI,
+    Init = G,
+    Startup,
+    External,
+}
+
+fn main() {
+    assert_eq!(std::mem::size_of::<RedirectionTableEntry>(), 1);
+
+    // Initialized to all 0 bits.
+    let mut entry = RedirectionTableEntry::new();
+    assert_eq!(entry.get_delivery_mode(), DeliveryMode::Init);
+
+    entry.set_delivery_mode(DeliveryMode::Lowest);
+    assert_eq!(entry.get_delivery_mode(), DeliveryMode::Lowest);
+}

bitfield/tests/07-optional-discriminant.rs

@@ -0,0 +1,17 @@
+// Bitfield enums with a number of variants other than a power of two should
+// fail to compile.
+//
+// (Or, if you implemented the optional #[bits = N] enum approach mentioned in
+// the explanation of test case 06, then enums with non-power-of-two variants
+// without a #[bits = N] attribute should fail to compile.)
+
+use bitfield::*;
+
+#[derive(BitfieldSpecifier)]
+pub enum Bad {
+    Zero,
+    One,
+    Two,
+}
+
+fn main() {}

bitfield/tests/08-non-power-of-two.rs

@@ -0,0 +1,5 @@
+error: BitfieldSpecifier expected a number of variants which is a power of 2
+  --> $DIR/08-non-power-of-two.rs:10:10
+   |
+10 | #[derive(BitfieldSpecifier)]
+   |          ^^^^^^^^^^^^^^^^^