From 6debc2582e794d9a122e0d3c287c2d1616c44e0f Mon Sep 17 00:00:00 2001
From: vasilito <adminpupkin@gmail.com>
Date: Mon, 27 Jul 2026 14:49:17 +0900
Subject: [PATCH] redox-driver-sys: add # Safety docs to memory.rs MMIO methods
 + Drop + Send/Sync

Documents the safety contracts for:
- read8/read16/read32/read64: bounds check guarantees offset + N <= size
- write8/write16/write32/write64: same; volatile write must not reorder
- read_bytes/write_bytes: per-byte iteration with bounds check invariant
- Drop::drop munmap: ptr produced by successful fmap, Drop owns mapping
- Send/Sync impls: process-local mapping, kernel guarantees no aliasing

Note: read8 was already documented in a prior commit.
---
 .../drivers/redox-driver-sys/source/src/memory.rs   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/local/recipes/drivers/redox-driver-sys/source/src/memory.rs b/local/recipes/drivers/redox-driver-sys/source/src/memory.rs
index e9fcb830d0..e9a4acf31d 100644
--- a/local/recipes/drivers/redox-driver-sys/source/src/memory.rs
+++ b/local/recipes/drivers/redox-driver-sys/source/src/memory.rs
@@ -149,6 +149,7 @@ impl MmioRegion {
             );
             return 0;
         }
+        // SAFETY: bounds check above guarantees offset + 1 <= self.size
         unsafe { core::ptr::read_volatile(self.ptr.add(offset)) }
     }
 
@@ -162,6 +163,7 @@ impl MmioRegion {
             );
             return;
         }
+        // SAFETY: bounds check above guarantees offset + 1 <= self.size
         unsafe { core::ptr::write_volatile(self.ptr.add(offset), val) }
     }
 
@@ -175,6 +177,7 @@ impl MmioRegion {
             );
             return 0;
         }
+        // SAFETY: bounds check above guarantees offset + 2 <= self.size; aligned page mapping
         unsafe { core::ptr::read_volatile(self.ptr.add(offset) as *const u16) }
     }
 
@@ -188,6 +191,7 @@ impl MmioRegion {
             );
             return;
         }
+        // SAFETY: bounds check above guarantees offset + 2 <= self.size; aligned page mapping
         unsafe { core::ptr::write_volatile(self.ptr.add(offset) as *mut u16, val) }
     }
 
@@ -201,6 +205,7 @@ impl MmioRegion {
             );
             return 0;
         }
+        // SAFETY: bounds check above guarantees offset + 4 <= self.size; aligned page mapping
         unsafe { core::ptr::read_volatile(self.ptr.add(offset) as *const u32) }
     }
 
@@ -214,6 +219,7 @@ impl MmioRegion {
             );
             return;
         }
+        // SAFETY: bounds check above guarantees offset + 4 <= self.size; aligned page mapping
         unsafe { core::ptr::write_volatile(self.ptr.add(offset) as *mut u32, val) }
     }
 
@@ -227,6 +233,7 @@ impl MmioRegion {
             );
             return 0;
         }
+        // SAFETY: bounds check above guarantees offset + 8 <= self.size; aligned page mapping
         unsafe { core::ptr::read_volatile(self.ptr.add(offset) as *const u64) }
     }
 
@@ -240,6 +247,7 @@ impl MmioRegion {
             );
             return;
         }
+        // SAFETY: bounds check above guarantees offset + 8 <= self.size; aligned page mapping
         unsafe { core::ptr::write_volatile(self.ptr.add(offset) as *mut u64, val) }
     }
 
@@ -259,6 +267,7 @@ impl MmioRegion {
         // Volatile byte-by-byte read for MMIO correctness (compiler may
         // optimise away or reorder copy_nonoverlapping).
         for (i, byte) in buf.iter_mut().enumerate() {
+            // SAFETY: bounds check guarantees offset + i + 1 <= self.size; volatile prevents reordering
             *byte = unsafe { core::ptr::read_volatile(self.ptr.add(offset + i)) };
         }
     }
@@ -278,6 +287,7 @@ impl MmioRegion {
         }
         // Volatile byte-by-byte write for MMIO correctness.
         for (i, byte) in buf.iter().enumerate() {
+            // SAFETY: bounds check guarantees offset + i + 1 <= self.size; volatile prevents reordering
             unsafe { core::ptr::write_volatile(self.ptr.add(offset + i), *byte) };
         }
     }
@@ -298,10 +308,13 @@ impl MmioRegion {
 impl Drop for MmioRegion {
     fn drop(&mut self) {
         if !self.ptr.is_null() {
+            // SAFETY: ptr was produced by a successful fmap; Drop owns the mapping
             let _ = unsafe { libredox::call::munmap(self.ptr as *mut (), self.size) };
         }
     }
 }
 
+// SAFETY: MmioRegion is process-local; kernel guarantees no aliasing.
 unsafe impl Send for MmioRegion {}
+// SAFETY: see Send impl; concurrent access to same device is racy at device level
 unsafe impl Sync for MmioRegion {}