Image::add_files_cached() API to simplify the creation of a cached image

Author: Marcondiro

CHANGELOG.md

@@ -8,6 +8,7 @@ _This changelog documents only changes relevant to users, internal changes might
 
 - This [CHANGELOG](./CHANGELOG.md) 🎉
 - Explicit [MSRV](Cargo.toml)
+- New `Image::add_files_cached()` API to simplify the creation of a cached image for simple use cases.
 
 ### Changed
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libipt"
-version = "0.3.0-beta.2"
+version = "0.3.0-beta.3"
 authors = [
   "sum_catnip <catnip@catnip.fyi>",
   "Marcondiro <cavenatimarco+libiptrs@gmail.com>",
@@ -17,6 +17,6 @@ rust-version = "1.82.0"
 libipt_master = ["libipt-sys/libipt_master"]
 
 [dependencies]
-libipt-sys = { version = "0.2.1-beta.3", git = "https://github.com/sum-catnip/libipt-sys.git" }
+libipt-sys = { version = "0.2.1", git = "https://github.com/sum-catnip/libipt-sys.git" }
 bitflags = "2.4.1"
 num_enum = "0.7.1"

src/image/mod.rs

@@ -97,6 +97,19 @@ impl Drop for BoxedCallback {
     }
 }
 
+/// Info of a binary's section that can be used to populate an `Image`
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SectionInfo {
+    /// Path of the binary
+    pub filename: String,
+    /// Offset of the section in the file
+    pub offset: u64,
+    /// Size of the section
+    pub size: u64,
+    /// Start virtual address of the section once loaded in memory
+    pub virtual_address: u64,
+}
+
 /// An Image defines the memory image that was traced as a collection
 /// of file sections and the virtual addresses at which those sections were loaded.
 #[derive(Debug)]
@@ -109,7 +122,7 @@ pub struct Image {
     callback: Option<BoxedCallback>,
     caches: Vec<Rc<SectionCache>>,
     // `HashSet` might grow and move the content around, we cannot use `Asid` directly since we
-    // share a pointer with libipt and it must be valid for the entire Image (section) filetime.
+    // share a pointer with libipt, and it must be valid for the entire Image (section) lifetime.
     asids: HashSet<Rc<Asid>>,
 }
 
@@ -321,6 +334,31 @@ impl Image {
         })?;
         Ok(())
     }
+
+    /// Add multiple file sections to the traced memory image, backed by a cache.
+    ///
+    /// This is the same as creating a `SectionCache` and subsequently calling `add_cached()` for
+    /// each section.
+    pub fn add_files_cached(
+        &mut self,
+        sections_info: &[SectionInfo],
+        asid: Option<&Asid>,
+    ) -> Result<(), PtError> {
+        let mut image_cache = SectionCache::new(None)?;
+
+        let mut isids = Vec::with_capacity(sections_info.len());
+        for s in sections_info {
+            let isid = image_cache.add_file(&s.filename, s.offset, s.size, s.virtual_address)?;
+            isids.push(isid);
+        }
+
+        let rc_cache = Rc::new(image_cache);
+        for isid in isids {
+            self.add_cached(rc_cache.clone(), isid, asid)?;
+        }
+
+        Ok(())
+    }
 }
 
 impl Drop for Image {
@@ -511,4 +549,22 @@ mod test {
             assert_eq!(img.remove_by_asid(&Asid::new(Some(i), Some(i))).unwrap(), 1);
         }
     }
+
+    #[test]
+    fn img_add_files_cached() {
+        let file: PathBuf = [env!("CARGO_MANIFEST_DIR"), "testfiles", "garbage.txt"]
+            .iter()
+            .collect();
+
+        let section = SectionInfo {
+            filename: file.to_string_lossy().to_string(),
+            offset: 5,
+            size: 15,
+            virtual_address: 0x1337,
+        };
+        let mut i = img_with_file();
+        let asid = Asid::new(Some(3), Some(4));
+        i.add_files_cached(&[section], Some(&asid)).unwrap();
+        assert_eq!(i.remove_by_asid(&asid).unwrap(), 1);
+    }
 }