Safety comments, in code documentation, test for proc maps parsing

Author: gyuheon0h

Cargo.lock

@@ -25,15 +25,17 @@ let mut orig_addr: usize = 0;
 unsafe {
     hook_symbol(c"__assert_fail", my_hook as *const () as usize, &mut orig_addr);
 }
+// Release pairs with the Acquire load in my_hook, ensuring the GOT
+// patches from hook_symbol are visible before the hook reads orig_addr.
 ORIG_FN.store(orig_addr, Ordering::Release);
 ```
 
 ### Multi-symbol registry (heap profiling hooking malloc/free/calloc/realloc)
 
 See [`libdd-profiling-heap-gotter`](../libdd-profiling-heap-gotter) which builds a `SymbolOverrides` registry on top of the primitives exported by this crate.
 
-## Platform support
-
-- **64-bit Linux (glibc)**: Full support.
-- **64-bit Linux (musl)**: Works for dynamically linked symbols. Statically linked symbols have no GOT entries and cannot be patched.
-- **Other platforms**: The crate compiles but exports nothing — all types and functions are `cfg`-gated to `target_os = "linux"`.
+## Support
+This library can be used on ARM64 and AMD64 Linux in processes using glibc or musl runtimes.
+Only symbols that have been dynamically linked can be intercept.
+For instance, if you want to intercept the `malloc` of your C runtime,
+you _cannot_ do so if the application has been statically linked against musl.

datadog-ffe-test-suite/ffe-system-test-data

@@ -218,6 +218,8 @@ impl DynamicInfo {
         if self.relas.is_null() || self.relas_count == 0 {
             &[]
         } else {
+            // SAFETY: same as rels(); from_phdr set relas/relas_count
+            // from DT_RELA/DT_RELASZ of a mapped ELF object.
             unsafe { core::slice::from_raw_parts(self.relas, self.relas_count) }
         }
     }
@@ -227,6 +229,8 @@ impl DynamicInfo {
         if self.jmprels.is_null() || self.jmprels_count == 0 {
             &[]
         } else {
+            // SAFETY: same as rels(); from_phdr set jmprels/jmprels_count
+            // from DT_JMPREL/DT_PLTRELSZ of a mapped ELF object.
             unsafe { core::slice::from_raw_parts(self.jmprels, self.jmprels_count) }
         }
     }
@@ -309,6 +313,14 @@ pub unsafe fn gnu_hash_lookup(info: &DynamicInfo, name: &[u8]) -> Option<Elf64_S
         return None;
     }
 
+    // offset 0: nbuckets     (u32)
+    // offset 1: symbias      (u32)  first symbol index covered by the hash
+    // offset 2: bloom_size   (u32)  number of u64 bloom filter words
+    // offset 3: bloom_shift  (u32)  secondary bloom bit shift
+    // offset 4: bloom[bloom_size]   (u64 each, so bloom_size * 2 u32 words)
+    //           buckets[nbuckets]   (u32 each)
+    //           chains[...]         (u32 each, one per symbol starting at symbias)
+
     let nbuckets = *hashtab;
     let symbias = *hashtab.add(1);
     let bloom_size = *hashtab.add(2);
@@ -474,8 +486,9 @@ pub struct PageProtGuard {
 
 impl PageProtGuard {
     pub fn new() -> Self {
-        // sysconf can return -1 on error; fall back to a conservative
-        // 4 KiB default if the query fails.
+        // SAFETY: sysconf(_SC_PAGESIZE) is safe to call; it
+        // reads a cached kernel value with no side effects. Returns -1
+        // on error; we fall back to 4 KiB in that case.
         let raw = unsafe { sysconf(_SC_PAGESIZE) };
         let page_size = usize::try_from(raw).unwrap_or(4096);
         Self {
@@ -625,4 +638,37 @@ mod tests {
         let r = lookup_symbol("definitely_not_a_real_libc_symbol_xyzzy", 0);
         assert!(r.is_none());
     }
+
+    #[test]
+    #[cfg_attr(miri, ignore)]
+    fn test_read_proc_maps_returns_entries() {
+        let maps = read_proc_maps();
+        // Every running Linux process has at least a few mappings
+        assert!(!maps.is_empty(), "read_proc_maps should return entries");
+
+        for entry in &maps {
+            // Every mapping has a non-zero size.
+            assert!(
+                entry.end > entry.start,
+                "mapping {:#x}-{:#x} has zero or negative size",
+                entry.start,
+                entry.end,
+            );
+            // Prot flags should only contain the bits we parse.
+            let valid_bits = PROT_READ | PROT_WRITE | PROT_EXEC;
+            assert!(
+                entry.prot & !valid_bits == 0,
+                "unexpected prot bits {:#x} in mapping {:#x}-{:#x}",
+                entry.prot,
+                entry.start,
+                entry.end,
+            );
+        }
+
+        // At least one mapping should be readable (the executable itself).
+        assert!(
+            maps.iter().any(|e| e.prot & PROT_READ != 0),
+            "expected at least one readable mapping"
+        );
+    }
 }