Update documentation on Mutex

tstdc/src/mutex.rs

@@ -1,6 +1,6 @@
 // Copyright (c) 2023 The MobileCoin Foundation
 
-//! Mutex functionality for an SGX enclave
+//! Mutex functionality for use inside of an SGX enclave
 
 use core::cell::UnsafeCell;
 use mc_sgx_tstdc_sys::{
@@ -20,16 +20,29 @@ pub enum Error {
 
 type Result<T> = core::result::Result<T, Error>;
 
-/// A mutex inside of an SGX enclave
+/// Rust wrapper for an SGX SDK mutex used inside of an enclave.
+///
+/// A [`Mutex`] does *not* wrap up data directly. It is a primitive which can be
+/// used to create a higher level Mutex analogous to
+/// [`std::sync::Mutex`](https://doc.rust-lang.org/std/sync/struct.Mutex.html).
+/// It handles locking, unlocking and freeing of the underlying SGX SDK mutex
 ///
 /// NB: per the documentation of
 /// [`sgx_thread_mutex_lock()`](https://download.01.org/intel-sgx/sgx-linux/2.18/docs/Intel_SGX_Developer_Reference_Linux_2.18_Open_Source.pdf#%5B%7B%22num%22%3A303%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C94.5%2C341.25%2C0%5D)
 /// a mutex should not be locked across root ECALLs.
+///
+/// Threads that run inside the enclave are created within the (untrusted)
+/// application.
+///
+/// Each concurrent root ECALL that starts from the (untrusted) application will
+/// use a separate thread in the SGX enclave. [`Mutex`]es can be used to protect
+/// shared global data that needs to be accessed by multiple concurrent root
+/// ECALLs.
+// SAFETY: The `sgx_thread_mutex_*` C functions utilize a spinlock to prevent
+//  concurrent access to the underlying `sgx_thread_mutex_t`
 #[derive(Debug, Default)]
 pub struct Mutex(UnsafeCell<sgx_thread_mutex_t>);
 
-// SAFETY: The `sgx_thread_mutex_*` C functions utilize a spinlock to prevent
-//  concurrent access to the underlying `sgx_thread_mutex_t`
 unsafe impl Send for Mutex {}
 unsafe impl Sync for Mutex {}
 
@@ -39,9 +52,9 @@ impl Mutex {
         Self(UnsafeCell::new(SGX_THREAD_NONRECURSIVE_MUTEX_INITIALIZER))
     }
 
-    /// Lock self
+    /// Lock this [`Mutex`] instance
     ///
-    /// Blocks the current thread waiting for the mutex lock or an error.
+    /// Blocks the current thread waiting for the mutex lock or an [`Error`].
     ///
     /// # Errors
     /// [`Error::Invalid`] will be returned if self is invalid or trying to lock
@@ -54,9 +67,9 @@ impl Mutex {
         }
     }
 
-    /// Try to lock self
+    /// Try to lock this [`Mutex`] instance
     ///
-    /// Returns immediately with the mutex or an error
+    /// Returns immediately with the mutex or an [`Error`]
     ///
     /// # Errors
     /// - [`Error::Busy`] if another thread has the lock, or higher precedence
@@ -72,9 +85,9 @@ impl Mutex {
         }
     }
 
-    /// Unlock self
+    /// Unlock this [`Mutex`] instance
     ///
-    /// Returns immediately with the mutex or an error
+    /// Returns immediately with [`Ok`] or an [`Error`].
     ///
     /// # Errors
     /// - [`Error::Busy`] if another thread has the lock.