Added mdbook entry for bitfields.

Author: ambaxter

book/src/SUMMARY.md

@@ -19,4 +19,5 @@
     - [Preventing the Derivation of `Copy` and `Clone`](./nocopy.md)
 - [Generating Bindings to C++](./cpp.md)
 - [Using Unions](./using-unions.md)
+- [Using Bitfields](./using-bitfields.md)
 - [FAQ](./faq.md)

book/src/using-bitfields.md

@@ -0,0 +1,196 @@
+# Using the Bitfield Types Generated by Bindgen
+
+For this discussion, we will use the following C type definitions and functions.
+```c
+typedef struct {
+    unsigned int a: 1;
+    unsigned int b: 1;
+    unsigned int c: 2;
+    
+} bitfield;
+
+// Create a default bitfield
+bitfield create_bitfield();
+
+// Print a bitfield
+void print_bitfield(bitfield bfield)
+```
+
+Bindgen creates a set of field getters and setters for interacting with the bitset. For example, 
+
+```rust,ignore
+    let mut bfield = unsafe { create_bitfield() };
+    
+    bfield.set_a(1);
+    println!("a set to {}", bfield.a());
+    bfield.set_b(1);
+    println!("b set to {}", bfield.b());
+    bfield.set_c(3);
+    println!("c set to {}", bfield.c());
+    unsafe { print_bitfield(bfield) };
+```
+
+will print out
+
+```text
+a set to 1
+b set to 1
+c set to 3
+bitfield: a:1, b:1, c:3
+```
+
+Overflowing a bitfield will result in the same behavior as in C/C++: the bitfield will be set to 0.
+
+```rust,ignore
+    let mut bfield = unsafe { create_bitfield() };
+    bfield.set_a(1);
+    bfield.set_b(1);
+    bfield.set_c(12);
+    println!("c set to {} due to overflow", bfield.c());
+    unsafe { print_bitfield(bfield) };
+```
+
+will print out
+
+```text
+c set to 0 due to overflow
+bitfield: a:1, b:1, c:0
+```
+
+To create a new bitfield in Rust, use mem::zeroed.
+
+```rust,ignore
+    let mut bfield = unsafe { mem::zeroed::<bitfield>() };
+    bfield.set_a(1);
+    bfield.set_c(2);
+    unsafe { print_bitfield(bfield) };
+```
+
+This will print out
+
+```text
+bitfield: a:1, b:0, c:2
+```
+
+## Unsigned bitfield gotcha
+
+Special care should be given to handling unsigned bitfields. Let's change 'c' field to an int. C's valid values are now -2, -1, 0, and 1.
+
+```c
+typedef struct {
+    unsigned int a: 1;
+    unsigned int b: 1;
+    int c: 2;
+
+} bitfield;
+```
+
+Let's now walk the bitfield possibilities in both C and Rust up to the first overflow on each end:
+
+```c
+void walk_bitfield() {
+    bitfield bfield = create_bitfield();
+    print_bitfield(bfield);
+    bfield.c = 1;
+    print_bitfield(bfield);
+    bfield.c = 2;
+    print_bitfield(bfield);
+    bfield.c = 3;
+    print_bitfield(bfield);
+    bfield.c = 4;
+    print_bitfield(bfield);
+    bfield.c = -1;
+    print_bitfield(bfield);
+    bfield.c = -2;
+    print_bitfield(bfield);
+    bfield.c = -3;
+    print_bitfield(bfield);
+    bfield.c = -4;
+    print_bitfield(bfield);
+}
+```
+
+```rust,ignore
+fn walk_bitfield() {
+    let mut bfield = unsafe { mem::zeroed::<bitfield>() };
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(1);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(2);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(3);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(4);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(-1);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(-2);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(-3);
+    unsafe { print_bitfield(bfield) };
+    bfield.set_c(-4);
+    unsafe { print_bitfield(bfield) };
+}
+```
+
+This produces identical results in C's print function:
+
+```text
+Print C walk
+bitfield: a:0, b:0, c:0
+bitfield: a:0, b:0, c:1
+bitfield: a:0, b:0, c:-2
+bitfield: a:0, b:0, c:-1
+bitfield: a:0, b:0, c:0
+bitfield: a:0, b:0, c:-1
+bitfield: a:0, b:0, c:-2
+bitfield: a:0, b:0, c:1
+bitfield: a:0, b:0, c:0
+Print Rust walk
+bitfield: a:0, b:0, c:0
+bitfield: a:0, b:0, c:1
+bitfield: a:0, b:0, c:-2
+bitfield: a:0, b:0, c:-1
+bitfield: a:0, b:0, c:0
+bitfield: a:0, b:0, c:-1
+bitfield: a:0, b:0, c:-2
+bitfield: a:0, b:0, c:1
+bitfield: a:0, b:0, c:0
+```
+
+However, Bindgen's getter provides different results: 
+
+```rust,ignore
+fn getter_walk_bitfield() {
+    let mut bfield = unsafe { mem::zeroed::<bitfield>() };
+    println!("c set to {}", bfield.c());
+    bfield.set_c(1);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(2);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(3);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(4);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(-1);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(-2);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(-3);
+    println!("c set to {}", bfield.c());
+    bfield.set_c(-4);
+    println!("c set to {}", bfield.c());
+}
+```
+
+```text
+c set to 0
+c set to 1
+c set to 2
+c set to 3
+c set to 0
+c set to 3
+c set to 2
+c set to 1
+c set to 0
+```