From 23972ce1e8acbd26ae0413bf14546bbf36893b52 Mon Sep 17 00:00:00 2001
From: Per <Per Lindgren>
Date: Thu, 13 Dec 2018 16:05:23 +0100
Subject: [PATCH] examples and documentation
---
.vscode/tasks.json | 31 ++++++++++++++++++++
Cargo.toml | 4 ++-
README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++
examples/example.rs | 20 +++++++++++++
examples/example2.rs | 23 +++++++++++++++
5 files changed, 144 insertions(+), 1 deletion(-)
create mode 100644 .vscode/tasks.json
create mode 100644 examples/example.rs
create mode 100644 examples/example2.rs
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 0000000..82a5462
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,31 @@
+{
+ // 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
diff --git a/Cargo.toml b/Cargo.toml
index e6bd14d..4aca0f9 100644
--- a/Cargo.toml
+++ b/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
diff --git a/README.md b/README.md
index bd69ff8..efa2f79 100644
--- a/README.md
+++ b/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
diff --git a/examples/example.rs b/examples/example.rs
new file mode 100644
index 0000000..c0e601c
--- /dev/null
+++ b/examples/example.rs
@@ -0,0 +1,20 @@
+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
diff --git a/examples/example2.rs b/examples/example2.rs
new file mode 100644
index 0000000..8241dea
--- /dev/null
+++ b/examples/example2.rs
@@ -0,0 +1,23 @@
+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);
+}
--
GitLab