Rust 122 🦀 Device Driver Development and Hardware Register Mapping (volatile) - KandZ

⏱️ Estimated read: 13 min | |

A device driver is the bridge between software and physical hardware. On a microcontroller or a kernel, the CPU communicates with peripherals—UART controllers, GPIO banks, timers, network cards—by reading from and writing to fixed memory addresses. These are not ordinary RAM. Reading a status register might clear a pending interrupt. Writing a data register might transmit a byte over a wire. The compiler cannot know these side effects, and if it optimizes away a read because “nothing changed,” or reorders a write because “no one depends on it,” the device fails. The volatile read and write operations are the compiler-level contract that prevents this optimization, ensuring every access the driver makes actually reaches the hardware.

Key point: read_volatile and write_volatile tell the compiler “this access has side effects; do not elide it, do not reorder it across other volatile operations.” They do not provide atomicity, synchronization, or mutual exclusion. A read-modify-write sequence on a shared register requires additional synchronization, or the driver will race with itself.

Why volatile operations exist

The optimization problem. The compiler is designed to eliminate redundant loads and stores. If a driver reads a status register twice in a loop and the compiler sees no intervening write, it may cache the first value and skip the second read. For normal memory, this is correct and desirable. For a hardware register, the value can change at any time—a packet can arrive, a byte can be received, an interrupt can be raised—without any CPU instruction. The second read must happen, and read_volatile forces it .

The reordering problem. The compiler may reorder stores to improve cache behavior or pipeline utilization. For a device driver, ordering is often critical. A command register must be written before a data register. An interrupt flag must be cleared after the status is read. Volatile operations are guaranteed not to be reordered relative to other volatile operations, preserving the sequence the driver author intended .

The MMIO boundary problem. Memory-mapped I/O regions are not backed by RAM. They have no ownership semantics, no initialization requirements, and no alignment guarantees beyond what the hardware specifies. The Rust compiler cannot verify that a pointer to 0x4000_0000 is a valid UART register. The volatile operations are unsafe because the caller asserts that the address is valid for the operation being performed . This is the boundary where the driver author takes responsibility for the hardware contract.

The abstraction problem. Writing read_volatile and write_volatile directly throughout a driver is error-prone and unreadable. Modern Rust embedded code wraps these operations in types that encode access permissions: ReadOnly<T>, WriteOnly<T>, and Volatile<T>. The volatile-register crate provides RO, WO, and RW types with read(), write(), and modify() methods that perform the correct volatile operation for the register’s access mode . The virtio-drivers crate uses a similar pattern with VolatileReadable and VolatileWritable traits implemented for raw pointers to these register types .

The trade-off. Volatile operations prevent compiler optimizations. A loop that reads a register on every iteration cannot be hoisted, vectorized, or unrolled. This is necessary for correctness but makes volatile-heavy code slower than equivalent RAM operations. The driver author must balance the number of volatile accesses against the hardware’s requirements.

a. Raw volatile operations and safety contracts

The core::ptr module provides the fundamental operations. read_volatile performs a volatile read from a raw pointer and returns the value. write_volatile performs a volatile write to a raw pointer. Both are unsafe functions .

use core::ptr::{read_volatile, write_volatile};

// A raw pointer to a hardware register.
let status_reg = 0x4000_0000 as *const u32;
let control_reg = 0x4000_0004 as *mut u32;

unsafe {
    // Force a read from the hardware.
    let status = read_volatile(status_reg);
    
    // Force a write to the hardware.
    write_volatile(control_reg, 0x01);
}

The safety contract for read_volatile requires that the pointer is valid for reads, properly aligned, and points to a properly initialized value of the type. For MMIO, “properly initialized” is a misnomer—the hardware provides the value—but the alignment requirement remains. A u32 register must be accessed at a 4-byte-aligned address . write_volatile requires that the pointer is valid for writes and properly aligned .

The critical limitation is that volatile is a property of the operation, not the memory. It does not make the access atomic. A read-modify-write sequence—read a register, modify a bit, write it back—is three separate operations. If an interrupt occurs between the read and the write, and the interrupt handler modifies the same register, the final write overwrites the interrupt’s change. This is a lost update. The driver must either disable interrupts during the sequence or use a hardware mechanism (like bit-band aliasing or atomic set/clear registers) that the peripheral provides .

