From 997eb9e47269e7bc39a14b6ec54c4a095bb0e8f1 Mon Sep 17 00:00:00 2001
From: "Cliff L. Biffle" <code@cliffle.com>
Date: Thu, 25 Apr 2024 20:16:54 -0700
Subject: [PATCH] Fix remaining safety comments, turn on warning

---
 os/src/exec.rs  |  3 +++
 os/src/lib.rs   |  1 +
 os/src/mutex.rs | 10 ++++++++++
 os/src/spsc.rs  |  4 ++--
 4 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/os/src/exec.rs b/os/src/exec.rs
index e46adae..0ede3e5 100644
--- a/os/src/exec.rs
+++ b/os/src/exec.rs
@@ -499,6 +499,9 @@ pub unsafe fn run_tasks_with_preemption_and_idle(
         //    be wrong.
         let futures_ptr: *mut [Pin<*mut dyn Future<Output = Infallible>>] = futures_ptr as _;
         // Stash the task future array in a known location.
+        //
+        // Safety: this is written by code but never read back, so the fact that
+        // it's a static mut has no effect on code other than the warning.
         unsafe {
             TASK_FUTURES = Some(futures_ptr);
         }
diff --git a/os/src/lib.rs b/os/src/lib.rs
index 0b180bb..f8ccd15 100644
--- a/os/src/lib.rs
+++ b/os/src/lib.rs
@@ -142,6 +142,7 @@
     unsafe_op_in_unsafe_fn,
     unused_qualifications,
 )]
+#![warn(clippy::undocumented_unsafe_blocks)]
 
 /// Internal assert macro that doesn't stringify its expression or generate any
 /// fancy messages. This means failures must be diagnosed by file:line only, so,
diff --git a/os/src/mutex.rs b/os/src/mutex.rs
index 0ba07bf..0e6e7b1 100644
--- a/os/src/mutex.rs
+++ b/os/src/mutex.rs
@@ -249,8 +249,18 @@ impl<T> Mutex<T> {
         }
     }
 
+    /// Grabs a reference to the contents of the mutex.
+    ///
+    /// Used internally by Deref.
+    ///
+    /// # Safety
+    ///
+    /// For this to be sound, you must ensure that there are no aliasing `&mut`
+    /// references to the contents.
     unsafe fn contents(&self) -> &T {
         let ptr = self.value.get();
+        // Safety: as long as our contract is upheld, this won't produce a
+        // reference aliasing a `&mut` so we should be fine.
         unsafe { &*ptr }
     }
 }
diff --git a/os/src/spsc.rs b/os/src/spsc.rs
index c8cf894..3c43706 100644
--- a/os/src/spsc.rs
+++ b/os/src/spsc.rs
@@ -64,8 +64,8 @@ pub struct Queue<'s, T> {
     pushed: Notify,
 }
 
-/// This type is easily sharable across threads, because there are no useful
-/// operations that can be performed using only a shared reference.
+/// Safety: This type is easily sharable across threads, because there are no
+/// useful operations that can be performed using only a shared reference.
 unsafe impl<T> Sync for Queue<'_, T> where T: Send {}
 
 impl<'s, T> Queue<'s, T> {