Added latest changes.

Author: ambaxter

book/src/using-bitfields.md

@@ -1,19 +1,28 @@
 # Using the Bitfield Types Generated by Bindgen
 
+## Bitfield Strategy Overview
+
+As Rust does not support bitfields, Bindgen generates an opaque struct for each with the following characteristics
+* Immutable getter functions for each bitfield named ```<bitfield>```
+* Setter functions for each bitfield named ```set_<bitfield>```
+* A static constructor  ```new_bitfield_{1, 2, ...}``` with a parameter for each bitfield contained within the opaque physical field.
+
+## Bitfield examples
+
 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;
+} StructWithBitfields;
 
 // Create a default bitfield
-bitfield create_bitfield();
+StructWithBitfields create_bitfield();
 
 // Print a bitfield
-void print_bitfield(bitfield bfield)
+void print_bitfield(StructWithBitfields bfield);
 ```
 
 Bindgen creates a set of field getters and setters for interacting with the bitset. For example, 
@@ -36,7 +45,7 @@ will print out
 a set to 1
 b set to 1
 c set to 3
-bitfield: a:1, b:1, c:3
+StructWithBitfields: 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.
@@ -54,143 +63,22 @@ 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
+StructWithBitfields: a:1, b:1, c:0
 ```
 
-## Unsigned bitfield gotcha
+To create a new bitfield in Rust, use the bitfield allocation unit constructor.
 
-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);
-}
-```
+Note: This requires the Builder's derive_default to be set to true, otherwise the necessary Default functions won't be generated.
 
 ```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) };
-}
+    let bfield = StructWithBitfields{
+        _bitfield_1: StructWithBitfields::new_bitfield_1(0,0,0),
+        ..Default::default()
+    };    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());
-}
-```
+This will print out
 
 ```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
+StructWithBitfields: a:1, b:0, c:2
 ```