Safer libipt-rs 0.3.0-beta.1 (#10)

* AddrFilter builder()

* Add comments about possibly very unsafe stuff

* Allow casts marked unnecessary by clippy bc platform dependent

* WIP: no references from FFI C pointers

* PtEncoderDecoder trait and EncoderDecoderBuilder

* Updaate tests

* Clippy

* Fix block decoder get image

* Move tests at the bottom

* Safer iscache

* Nuke deref_ptresult_mut

* Restore decoder get config, now: used_builder

* Safer Image

* Tests at the bottom

* Clippy

* Add CHANGELOG.md

* Lints

* Block/Insn decoder `to_owned_image(self) -> Image`

* doc.rs works now

* Remove decoder callback generic

* used_builder for packet decoder

* Fix block_decoder core_bus_ratio

* cfilename use fn instead of repeat code

* Clippy

* into_owned_image

* decoder takes mut ref to image

* decoder takes mut ref to image

* insn decoder takes mut ref to image

* Simpler config flags API

* Fix flags tests

* rename status mod

* Easy const

* Easy const pt2

* Lints

Author: Marcondiro

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+_This changelog documents only changes relevant to users, internal changes might be omitted._
+
+## [0.3.0] 2025/01
+
+### Added
+
+- This [CHANGELOG](./CHANGELOG.md) 🎉
+- Explicit [MSRV](Cargo.toml)
+
+### Changed
+
+- `ConfigBuilder` and `Config` have been replaced by `EncoderDecoderBuilder`
+- Decoders/Encoder `::new()` have been replaced by `EncoderDecoderBuilder.build()`
+- Decoders/Encoder `.get_config()` have been replaced by `.used_builder()`
+- Block/Insn decoders `.image()` now returns `&mut Image` instead of `Result<Image,...>`
+- `Image.copy()` has been replaced by `Image.extend()`
+- `Image.add_cached()` now takes a `Rc<SectionCache>` instead of `&mut SectionCache` to ensure that the cache outlives the `Image`. 
+- Many packet/event types methods now take a `&self` instead of consuming `self`
+
+### Removed
+
+- `From<&mut pt_image> for Image`
+- Decoders/Encoder callback due to [UB issues](https://github.com/sum-catnip/libipt-rs/issues/9) (PRs are welcome)
+
+### Fixed
+
+- Some safety issues: __do not cast raw pointers to references with `ptr.as_mut()` with FFI pointers.__  
+  `as_mut()` [requires](https://doc.rust-lang.org/std/ptr/index.html#pointer-to-reference-conversion) the pointer to be  convertible to a reference.
+  This is not true in many cases for FFI pointers: when creating a mutable reference, the referenced memory must not get accessed (read or written) through any other pointer or reference not derived from this reference.
+  In many cases, we cannot ensure that `libipt` does not access the pointed data internally.
+
+## [0.2.x]
+
+_No changelog provided_

Cargo.toml

@@ -1,16 +1,19 @@
 [package]
 name = "libipt"
-version = "0.2.1-beta.1"
-authors = ["sum_catnip <[email protected]>", "Marcondiro"]
+version = "0.3.0-beta.1"
+authors = ["sum_catnip <[email protected]>", "Marcondiro <[email protected]>"]
 edition = "2021"
 license = "MIT"
 description = "The Intel Processor Trace (Intel PT) Decoder Library is Intel's reference implementation for decoding Intel PT."
+categories = ["development-tools::debugging", "development-tools::profiling"]
 repository = "https://github.com/sum-catnip/libipt-rs"
+keywords = ["IntelPT", "ProcessorTrace", "libipt"]
+rust-version = "1.82.0"
 
 [features]
 libipt_master = ["libipt-sys/libipt_master"]
 
 [dependencies]
-libipt-sys = "0.2.1-beta.1"
+libipt-sys = "0.2.1-beta.3"
 bitflags = "2.4.1"
 num_enum = "0.7.1"

README.md

@@ -22,9 +22,6 @@ Contributions are also appreciated.
 I did my best to provide useful documentation for most of the library.
 If you see any missing or weird documentation feel free to open an issue or pull request.
 
-docs.rs is sadly unable to build the project because of a header file which needs to be copied out of the build dir.
-Ill need to get the sorted out somehow.
-
 # Unit Tests
 - block:   ✔️
 - config:  ✔️

src/asid.rs

@@ -1,5 +1,72 @@
 use libipt_sys::{pt_asid, pt_asid_no_cr3 as NO_CR3, pt_asid_no_vmcs as NO_VMCS};
-use std::mem;
+
+/// An Intel PT address space identifier.
+///
+/// This identifies a particular address space when adding file sections or
+/// when reading memory.
+#[derive(Clone, Copy, Debug)]
+pub struct Asid(pub(crate) pt_asid);
+impl Asid {
+    #[inline]
+    #[must_use]
+    pub fn new(cr3: Option<u64>, vmcs: Option<u64>) -> Self {
+        Asid(pt_asid {
+            size: size_of::<pt_asid>(),
+            cr3: cr3.unwrap_or(NO_CR3),
+            vmcs: vmcs.unwrap_or(NO_VMCS),
+        })
+    }
+
+    /// The CR3 value.
+    #[inline]
+    #[must_use]
+    pub const fn cr3(self) -> Option<u64> {
+        match self.0.cr3 {
+            NO_CR3 => None,
+            x => Some(x),
+        }
+    }
+
+    /// The CR3 value.
+    #[inline]
+    pub fn set_cr3(&mut self, cr3: u64) {
+        self.0.cr3 = cr3;
+    }
+
+    /// The VMCS Base address.
+    #[inline]
+    #[must_use]
+    pub const fn vmcs(self) -> Option<u64> {
+        match self.0.vmcs {
+            NO_VMCS => None,
+            x => Some(x),
+        }
+    }
+
+    /// The VMCS Base address.
+    #[inline]
+    pub fn set_vmcs(&mut self, vmcs: u64) {
+        self.0.vmcs = vmcs;
+    }
+}
+
+impl Default for Asid {
+    fn default() -> Self {
+        Asid::new(None, None)
+    }
+}
+
+impl From<pt_asid> for Asid {
+    fn from(asid: pt_asid) -> Self {
+        Asid(asid)
+    }
+}
+
+impl PartialEq for Asid {
+    fn eq(&self, other: &Self) -> bool {
+        self.cr3() == other.cr3() && self.vmcs() == other.vmcs()
+    }
+}
 
 #[cfg(test)]
 mod test {
@@ -67,68 +134,3 @@ mod test {
         assert_eq!(raw.cr3, NO_CR3);
     }
 }
-
-/// An Intel PT address space identifier.
-///
-/// This identifies a particular address space when adding file sections or
-/// when reading memory.
-#[derive(Clone, Copy, Debug)]
-pub struct Asid(pub(crate) pt_asid);
-impl Asid {
-    #[inline]
-    pub fn new(cr3: Option<u64>, vmcs: Option<u64>) -> Self {
-        Asid(pt_asid {
-            size: mem::size_of::<pt_asid>(),
-            cr3: cr3.unwrap_or(NO_CR3),
-            vmcs: vmcs.unwrap_or(NO_VMCS),
-        })
-    }
-
-    /// The CR3 value.
-    #[inline]
-    pub fn cr3(self) -> Option<u64> {
-        match self.0.cr3 {
-            NO_CR3 => None,
-            x => Some(x),
-        }
-    }
-
-    /// The CR3 value.
-    #[inline]
-    pub fn set_cr3(&mut self, cr3: u64) {
-        self.0.cr3 = cr3
-    }
-
-    /// The VMCS Base address.
-    #[inline]
-    pub fn vmcs(self) -> Option<u64> {
-        match self.0.vmcs {
-            NO_VMCS => None,
-            x => Some(x),
-        }
-    }
-
-    /// The VMCS Base address.
-    #[inline]
-    pub fn set_vmcs(&mut self, vmcs: u64) {
-        self.0.vmcs = vmcs
-    }
-}
-
-impl Default for Asid {
-    fn default() -> Self {
-        Asid::new(None, None)
-    }
-}
-
-impl From<pt_asid> for Asid {
-    fn from(asid: pt_asid) -> Self {
-        Asid(asid)
-    }
-}
-
-impl PartialEq for Asid {
-    fn eq(&self, other: &Self) -> bool {
-        self.cr3() == other.cr3() && self.vmcs() == other.vmcs()
-    }
-}