[![crates.io](https://img.shields.io/crates/d/volatile-register.svg)](https://crates.io/crates/volatile-register)
[![crates.io](https://img.shields.io/crates/v/volatile-register.svg)](https://crates.io/crates/volatile-register)

# `volatile-register`

> Volatile access to memory mapped hardware registers

Adds debug to volatile register when compiled with `--features debug-fmt`.

## Caveats

Notice, the current implementation of `array-debug` (see `examples/example2.rs`) requires a nightly toolchain (`#![feature(unsize)]`). This is however an "opt-in", and needed to support `#[derive(Debug)]` for cases with (register) arrays larger than 32 elements.


``` 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 elements, `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

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.