717: Volatile Memory Reads and Writes

//! 717 — Volatile Reads/Writes for Memory-Mapped I/O
//! read_volatile / write_volatile: prevent compiler elision of I/O accesses.

use std::ptr;

/// Simulated MMIO device with 8 x u32 registers.
/// Uses &mut self for writes — models exclusive hardware register ownership.
pub struct MmioDevice {
    regs: [u32; 8],
}

impl MmioDevice {
    pub fn new() -> Self { Self { regs: [0u32; 8] } }

    /// Volatile write: every write reaches the hardware, no elision.
    pub fn write(&mut self, reg: usize, val: u32) {
        assert!(reg < 8);
        unsafe {
            // SAFETY: reg < 8 == regs.len(); pointer is valid and aligned for u32.
            // Volatile prevents the compiler from merging or reordering writes —
            // critical for hardware registers with side effects on every write.
            ptr::write_volatile(&mut self.regs[reg] as *mut u32, val);
        }
    }

    /// Volatile read: every read goes to hardware, no cached value.
    pub fn read(&self, reg: usize) -> u32 {
        assert!(reg < 8);
        unsafe {
            // SAFETY: reg < 8; pointer is valid and aligned.
            // Hardware may change this register at any time; volatile
            // prevents the compiler from using a prior cached read.
            ptr::read_volatile(&self.regs[reg] as *const u32)
        }
    }

    /// Read-modify-write: read current, apply f, write back.
    pub fn rmw(&mut self, reg: usize, f: impl FnOnce(u32) -> u32) {
        let v = self.read(reg);
        self.write(reg, f(v));
    }

    /// Set specific bits in a register.
    pub fn set_bits(&mut self, reg: usize, mask: u32) {
        self.rmw(reg, |v| v | mask);
    }

    /// Clear specific bits in a register.
    pub fn clear_bits(&mut self, reg: usize, mask: u32) {
        self.rmw(reg, |v| v & !mask);
    }

    /// Poll until bit is set (returns true if set).
    pub fn poll_bit(&self, reg: usize, bit: u32) -> bool {
        (self.read(reg) & (1 << bit)) != 0
    }
}

/// Simulated device transaction protocol.
fn device_transaction(dev: &mut MmioDevice) -> u32 {
    const CMD:    usize = 0;
    const DATA:   usize = 1;
    const STATUS: usize = 2;
    const RESULT: usize = 3;

    dev.write(CMD, 0x01);            // start command
    dev.write(DATA, 0xABCD_1234);    // payload
    dev.write(STATUS, 0x01);         // simulate HW: set ready bit
    dev.write(RESULT, 0xDEAD_BEEF);  // simulate HW: store result

    if dev.poll_bit(STATUS, 0) {
        dev.read(RESULT)
    } else {
        u32::MAX // timeout
    }
}

fn main() {
    let mut dev = MmioDevice::new();

    dev.write(0, 0xFF);
    println!("reg[0] = {:#010x}", dev.read(0));

    let result = device_transaction(&mut dev);
    println!("Transaction result = {:#010x}", result);

    // Demonstrate volatile write+read round-trip
    for i in 0..8usize {
        dev.write(i, i as u32 * 0x1111);
    }
    for i in 0..8usize {
        println!("reg[{i}] = {:#010x}", dev.read(i));
    }

    // bit manipulation
    dev.write(0, 0x0000_0000);
    dev.set_bits(0, 0b0101);
    println!("After set_bits(0b0101): {:#010b}", dev.read(0));
    dev.clear_bits(0, 0b0001);
    println!("After clear_bits(0b0001): {:#010b}", dev.read(0));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_write_read() {
        let mut d = MmioDevice::new();
        d.write(0, 0xCAFE_BABE);
        assert_eq!(d.read(0), 0xCAFE_BABE);
    }

    #[test]
    fn test_independent_regs() {
        let mut d = MmioDevice::new();
        for i in 0..8usize { d.write(i, i as u32 * 10); }
        for i in 0..8usize { assert_eq!(d.read(i), i as u32 * 10); }
    }

    #[test]
    fn test_poll_bit() {
        let mut d = MmioDevice::new();
        d.write(0, 0b0000_0100); // bit 2 set
        assert!(d.poll_bit(0, 2));
        assert!(!d.poll_bit(0, 0));
    }

    #[test]
    fn test_set_clear_bits() {
        let mut d = MmioDevice::new();
        d.write(0, 0b1010);
        d.set_bits(0, 0b0101);
        assert_eq!(d.read(0), 0b1111);
        d.clear_bits(0, 0b1100);
        assert_eq!(d.read(0), 0b0011);
    }
}