Merge pull request #29 from rust-osdev/next

[v0.5] New design with two wrapper types: `VolatilePtr` and `VolatileRef`

Author: phil-opp

.github/workflows/build.yml

@@ -70,6 +70,26 @@ jobs:
           command: test
           args: --features unstable
 
+  very_unstable:
+    name: Test Suite (very_unstable)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+
+      - name: Install nightly toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: nightly
+          override: true
+
+      - name: Run cargo test --features very_unstable
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --features very_unstable
+
 
   lints:
     name: Lints

Cargo.toml

@@ -4,20 +4,25 @@ version = "0.4.6"
 authors = ["Philipp Oppermann <[email protected]>"]
 license = "MIT OR Apache-2.0"
 keywords = ["volatile"]
-description = "A simple volatile wrapper type"
+description = "Volatile wrapper types for raw pointers"
 documentation = "https://docs.rs/volatile"
 repository = "https://github.com/rust-osdev/volatile"
+edition = "2021"
 
 [dependencies]
 
 [features]
 # Enable unstable features; requires Rust nightly; might break on compiler updates
 unstable = []
+# Enable unstable and experimental features; requires Rust nightly; might break on compiler updates
+very_unstable = ["unstable"]
+
+[dev-dependencies]
+rand = "0.8.3"
 
 [package.metadata.release]
-dev-version = false
 pre-release-replacements = [
-    { file="Changelog.md", search="# Unreleased", replace="# Unreleased\n\n# {{version}} – {{date}}", exactly=1 },
+    { file = "Changelog.md", search = "# Unreleased", replace = "# Unreleased\n\n# {{version}} – {{date}}", exactly = 1 },
 ]
 pre-release-commit-message = "Release version {{version}}"
 

Changelog.md

@@ -1,5 +1,12 @@
 # Unreleased
 
