examples and documentation

.vscode/tasks.json

+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "type": "shell",
+            "label": "cargo run --example example --features debug-fmt",
+            "command": "cargo run --example example --features debug-fmt",
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "type": "shell",
+            "label": "cargo run --example example2 --features debug-fmt",
+            "command": "cargo run --example example2 --features debug-fmt",
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}
\ No newline at end of file

Cargo.toml

@@ -18,4 +18,6 @@ vcell = "0.1.0"
 
 [features]
 debug-fmt = []
-#default = ["debug-fmt"]
+
\ No newline at end of file
+[dev-dependencies]
+array-debug = { git = "https://gitlab.henriktjader.com/pln/array-debug" }
\ No newline at end of file

README.md

@@ -5,6 +5,73 @@
 
 > Volatile access to memory mapped hardware registers
 
+Adds debug to volatile register when compiled with `--features debug-fmt`.
+
+``` rust
+extern crate volatile_register;
+use std::mem;
+use volatile_register::{RW};
+
+ #[repr(C)]
+ #[derive(Debug)]
+ pub struct Nvic {
+     /// Interrupt Set-Enable
+     pub iser: [RW<u32>; 8],
+     reserved0: [u32; 24],
+     /// Interrupt Clear-Enable
+     pub icer: [RW<u32>; 8],
+     reserved1: [u32; 24],
+     // .. more registers ..
+}
+
+fn main() {
+    let r : Nvic = unsafe {mem::uninitialized() }; 
+    println!("{:?}", r);
+}
+```
+
+This will render an output of the form:
+
+``` txt
+Nvic { iser: [0xB618860, 0x7FFE, 0x20, 0x0, 0x0, 0x7F70, 0x30, 0x0], reserved0: [7, 0, 3, 0, 274354200, 22074, 31, 0, 80, 0, 4294967024, 4294967295, 0, 0, 3, 48, 0, 0, 0, 0, 91, 110, 0, 0], icer: [0x77, 0x7C, 0xFFFFFEF0,0xFFFFFFFF, 0xC3041AA0, 0x7F70, 0x20, 0x0], reserved1: [132352, 0, 3271845168, 32624, 274356992, 22074, 1, 0, 3272547558, 32624, 3269993280, 32624, 274357008, 22074, 3272638464, 32624, 252047400, 22074, 3269993088, 32624, 3270237052, 32624, 274356816, 22074] }
+```
+
+Registers will be formatted under `UpperHex`, notice in the example that arrays are of size less than 32, hence `Debug` of array (`[T; N]`) is implemented by default. Notice that the `reserved` fields falls back to the default integer formatting (as not wrapped by the `volatile-register` abstraction).
+
+For register arrays with more then 32 items, `array-debug` provides a newtype over array, replicating the array behavior while providing `Debug`.
+
+``` rust
+extern crate array_debug;
+extern crate volatile_register;
+
+use array_debug::ArrayDebug;
+use std::mem;
+use volatile_register::RW;
+
+#[repr(C)]
+#[derive(Debug)]
+pub struct Nvic {
+    /// Interrupt Set-Enable
+    pub iser: ArrayDebug<[RW<u32>; 38], RW<u32>>,
+    reserved0: [u32; 24],
+    /// Interrupt Clear-Enable
+    pub icer: [RW<u32>; 8],
+    reserved1: [u32; 24],
+    // .. more registers ..
+}
+
+fn main() {
+    let r: Nvic = unsafe { mem::uninitialized() };
+    println!("{:?}", r);
+}
+```
+
+Rendering output of the form:
+
+``` text
+Nvic { iser: [0x3, 0x30, 0x0, 0x0, 0x0, 0x0, 0x5B, 0x6E, 0x0, 0x0, 0x77, 0x7C, 0x4C6DAEC0, 0x7F95, 0x1F, 0x0, 0x20, 0x0, 0x1, 0x0, 0xFFFFFEF0, 0xFFFFFFFF, 0x0, 0x0, 0x4C65C340, 0x7F95, 0x4C6E2967, 0x7F95, 0x20, 0x0, 0xD7FADB10, 0x7FFF, 0x20, 0x0, 0x0, 0x7F95, 0x30, 0x0], reserved0: [7, 0, 3, 0, 4060155928, 22095, 31, 0, 80, 0, 4294967024, 4294967295, 0, 0, 3, 48, 0, 0, 0, 0, 91, 110, 0, 0], icer: [0x77, 0x7C, 0xFFFFFEF0, 0xFFFFFFFF, 0x4C81BAA0, 0x7F95, 0x20, 0x0], reserved1: [132352, 0, 1283589424, 32661, 4060158720, 22095, 1, 0, 1284291814, 32661, 1281737536, 32661, 4060158736, 22095, 1284382720, 32661, 4038778920, 22095, 1281737344, 32661, 1281981308, 32661, 4060158544, 22095] }
+```
+
 ## [Documentation](https://docs.rs/crate/volatile-register)
 
 ## License

examples/example.rs

+extern crate volatile_register;
+use std::mem;
+use volatile_register::{RW};
+
+ #[repr(C)]
+ #[derive(Debug)]
+ pub struct Nvic {
+     /// Interrupt Set-Enable
+     pub iser: [RW<u32>; 8],
+     reserved0: [u32; 24],
+     /// Interrupt Clear-Enable
+     pub icer: [RW<u32>; 8],
+     reserved1: [u32; 24],
+     // .. more registers ..
+}
+
+fn main() {
+    let r : Nvic = unsafe {mem::uninitialized() }; 
+    println!("{:?}", r);
+}
\ No newline at end of file

examples/example2.rs

+extern crate array_debug;
+extern crate volatile_register;
+
+use array_debug::ArrayDebug;
+use std::mem;
+use volatile_register::RW;
+
+#[repr(C)]
+#[derive(Debug)]
+pub struct Nvic {
+    /// Interrupt Set-Enable
+    pub iser: ArrayDebug<[RW<u32>; 38], RW<u32>>,
+    reserved0: [u32; 24],
+    /// Interrupt Clear-Enable
+    pub icer: [RW<u32>; 8],
+    reserved1: [u32; 24],
+    // .. more registers ..
+}
+
+fn main() {
+    let r: Nvic = unsafe { mem::uninitialized() };
+    println!("{:?}", r);
+}