extra comments and cleanup

Author: LorrensP-2158466

src/shims/unix/freebsd/sync.rs

@@ -66,13 +66,15 @@ pub trait EvalContextExt<'tcx>: crate::MiriInterpCxExt<'tcx> {
                     if op == wait { this.machine.layouts.isize } else { this.machine.layouts.u32 };
                 let obj = this.ptr_to_mplace(obj, obj_layout);
 
-                // Read the Linux futex implementation in Miri to understand why this fence is needed.
+                // Read the Linux futex wait implementation in Miri to understand why this fence is needed.
                 this.atomic_fence(AtomicFenceOrd::SeqCst)?;
                 let obj_val = this
                     .read_scalar_atomic(&obj, AtomicReadOrd::Acquire)?
                     .to_bits(obj_layout.size)?; // isize and u32 can have different sizes
 
                 if obj_val == u128::from(val) {
+                    // This cannot fail since we already did an atomic acquire read on that pointer.
+                    // Acquire reads are only allowed on mutable memory.
                     let futex_ref = this
                         .get_sync_or_init(obj.ptr(), |_| FreeBsdFutex { futex: Default::default() })
                         .unwrap()
@@ -122,7 +124,8 @@ pub trait EvalContextExt<'tcx>: crate::MiriInterpCxExt<'tcx> {
                             };
 
                             // From the FreeBSD source code:
-                            // In the function `umtx_copyin_umtx_time` in kern_umtx.c, _clock_id is set to CLOCK_REALTIME when using `timespec`
+                            // In the function `umtx_copyin_umtx_time` in kern_umtx.c,
+                            // _clock_id is set to CLOCK_REALTIME when using a `timespec` timeout.
                             Some((TimeoutClock::RealTime, TimeoutAnchor::Relative, duration))
                         } else {
                             return this.set_last_error_and_return(LibcError("EINVAL"), dest);
@@ -177,7 +180,7 @@ pub trait EvalContextExt<'tcx>: crate::MiriInterpCxExt<'tcx> {
                 // Saturating cast for when usize is smaller than u64.
                 let count = usize::try_from(val).unwrap_or(usize::MAX);
 
-                // Read the Linux futex implementation in Miri to understand why this fence is needed.
+                // Read the Linux futex wake implementation in Miri to understand why this fence is needed.
                 this.atomic_fence(AtomicFenceOrd::SeqCst)?;
 
                 // `_umtx_op` doesn't return the amount of woken threads.