b. Register abstraction types

Direct pointer arithmetic becomes unreadable quickly. The volatile-register crate provides RO<T>, WO<T>, and RW<T> types that wrap the volatile operations. The driver defines a #[repr(C)] struct that mirrors the hardware’s register layout, including reserved gaps, and casts the base address to a pointer to that struct .

use volatile_register::{RO, RW, WO};

#[repr(C)]
pub struct UartRegisters {
    // Data register: write to transmit, read to receive.
    pub dr: RW<u32>,
    // Status register: read-only.
    pub sr: RO<u32>,
    // Control register: write-only.
    pub cr: WO<u32>,
    // Reserved space matching the hardware layout.
    _reserved: [u8; 0x10],
}

The RW type provides read(), write(), and modify(). The modify() method is an unsafe read-modify-write because it is not atomic. The RO type provides only read(). The WO type provides only write(). These restrictions catch errors at compile time: writing to a read-only register is a type error, not a runtime surprise .

The virtio-drivers crate uses a slightly different approach. Its Volatile<T> wrapper uses #[repr(transparent)] to ensure the struct has the same layout as the inner type. The VolatileReadable and VolatileWritable traits are implemented for *const ReadOnly<T> and *mut WriteOnly<T>, respectively. The volread! and volwrite! macros perform the pointer arithmetic and volatile access in a single expression .

// Inside virtio-drivers: a macro for volatile field reads.
macro_rules! volread {
    ($nonnull:expr, $field:ident) => {
        VolatileReadable::vread((&raw const (*$nonnull.as_ptr()).$field))
    };
}

The macro takes a NonNull<MmioDevice> and a field name, computes the field’s address, and invokes the volatile read. This keeps the driver code declarative: the register access is a named field, not a hexadecimal offset.

c. The architectural caveat: volatile is not a memory barrier

Volatile operations prevent the compiler from eliding or reordering volatile operations relative to each other. They do not prevent the CPU from reordering memory operations, and they do not prevent the compiler from reordering non-volatile operations across volatile ones. On weakly-ordered architectures like ARM, this distinction is critical.

The virtio-drivers crate encountered this issue on aarch64. The standard write_volatile on aarch64 uses a normal str instruction, which can be reordered by the CPU’s memory subsystem. For VirtIO device registers, the ordering must be stricter. The solution was to use inline assembly with str and ldr instructions, which the architecture guarantees to be ordered relative to other device memory accesses .

// On aarch64, use inline assembly for MMIO ordering guarantees.
#[cfg(target_arch = "aarch64")]
core::arch::asm!(
    "str {value:w}, [{ptr}]",
    value = in(reg) data,
    ptr = in(reg) ptr,
);

If the driver requires ordering between a volatile write and subsequent normal memory accesses, it must use a memory barrier (DMB or DSB on ARM, mfence on x86) in addition to the volatile operation. The volatile operation guarantees the compiler will not elide it; the barrier guarantees the CPU will not reorder it .

Complete Example Session

# ============================================
# PART 1: RAW VOLATILE ACCESS
# ============================================

use core::ptr::{read_volatile, write_volatile};

// A UART base address (hypothetical).
const UART_BASE: usize = 0x4000_0000;

unsafe {
    // Read the status register.
    let status = read_volatile((UART_BASE + 0x04) as *const u32);
    
    // Write to the data register.
    write_volatile((UART_BASE + 0x00) as *mut u32, b'A' as u32);
}

# ============================================
# PART 2: REGISTER STRUCT DEFINITION
# ============================================

use volatile_register::{RO, RW, WO};

#[repr(C)]
pub struct Uart {
    pub dr: RW<u32>,        // 0x00: Data register
    pub sr: RO<u32>,        // 0x04: Status register
    pub cr: WO<u32>,        // 0x08: Control register
    _reserved: [u8; 0x14],  // Padding to next register block
}

# ============================================
# PART 3: SAFE ACCESS VIA REGISTER TYPES
# ============================================

// Cast the base address to the register struct.
let uart = UART_BASE as *const Uart;

