Add more comments

Author: tiif

src/shims/unix/linux/eventfd.rs

@@ -1,5 +1,4 @@
 //! Linux `eventfd` implementation.
-//! Currently just a stub.
 use std::io;
 use std::io::{Error, ErrorKind};
 
@@ -41,7 +40,7 @@ impl FileDescription for Event {
         Ok(Ok(()))
     }
 
-    /// Read the counter in the buffer and return the counter if succeed.
+    /// Read the counter in the buffer and return the counter if succeeded.
     fn read<'tcx>(
         &mut self,
         _communicate_allowed: bool,
@@ -52,6 +51,7 @@ impl FileDescription for Event {
         let Some(bytes) = bytes.first_chunk_mut::<8>() else {
             return Ok(Err(Error::from(ErrorKind::InvalidInput)));
         };
+        // Block when counter == 0.
         if self.counter == 0 {
             if self.is_nonblock {
                 return Ok(Err(Error::from(ErrorKind::WouldBlock)));
@@ -94,7 +94,7 @@ impl FileDescription for Event {
         let Some(bytes) = bytes.first_chunk::<8>() else {
             return Ok(Err(Error::from(ErrorKind::InvalidInput)));
         };
-        // Convert from target endianness to host endianness.
+        // Convert from bytes to int according to host endianness.
         let num = match ecx.tcx.sess.target.endian {
             Endian::Little => u64::from_le_bytes(*bytes),
             Endian::Big => u64::from_be_bytes(*bytes),
@@ -103,6 +103,8 @@ impl FileDescription for Event {
         if num == u64::MAX {
             return Ok(Err(Error::from(ErrorKind::InvalidInput)));
         }
+        // If the addition does not let the counter to exceed the maximum value, update the counter.
+        // Else, block.
         match self.counter.checked_add(num) {
             Some(new_count @ 0..=MAX_COUNTER) => {
                 // Prevent false alarm in data race detection when doing synchronisation via eventfd.
@@ -166,7 +168,7 @@ pub trait EvalContextExt<'tcx>: crate::MiriInterpCxExt<'tcx> {
             flags &= !efd_nonblock;
             is_nonblock = true;
         }
-        // After unloading, if flags != 0, that means other flags are used.
+        // After unloading, flags != 0 means other flags are used.
         if flags != 0 {
             let einval = this.eval_libc("EINVAL");
             this.set_last_error(einval)?;

tests/pass-dep/libc/libc-eventfd.rs

@@ -15,10 +15,10 @@ fn test_read_write() {
     let fd = unsafe { libc::eventfd(0, flags) };
     let sized_8_data: [u8; 8];
     if cfg!(target_endian = "big") {
-        // Adjust the data based on the endianess of host system.
-        sized_8_data = [0, 0, 0, 0, 0, 0, 0, 1];
+        // Adjust the data based on the endianness of host system.
+        sized_8_data = 1_i64.to_be_bytes();
     } else {
-        sized_8_data = [1, 0, 0, 0, 0, 0, 0, 0];
+        sized_8_data = 1_i64.to_le_bytes();
     }
     // Write 1 to the counter.
     let res: i64 = unsafe {
@@ -33,6 +33,7 @@ fn test_read_write() {
     };
     // Read returns number of bytes has been read, which is always 8.
     assert_eq!(res, 8);
+    // Check the value of counter read.
     let counter: u64;
     if cfg!(target_endian = "big") {
         // Read will store the bytes based on the endianess of the host system.
@@ -42,47 +43,43 @@ fn test_read_write() {
     }
     assert_eq!(counter, 1);
 
-    // Read when counter == 0 should fail.
+    // After read, the counter is currently 0, read counter 0 should fail with return
+    // value -1.
     let mut buf: [u8; 8] = [0; 8];
     let res: i32 = unsafe {
         libc::read(fd, buf.as_mut_ptr().cast(), buf.len() as libc::size_t).try_into().unwrap()
     };
-    // Read returns number of bytes has been read, which is always 8.
     assert_eq!(res, -1);
 
-    // Write with buffer size > 8 bytes.
+    // Write with supplied buffer that > 8 bytes should be allowed.
+    let sized_9_data: [u8; 9];
+    if cfg!(target_endian = "big") {
+        // Adjust the data based on the endianess of host system.
+        sized_9_data = [0, 0, 0, 0, 0, 0, 0, 0, 1];
+    } else {
+        sized_9_data = [1, 0, 0, 0, 0, 0, 0, 0, 0];
+    }
     let res: i64 = unsafe {
-        libc::write(fd, sized_8_data.as_ptr() as *const libc::c_void, 8).try_into().unwrap()
+        libc::write(fd, sized_9_data.as_ptr() as *const libc::c_void, 8).try_into().unwrap()
     };
     assert_eq!(res, 8);
 
-    // Read with supplied buffer that < 8 bytes.
+    // Read with supplied buffer that < 8 bytes should fail with return
+    // value -1.
     let mut buf: [u8; 7] = [1; 7];
     let res: i32 = unsafe {
         libc::read(fd, buf.as_mut_ptr().cast(), buf.len() as libc::size_t).try_into().unwrap()
     };
     assert_eq!(res, -1);
 
-    // Write with supplied buffer that < 8 bytes
+    // Write with supplied buffer that < 8 bytes should fail with return
+    // value -1.
     let res: i64 = unsafe {
         libc::write(fd, sized_8_data[0..7].as_ptr() as *const libc::c_void, 7).try_into().unwrap()
     };
     assert_eq!(res, -1);
 
-    // Write with supplied buffer that > 8 bytes
-    let sized_9_data: [u8; 9];
-    if cfg!(target_endian = "big") {
-        // Adjust the data based on the endianess of host system.
-        sized_9_data = [0, 0, 0, 0, 0, 0, 0, 0, 1];
-    } else {
-        sized_9_data = [1, 0, 0, 0, 0, 0, 0, 0, 0];
-    }
-    let res: i64 = unsafe {
-        libc::write(fd, sized_9_data.as_ptr() as *const libc::c_void, 8).try_into().unwrap()
-    };
-    assert_eq!(res, 8);
-
-    // Read with supplied buffer > 8 bytes.
+    // Read with supplied buffer > 8 bytes should be allowed.
     let mut buf: [u8; 9] = [1; 9];
     let res: i32 = unsafe {
         libc::read(fd, buf.as_mut_ptr().cast(), buf.len() as libc::size_t).try_into().unwrap()