+- **Breaking:** [New design based on raw pointers](https://github.com/rust-osdev/volatile/pull/29)
+  - The previous reference-based design was [unsound](https://github.com/rust-osdev/volatile/pull/13#issuecomment-842455552) because it allowed the compiler to insert spurious reads.
+  - The new design features two wrapper types for raw pointers: `VolatilePtr` and `VolatileRef`
+  - `VolatilePtr` provides safe read and write access to volatile values. Like raw pointers, it implements `Copy` and is `!Sync`.
+  - `VolatileRef` is a pointer type that respects Rust's aliasing rules. It doesn't implement `Copy`, requires a `&mut` reference for modification, and implements `Sync`. It can converted to temporary `VolatilePtr` instances through the `as_ptr`/`as_mut_ptr` methods.
+- We now provide methods for volatile slice operations and a `map!` macro for struct field projection. These advanced features are gated behind a cargo feature named _"unstable"_.
+
 # 0.4.6 – 2023-01-17
 
 - Fix UB in slice methods when Deref returns different references ([#27](https://github.com/rust-osdev/volatile/pull/27))

README.md

@@ -2,9 +2,27 @@
 
 [![Build Status](https://github.com/rust-osdev/volatile/workflows/Build/badge.svg)](https://github.com/rust-osdev/volatile/actions?query=workflow%3ABuild) [![Docs.rs Badge](https://docs.rs/volatile/badge.svg)](https://docs.rs/volatile/)
 
-Provides the wrapper type `Volatile`, which wraps a reference to any copy-able type and allows  for volatile memory access to wrapped value. Volatile memory accesses are never optimized away  by the compiler, and are useful in many low-level systems programming and concurrent contexts.
+Provides volatile wrapper types for raw pointers.
 
-The wrapper types *do not* enforce any atomicity guarantees; to also get atomicity, consider looking at the `Atomic` wrapper types found in `libcore` or `libstd`.
+The volatile wrapper types in this crate wrap a pointer to any [`Copy`]-able type and provide volatile memory access to wrapped value.
+Volatile memory accesses are never optimized away by the compiler, and are useful in many low-level systems programming and concurrent contexts.
+
+This crate provides two different wrapper types: [`VolatilePtr`] and [`VolatileRef`].
+The difference between the two types is that the former behaves like a raw pointer, while the latter behaves like a Rust reference type.
+For example, `VolatilePtr` can be freely copied, but not sent across threads because this could introduce mutable aliasing.
+The `VolatileRef` type, on the other hand, requires exclusive access for mutation, so that sharing it across thread boundaries is safe.
+
+Both wrapper types *do not* enforce any atomicity guarantees; to also get atomicity, consider looking at the `Atomic` wrapper types found in `libcore` or `libstd`.
+
+## Why is there no `VolatileCell`?
+
+Many people expressed interest in a `VolatileCell` type, i.e. a transparent wrapper type that owns the wrapped value.
+Such a type would be similar to [`core::cell::Cell`], with the difference that all methods are volatile.
+Unfortunately, it is not sound to implement such a `VolatileCell` type in Rust.
+The reason is that Rust and LLVM consider `&` and `&mut` references as _dereferencable_.
+This means that the compiler is allowed to freely access the referenced value without any restrictions.
+So no matter how a `VolatileCell` type is implemented, the compiler is allowed to perform non-volatile read operations of the contained value, which can lead to unexpected (or even undefined?) behavior.
+For more details, see the discussion [in our repository](https://github.com/rust-osdev/volatile/issues/31) and [in the `unsafe-code-guidelines` repository](https://github.com/rust-lang/unsafe-code-guidelines/issues/411).
 
 ## License
 

src/access.rs

@@ -1,22 +1,83 @@
+//! Marker types for limiting access.
+
+/// Private trait that is implemented for the types in this module.
+pub trait Access: Copy + Default {
+    /// Ensures that this trait cannot be implemented outside of this crate.
+    #[doc(hidden)]
+    fn _private() -> _Private {
+        _Private
+    }
+
+    /// Reduced access level to safely share the corresponding value.
+    type RestrictShared: Access;
+}
+
 /// Helper trait that is implemented by [`ReadWrite`] and [`ReadOnly`].
-pub trait Readable {}
+pub trait Readable: Copy + Default {
+    /// Reduced access level to safely share the corresponding value.
+    type RestrictShared: Readable + Access;
+
+    /// Ensures that this trait cannot be implemented outside of this crate.
+    fn _private() -> _Private {
+        _Private
+    }
+}
 
 /// Helper trait that is implemented by [`ReadWrite`] and [`WriteOnly`].
-pub trait Writable {}
+pub trait Writable: Access {
+    /// Ensures that this trait cannot be implemented outside of this crate.
+    fn _private() -> _Private {
+        _Private
+    }
+}
+
+/// Implemented for access types that permit copying of `VolatileRef`.
+pub trait Copyable {
+    /// Ensures that this trait cannot be implemented outside of this crate.
+    fn _private() -> _Private {
+        _Private
+    }
+}
+
+impl<T> Access for T
+where
+    T: Readable + Default + Copy,
+{
+    type RestrictShared = <T as Readable>::RestrictShared;
+}
 
 /// Zero-sized marker type for allowing both read and write access.
-#[derive(Debug, Copy, Clone)]
+#[derive(Debug, Default, Copy, Clone)]
 pub struct ReadWrite;
-impl Readable for ReadWrite {}
+impl Readable for ReadWrite {
+    type RestrictShared = ReadOnly;
+}
 impl Writable for ReadWrite {}
 
 /// Zero-sized marker type for allowing only read access.
-#[derive(Debug, Copy, Clone)]
+#[derive(Debug, Default, Copy, Clone)]
 pub struct ReadOnly;
-
-impl Readable for ReadOnly {}
+impl Readable for ReadOnly {
+    type RestrictShared = ReadOnly;
+}
+impl Copyable for ReadOnly {}
 
 /// Zero-sized marker type for allowing only write access.
-#[derive(Debug, Copy, Clone)]
+#[derive(Debug, Default, Copy, Clone)]
 pub struct WriteOnly;
+impl Access for WriteOnly {
+    type RestrictShared = NoAccess;
+}
 impl Writable for WriteOnly {}
+
+/// Zero-sized marker type that grants no access.
+#[derive(Debug, Default, Copy, Clone)]
+pub struct NoAccess;
+impl Access for NoAccess {
+    type RestrictShared = NoAccess;
+}
+impl Copyable for NoAccess {}
+
+#[non_exhaustive]
+#[doc(hidden)]
+pub struct _Private;