Add access types for allowing only unsafe reads and/or writes

Author: phil-opp

Cargo.toml

@@ -14,6 +14,9 @@ repository = "https://github.com/rust-osdev/volatile"
 # Enable unstable features; requires Rust nightly; might break on compiler updates
 unstable = []
 
+[dev-dependencies]
+rand = "0.8.3"
+
 [package.metadata.release]
 no-dev-version = true
 pre-release-replacements = [

src/access.rs

@@ -1,28 +1,56 @@
 pub trait Access {}
 
 /// Helper trait that is implemented by [`ReadWrite`] and [`ReadOnly`].
-pub trait Readable {}
+pub trait Readable: UnsafelyReadable {}
 
 /// Helper trait that is implemented by [`ReadWrite`] and [`WriteOnly`].
-pub trait Writable {}
+pub trait Writable: UnsafelyWritable {}
+
+pub trait UnsafelyReadable {}
+
+pub trait UnsafelyWritable {}
 
 /// Zero-sized marker type for allowing both read and write access.
 #[derive(Debug, Copy, Clone)]
 pub struct ReadWrite;
 impl Access for ReadWrite {}
 impl Readable for ReadWrite {}
+impl UnsafelyReadable for ReadWrite {}
 impl Writable for ReadWrite {}
+impl UnsafelyWritable for ReadWrite {}
 
 /// Zero-sized marker type for allowing only read access.
 #[derive(Debug, Copy, Clone)]
 pub struct ReadOnly;
 
 impl Access for ReadOnly {}
 impl Readable for ReadOnly {}
+impl UnsafelyReadable for ReadOnly {}
 
 /// Zero-sized marker type for allowing only write access.
 #[derive(Debug, Copy, Clone)]
 pub struct WriteOnly;
 
 impl Access for WriteOnly {}
 impl Writable for WriteOnly {}
+impl UnsafelyWritable for WriteOnly {}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct Custom<R, W> {
+    pub read: R,
+    pub write: W,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct NoAccess;
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct SafeAccess;
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct UnsafeAccess;
+
+impl<W> Readable for Custom<SafeAccess, W> {}
+impl<W> UnsafelyReadable for Custom<SafeAccess, W> {}
+impl<W> UnsafelyReadable for Custom<UnsafeAccess, W> {}
+impl<R> Writable for Custom<R, SafeAccess> {}
+impl<R> UnsafelyWritable for Custom<R, SafeAccess> {}
+impl<R> UnsafelyWritable for Custom<R, UnsafeAccess> {}

src/lib.rs

@@ -16,7 +16,9 @@
 #![warn(missing_docs)]
 #![deny(unsafe_op_in_unsafe_fn)]
 
-use access::{ReadOnly, ReadWrite, Readable, Writable, WriteOnly};
+use access::{
+    ReadOnly, ReadWrite, Readable, UnsafelyReadable, UnsafelyWritable, Writable, WriteOnly,
+};
 use core::{fmt, marker::PhantomData, ptr};
 #[cfg(feature = "unstable")]
 use core::{
@@ -178,6 +180,30 @@ where
         f(&mut value);
         self.write(value);
     }
+
+    pub unsafe fn read_unsafe(&self) -> T
+    where
+        A: UnsafelyReadable,
+    {
+        unsafe { ptr::read_volatile(self.pointer) }
+    }
+
+    pub unsafe fn write_unsafe(&mut self, value: T)
+    where
+        A: UnsafelyWritable,
+    {
+        unsafe { ptr::write_volatile(self.pointer, value) };
+    }
+
+    pub unsafe fn update_unsafe<F>(&mut self, f: F)
+    where
+        A: UnsafelyReadable + UnsafelyWritable,
+        F: FnOnce(&mut T),
+    {
+        let mut value = unsafe { self.read_unsafe() };
+        f(&mut value);
+        unsafe { self.write_unsafe(value) };
+    }
 }
 
 /// Method for extracting the wrapped value.
@@ -765,7 +791,7 @@ macro_rules! map_field_mut {
 
 #[cfg(test)]
 mod tests {
-    use super::Volatile;
+    use super::{access::*, Volatile};
     use core::cell::UnsafeCell;
 
     #[test]
@@ -790,6 +816,92 @@ mod tests {
         assert_eq!(val, 43);
     }
 
+    #[test]
+    fn test_access() {
+        let mut val: i64 = 42;
+
+        // ReadWrite
+        assert_eq!(unsafe { Volatile::new(&mut val, ReadWrite) }.read(), 42);
+        unsafe { Volatile::new(&mut val, ReadWrite) }.write(50);
+        assert_eq!(val, 50);
+        unsafe { Volatile::new(&mut val, ReadWrite) }.update(|i| *i += 1);
+        assert_eq!(val, 51);
+
+        // ReadOnly and WriteOnly
+        assert_eq!(unsafe { Volatile::new(&mut val, ReadOnly) }.read(), 51);
+        unsafe { Volatile::new(&mut val, WriteOnly) }.write(12);
+        assert_eq!(val, 12);
+
+        // Custom: safe read + safe write
+        {
+            let access = Custom {
+                read: SafeAccess,
+                write: SafeAccess,
+            };
+            let mut volatile = unsafe { Volatile::new(&mut val, access) };
+            let random: i32 = rand::random();
+            volatile.write(i64::from(random));
+            assert_eq!(volatile.read(), i64::from(random));
+            let random2: i32 = rand::random();
+            volatile.update(|i| *i += i64::from(random2));
+            assert_eq!(volatile.read(), i64::from(random) + i64::from(random2));
+        }
+
+        // Custom: safe read + unsafe write
+        {
+            let access = Custom {
+                read: SafeAccess,
+                write: UnsafeAccess,
+            };
+            let mut volatile = unsafe { Volatile::new(&mut val, access) };
+            let random: i32 = rand::random();
+            unsafe { volatile.write_unsafe(i64::from(random)) };
+            assert_eq!(volatile.read(), i64::from(random));
+            let random2: i32 = rand::random();
+            unsafe { volatile.update_unsafe(|i| *i += i64::from(random2)) };
+            assert_eq!(volatile.read(), i64::from(random) + i64::from(random2));
+        }
+
+        // Custom: safe read + no write
+        {
+            let access = Custom {
+                read: SafeAccess,
+                write: NoAccess,
+            };
+            let random = rand::random();
+            val = random;
+            let mut volatile = unsafe { Volatile::new(&mut val, access) };
+            assert_eq!(volatile.read(), i64::from(random));
+        }
+
+        // Custom: unsafe read + safe write
+        {
+            let access = Custom {
+                read: UnsafeAccess,
+                write: SafeAccess,
+            };
+            let mut volatile = unsafe { Volatile::new(&mut val, access) };
+            let random: i32 = rand::random();
+            volatile.write(i64::from(random));
+            assert_eq!(unsafe { volatile.read_unsafe() }, i64::from(random));
+            let random2: i32 = rand::random();
+            volatile.update_unsafe(|i| *i += i64::from(random2));
+            assert_eq!(
+                volatile.read_unsafe(),
+                i64::from(random) + i64::from(random2)
+            );
+        }
+
+        // Todo: Custom: unsafe read + unsafe write
+        // Todo: Custom: unsafe read + no write
+        // Todo: Custom: no read + safe write
+        // Todo: Custom: no read + unsafe write
+        // Todo: Custom: no read + no write
+
+        // Todo: is there a way to check that a compile error occurs when trying to use
+        // unavailable methods (e.g. `write` when write permission is `UnsafeAccess`)?
+    }
+
     #[test]
     fn test_struct() {
         #[derive(Debug, PartialEq)]