embedded-shadow 0.1.0

Zero-alloc shadow register table with dirty tracking for embedded systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# embedded-shadow

A `no_std`, no-alloc shadow register table for embedded systems with dirty tracking and transactional writes.

## Features

- **Zero allocation** - All storage is statically allocated via const generics
- **Dirty tracking** - Efficiently track which blocks have been modified
- **Dual views** - Separate Host (application) and Kernel (hardware) access patterns  
- **Access policies** - Control read/write permissions for different memory regions
- **Persistence policies** - Define what and when data should be persisted
- **Staging support** - Preview and commit/rollback transactional writes
- **Critical-section support** - Thread-safe access when needed

## Quick Start

```rust
use embedded_shadow::prelude::*;

// Create a 1KB shadow register table
let storage = ShadowStorageBuilder::new()
    .total_size::<1024>()
    .block_size::<64>()
    .block_count::<16>()
    .default_access()
    .no_persist()
    .build();

// Host writes data (marks dirty)
let host = storage.host_shadow();
host.with_view(|view| {
    view.write_range(0x100, &[0x01, 0x02, 0x03, 0x04])?;
    Ok(())
});

// Kernel syncs dirty blocks to hardware
let kernel = storage.kernel_shadow();
kernel.with_view(|view| {
    view.for_each_dirty_block(|addr, data| {
        // Write to hardware registers
        hardware_write(addr, data);
        Ok(())
    })?;
    view.clear_dirty();
    Ok(())
});
```

## Examples

See the [examples](examples/) directory for detailed usage:

- [`basic.rs`](examples/basic.rs) - Core concepts and dirty tracking
- [`staging.rs`](examples/staging.rs) - Transactional writes with preview/commit/rollback
- [`access_policy.rs`](examples/access_policy.rs) - Memory protection and access control
- [`persist.rs`](examples/persist.rs) - Flash persistence patterns
- [`complex.rs`](examples/complex.rs) - Real-world motor controller simulation

## Critical Section

This crate requires a `critical-section` implementation for your platform. Most embedded HALs provide this. For testing, add:

```toml
[dev-dependencies]
critical-section = { version = "1.2", features = ["std"] }
```

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.