Add clarification on why we must take GuestSharedMemory::lock

src/hyperlight_host/src/hypervisor/hypervisor_handler.rs

@@ -322,6 +322,12 @@ impl HypervisorHandler {
                                             e
                                         )
                                     })?;
+                                // This apparently-useless lock is
+                                // needed to ensure the host does not
+                                // make unsynchronized accesses while
+                                // the guest is executing.  See the
+                                // documentation for
+                                // GuestSharedMemory::lock.
                                 let mem_lock_guard = evar_lock_guard
                                     .as_mut()
                                     .ok_or_else(|| {
@@ -399,6 +405,12 @@ impl HypervisorHandler {
                                             e
                                         )
                                     })?;
+                                // This apparently-useless lock is
+                                // needed to ensure the host does not
+                                // make unsynchronized accesses while
+                                // the guest is executing.  See the
+                                // documentation for
+                                // GuestSharedMemory::lock.
                                 let mem_lock_guard = evar_lock_guard
                                     .as_mut()
                                     .ok_or_else(|| {

src/hyperlight_host/src/mem/shared_mem.rs

@@ -126,6 +126,15 @@ unsafe impl Send for ExclusiveSharedMemory {}
 pub struct GuestSharedMemory {
     region: Arc<HostMapping>,
     /// The lock that indicates this shared memory is being used by non-Rust code
+    ///
+    /// This lock _must_ be held whenever the guest is executing,
+    /// because it prevents the host from converting its
+    /// HostSharedMemory to an ExclusiveSharedMemory. Since the guest
+    /// may arbitrarily mutate the shared memory, only synchronized
+    /// accesses from Rust should be allowed!
+    ///
+    /// We cannot enforce this in the type system, because the memory
+    /// is mapped in to the VM at VM creation time.
     pub lock: Arc<RwLock<()>>,
 }
 unsafe impl Send for GuestSharedMemory {}