unsafe {
    // Read status safely (RO provides only read).
    let status = (*uart).sr.read();
    
    // Write control safely (WO provides only write).
    (*uart).cr.write(0x01);
    
    // Read-modify-write on data register (unsafe, not atomic).
    (*uart).dr.modify(|v| v | 0x80);
}

# ============================================
# PART 4: VOLATILE REGISTER CRATE
# ============================================

// Add to Cargo.toml:
// volatile-register = "0.2"

# ============================================
# PART 5: THE READ-MODIFY-WRITE HAZARD
# ============================================

// WARNING: This sequence is not atomic.
// If an interrupt modifies `dr` between read and write,
// the interrupt's change is lost.
unsafe {
    let old = (*uart).dr.read();
    (*uart).dr.write(old | 0x01);
}

// The correct approach depends on the hardware:
// - Disable interrupts around the sequence, or
// - Use a hardware set/clear register.

# ============================================
# PART 6: VIRTIO-STYLE TRAITS
# ============================================

// virtio-drivers uses traits for volatile access.
pub trait VolatileReadable<T> {
    unsafe fn vread(self) -> T;
}

impl<T: Copy> VolatileReadable<T> for *const ReadOnly<T> {
    unsafe fn vread(self) -> T {
        self.read_volatile().0
    }
}

# ============================================
# PART 7: AARCH64 ORDERING WORKAROUND
# ============================================

#[cfg(target_arch = "aarch64")]
unsafe fn mmio_write(ptr: *mut u32, value: u32) {
    core::arch::asm!(
        "str {value:w}, [{ptr}]",
        value = in(reg) value,
        ptr = in(reg) ptr,
    );
}

# ============================================
# PART 8: MEMORY BARRIER
# ============================================

// On x86, a compiler fence may suffice for ordering.
core::sync::atomic::compiler_fence(core::sync::atomic::Ordering::SeqCst);

// On ARM, a hardware barrier is required.
// core::arch::asm!("dmb sy");

# ============================================
# PART 9: COMPLETE DRIVER SKELETON
# ============================================

pub struct UartDriver {
    base: *const Uart,
}

impl UartDriver {
    pub unsafe fn new(base: usize) -> Self {
        Self { base: base as *const Uart }
    }
    
    pub unsafe fn send(&self, byte: u8) {
        (*self.base).dr.write(byte as u32);
    }
    
    pub unsafe fn receive(&self) -> u8 {
        (*self.base).dr.read() as u8
    }
}

The nine parts trace the driver development lifecycle: raw volatile access, struct-based register abstraction, safe access via register types, the volatile-register crate, the read-modify-write hazard, trait-based access, the aarch64 ordering workaround, memory barriers, and a complete driver skeleton.

Quick Reference

Volatile Operations

Function	Purpose
`read_volatile<T>(src: *const T) -> T`	Force a volatile read
`write_volatile<T>(dst: *mut T, src: T)`	Force a volatile write

Register Types (volatile-register)

Type	Methods	Use
`RO<T>`	`read()`	Read-only status registers
`WO<T>`	`write()`	Write-only command registers
`RW<T>`	`read()`, `write()`, `modify()`	Read-write control registers

Safety Requirements

Operation	Requirements
`read_volatile`	Pointer valid, aligned, initialized
`write_volatile`	Pointer valid, aligned

Best Practices

✅ Do This:

let status = read_volatile(status_reg);
<!-- Force the hardware read -->                    # ✅

(*uart).sr.read()
<!-- Use RO to prevent accidental writes -->        # ✅

// Disable interrupts around RMW
unsafe { interrupt::free(|_| { (*reg).modify(...) }) }
<!-- Protect read-modify-write sequences -->        # ✅

❌ Don’t Do This:

let status = *status_reg;
<!-- Compiler may cache or elide the read -->       # ❌

(*uart).sr.write(0);
<!-- RO has no write method; type error -->        # ❌

