diff --git a/tstdc/src/mutex.rs b/tstdc/src/mutex.rs index 13b025a5e..f17fbffdb 100644 --- a/tstdc/src/mutex.rs +++ b/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 = core::result::Result; -/// 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); -// 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.