let old = read_volatile(reg);
// ... interrupt happens ...
write_volatile(reg, old | 1);
<!-- Lost update if interrupt modified reg -->      # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Register read optimized away	Compiler sees no dependence	Use `read_volatile`
Lost update on RMW	Interrupt between read and write	Disable interrupts or use atomic hardware
Unaligned access fault	Pointer not aligned for type	Ensure address alignment matches register width
Ordering violation on ARM	CPU reorders MMIO accesses	Add memory barrier (`DMB`)
Wrong register accessed	Hex offset typo	Use `#[repr(C)]` struct with named fields

Real-World Examples

1. Read a Status Register

let status = read_volatile(0x4000_0004 as *const u32);

2. Write a Command Register

write_volatile(0x4000_0008 as *mut u32, 0x01);

3. Register Struct

#[repr(C)]
struct Uart { dr: RW<u32>, sr: RO<u32>, cr: WO<u32> }

4. Safe Read

let sr = unsafe { (*uart).sr.read() };

5. Safe Write

unsafe { (*uart).cr.write(0x01) };

6. Modify (Unsafe RMW)

unsafe { (*uart).dr.modify(|v| v | 1) };

7. Virtio Read Trait

unsafe { ptr.vread() }

8. AArch64 MMIO Write

core::arch::asm!("str {v}, [{p}]", v = in(reg) val, p = in(reg) ptr);

9. Compiler Fence

compiler_fence(Ordering::SeqCst);

10. Disable Interrupts for RMW

interrupt::free(|_| unsafe { (*reg).modify(...) });

Visual

Volatile Access vs Normal Access

┌──────────────────────────────────────────────┐
│  Normal read: let x = *reg;                  │
│                                              │
│  Compiler: "No write between reads.          │
│  Cache the value. Skip the second read."     │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Hardware: Status changed, but CPU never     │
│  saw it. Driver reads stale value.           │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Volatile read: read_volatile(reg)           │
│                                              │
│  Compiler: "This is a volatile operation.    │
│  Cannot elide. Cannot reorder."              │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Hardware: Every read reaches the register.  │
│  Driver sees current status.                 │
└──────────────────────────────────────────────┘

The volatile keyword is a contract between the driver author and the compiler.

Read-Modify-Write Hazard

┌──────────────────────────────────────────────┐
│  Driver: read reg → value = 0b0001           │
└──────────────────┬───────────────────────────┘
                   │
                   │ INTERRUPT: sets bit 2
                   ▼
┌──────────────────────────────────────────────┐
│  Hardware: reg = 0b0101                      │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Driver: write reg ← value | 0b0010 = 0b0011 │
│  Bit 2 (set by interrupt) is overwritten.    │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  LOST UPDATE. Hardware expected 0b0111.      │
└──────────────────────────────────────────────┘

Volatile does not make the sequence atomic. The interrupt must be masked or the hardware must provide atomic set/clear registers.

Summary

Item	Value
Volatile read	`core::ptr::read_volatile`
Volatile write	`core::ptr::write_volatile`
Register types	`RO<T>`, `WO<T>`, `RW<T>` (volatile-register)
RMW hazard	Volatile does not provide atomicity
Ordering on ARM	Requires `DMB`/`DSB` or inline assembly
Safety requirement	Valid, aligned pointer; correct access width
Struct layout	`#[repr(C)]` to match hardware

Key takeaways:

Volatile prevents optimization, not races. read_volatile and write_volatile force the compiler to emit the access, but they do not make the access atomic or synchronized .
Register structs provide type safety. Wrapping registers in RO, WO, and RW types catches access violations at compile time. Writing to a read-only register is a type error .
Read-modify-write is not atomic. A sequence of volatile operations can be interrupted. The driver must disable interrupts or use hardware atomic registers when modifying shared state .
Ordering requires barriers on weak architectures. On ARM, volatile operations may still be reordered by the CPU. Memory barriers (DMB, DSB) or inline assembly are required for strict ordering .
The safety contract is on the caller. The pointer must be valid for the hardware, properly aligned for the access width, and the operation must match the register’s purpose.

Remember: A device driver is a contract with hardware. The compiler does not understand that contract; it only understands memory. Volatile operations are the signal that the memory is special—that reads and writes have consequences beyond the data they carry. Use them for every MMIO access, wrap them in types that encode permissions, and never assume that a sequence of volatile operations is atomic.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!