Continue

include/blazesym.h

@@ -201,25 +201,25 @@ typedef struct blaze_user_addr_meta {
 } blaze_user_addr_meta;
 
 /**
- * A normalized address along with an index into the associated
- * [`blaze_user_addr_meta`] array (such as
+ * A file offset or non-normalized address along with an index into the
+ * associated [`blaze_user_addr_meta`] array (such as
  * [`blaze_normalized_user_addrs::metas`]).
  */
-typedef struct blaze_normalized_addr {
+typedef struct blaze_normalized_output {
   /**
-   * The normalized address.
+   * The file offset or non-normalized address.
    */
-  uintptr_t addr;
+  uint64_t output;
   /**
    * The index into the associated [`blaze_user_addr_meta`] array.
    */
   size_t meta_idx;
-} blaze_normalized_addr;
+} blaze_normalized_output;
 
 /**
  * An object representing normalized user addresses.
  *
- * C ABI compatible version of [`NormalizedUserAddrs`].
+ * C ABI compatible version of [`UserOutput`].
  */
 typedef struct blaze_normalized_user_addrs {
   /**
@@ -231,13 +231,13 @@ typedef struct blaze_normalized_user_addrs {
    */
   struct blaze_user_addr_meta *metas;
   /**
-   * The number of [`blaze_normalized_addr`] objects present in `addrs`.
+   * The number of [`blaze_normalized_output`] objects present in `outputs`.
    */
-  size_t addr_cnt;
+  size_t output_cnt;
   /**
    * An array of `addr_cnt` objects.
    */
-  struct blaze_normalized_addr *addrs;
+  struct blaze_normalized_output *outputs;
 } blaze_normalized_user_addrs;
 
 /**

src/c_api/normalize.rs

@@ -13,7 +13,7 @@ use std::slice;
 use crate::log::error;
 use crate::normalize::ApkElf;
 use crate::normalize::Elf;
-use crate::normalize::NormalizedUserAddrs;
+use crate::normalize::UserOutput;
 use crate::normalize::Normalizer;
 use crate::normalize::Unknown;
 use crate::normalize::UserAddrMeta;
@@ -51,21 +51,21 @@ pub unsafe extern "C" fn blaze_normalizer_free(normalizer: *mut Normalizer) {
 }
 
 
-/// A normalized address along with an index into the associated
-/// [`blaze_user_addr_meta`] array (such as
+/// A file offset or non-normalized address along with an index into the
+/// associated [`blaze_user_addr_meta`] array (such as
 /// [`blaze_normalized_user_addrs::metas`]).
 #[repr(C)]
 #[derive(Debug)]
-pub struct blaze_normalized_addr {
-    /// The normalized address.
-    pub addr: Addr,
+pub struct blaze_normalized_output {
+    /// The file offset or non-normalized address.
+    pub output: u64,
     /// The index into the associated [`blaze_user_addr_meta`] array.
     pub meta_idx: usize,
 }
 
-impl From<(Addr, usize)> for blaze_normalized_addr {
-    fn from((addr, meta_idx): (Addr, usize)) -> Self {
-        Self { addr, meta_idx }
+impl From<(u64, usize)> for blaze_normalized_output {
+    fn from((output, meta_idx): (u64, usize)) -> Self {
+        Self { output, meta_idx }
     }
 }
 
@@ -329,22 +329,22 @@ impl From<blaze_user_addr_meta> for UserAddrMeta {
 
 /// An object representing normalized user addresses.
 ///
-/// C ABI compatible version of [`NormalizedUserAddrs`].
+/// C ABI compatible version of [`UserOutput`].
 #[repr(C)]
 #[derive(Debug)]
 pub struct blaze_normalized_user_addrs {
     /// The number of [`blaze_user_addr_meta`] objects present in `metas`.
     pub meta_cnt: usize,
     /// An array of `meta_cnt` objects.
     pub metas: *mut blaze_user_addr_meta,
-    /// The number of [`blaze_normalized_addr`] objects present in `addrs`.
-    pub addr_cnt: usize,
+    /// The number of [`blaze_normalized_output`] objects present in `outputs`.
+    pub output_cnt: usize,
     /// An array of `addr_cnt` objects.
-    pub addrs: *mut blaze_normalized_addr,
+    pub outputs: *mut blaze_normalized_output,
 }
 
-impl From<NormalizedUserAddrs> for blaze_normalized_user_addrs {
-    fn from(other: NormalizedUserAddrs) -> Self {
+impl From<UserOutput> for blaze_normalized_user_addrs {
+    fn from(other: UserOutput) -> Self {
         Self {
             meta_cnt: other.meta.len(),
             metas: unsafe {
@@ -360,13 +360,13 @@ impl From<NormalizedUserAddrs> for blaze_normalized_user_addrs {
                 .unwrap()
                 .as_mut_ptr()
             },
-            addr_cnt: other.addrs.len(),
-            addrs: unsafe {
+            output_cnt: other.outputs.len(),
+            outputs: unsafe {
                 Box::into_raw(
                     other
-                        .addrs
+                        .outputs
                         .into_iter()
-                        .map(blaze_normalized_addr::from)
+                        .map(blaze_normalized_output::from)
                         .collect::<Vec<_>>()
                         .into_boxed_slice(),
                 )
@@ -482,9 +482,9 @@ pub unsafe extern "C" fn blaze_user_addrs_free(addrs: *mut blaze_normalized_user
     }
     .into_vec();
     let _norm_addrs = unsafe {
-        Box::<[blaze_normalized_addr]>::from_raw(slice::from_raw_parts_mut(
-            user_addrs.addrs,
-            user_addrs.addr_cnt,
+        Box::<[blaze_normalized_output]>::from_raw(slice::from_raw_parts_mut(
+            user_addrs.outputs,
+            user_addrs.output_cnt,
         ))
     }
     .into_vec();
@@ -503,13 +503,13 @@ mod tests {
     /// Exercise the `Debug` representation of various types.
     #[test]
     fn debug_repr() {
-        let norm_addr = blaze_normalized_addr {
-            addr: 0x1337,
+        let output = blaze_normalized_output {
+            output: 0x1337,
             meta_idx: 1,
         };
         assert_eq!(
-            format!("{norm_addr:?}"),
-            "blaze_normalized_addr { addr: 4919, meta_idx: 1 }"
+            format!("{output:?}"),
+            "blaze_normalized_output { output: 4919, meta_idx: 1 }"
         );
 
         let meta_kind = blaze_user_addr_meta_kind::BLAZE_USER_ADDR_APK_ELF;
@@ -556,12 +556,12 @@ mod tests {
         let user_addrs = blaze_normalized_user_addrs {
             meta_cnt: 0,
             metas: ptr::null_mut(),
-            addr_cnt: 0,
-            addrs: ptr::null_mut(),
+            output_cnt: 0,
+            outputs: ptr::null_mut(),
         };
         assert_eq!(
             format!("{user_addrs:?}"),
-            "blaze_normalized_user_addrs { meta_cnt: 0, metas: 0x0, addr_cnt: 0, addrs: 0x0 }",
+            "blaze_normalized_user_addrs { meta_cnt: 0, metas: 0x0, output_cnt: 0, outputs: 0x0 }",
         );
     }
 

src/normalize/meta.rs

@@ -21,7 +21,7 @@ type BuildId = Vec<u8>;
 /// let normalized = normalizer
 ///     .normalize_user_addrs_sorted([addr_in_elf_in_apk].as_slice(), Pid::Slf)
 ///     .unwrap();
-/// let (norm_addr, meta_idx) = normalized.addrs[0];
+/// let (file_offset, meta_idx) = normalized.outputs[0];
 /// let meta = &normalized.meta[meta_idx];
 /// let apk_elf = meta.apk_elf().unwrap();
 ///
@@ -32,7 +32,7 @@ type BuildId = Vec<u8>;
 /// let src = symbolize::Source::from(symbolize::Elf::new(elf_path));
 /// let symbolizer = symbolize::Symbolizer::new();
 /// let sym = symbolizer
-///   .symbolize_single(&src, symbolize::Input::VirtOffset(norm_addr))
+///   .symbolize_single(&src, symbolize::Input::FileOffset(file_offset))
 ///   .unwrap()
 ///   .into_sym()
 ///   .unwrap();

src/normalize/mod.rs

@@ -19,13 +19,13 @@
 //! let addrs = [fopen_addr];
 //! let pid = Pid::Slf;
 //! let normalized = normalizer.normalize_user_addrs(&addrs, pid).unwrap();
-//! assert_eq!(normalized.addrs.len(), 1);
+//! assert_eq!(normalized.outputs.len(), 1);
 //!
-//! let (addr, meta_idx) = normalized.addrs[0];
-//! // fopen (0x7f5f8e23a790) corresponds to address 0x77790 within
+//! let (file_offset, meta_idx) = normalized.outputs[0];
+//! // fopen (0x7f5f8e23a790) corresponds to file offset 0x77790 within
 //! // Elf(Elf { path: "/usr/lib64/libc.so.6", build_id: Some([...]), ... })
 //! println!(
-//!   "fopen ({fopen_addr:#x}) corresponds to address {addr:#x} within {:?}",
+//!   "fopen ({fopen_addr:#x}) corresponds to file offset {file_offset:#x} within {:?}",
 //!   normalized.meta[meta_idx]
 //! );
 //! ```
@@ -41,7 +41,7 @@ pub use meta::Unknown;
 pub use meta::UserAddrMeta;
 pub use normalizer::Builder;
 pub use normalizer::Normalizer;
-pub use user::NormalizedUserAddrs;
+pub use user::UserOutput;
 
 pub(crate) use user::create_apk_elf_path;
 pub(crate) use user::normalize_apk_addr;

src/normalize/normalizer.rs

@@ -4,23 +4,24 @@ use crate::Pid;
 use crate::Result;
 
 use super::user::normalize_user_addrs_sorted_impl;
-use super::user::NormalizedUserAddrs;
+use super::user::UserOutput;
 
 
-/// A type capturing normalized addresses along with captured meta data.
+/// A type capturing normalized outputs along with captured meta data.
 ///
 /// This type enables "remote" symbolization. That is to say, it represents the
 /// input necessary for addresses to be symbolized on a system other than where
 /// they were recorded.
 #[derive(Clone, Debug)]
-pub struct NormalizedAddrs<M> {
-    /// Normalized addresses along with an index into `meta` for retrieval of
-    /// the corresponding [`AddrMeta`] information.
+pub struct FileOffsets<M> {
+    /// File offsets or non-normalized addresses along with an index into `meta`
+    /// for retrieval of the corresponding [`AddrMeta`] information.
     ///
-    /// A normalized address is one as it would appear in a binary or debug
-    /// symbol file, i.e., one excluding any relocations.
-    pub addrs: Vec<(Addr, usize)>,
-    /// Meta information about the normalized addresses.
+    /// A file offset is one as it would appear in a binary or debug symbol
+    /// file, i.e., one excluding any relocations. The data reported here can be
+    /// used with the [`symbolize::Input::FileOffset`] variant.
+    pub outputs: Vec<(u64, usize)>,
+    /// Meta information about the normalized outputs.
     pub meta: Vec<M>,
 }
 
@@ -95,7 +96,7 @@ impl Normalizer {
     ///
     /// Unknown addresses are not normalized. They are reported as
     /// [`Unknown`][crate::normalize::Unknown] meta entries in the
-    /// returned [`NormalizedUserAddrs`] object. The cause of an address
+    /// returned [`UserOutput`] object. The cause of an address
     /// to be unknown (and, hence, not normalized), could have a few
     /// reasons, including, but not limited to:
     /// - user error (if a bogus address was provided)
@@ -111,7 +112,7 @@ impl Normalizer {
         &self,
         addrs: &[Addr],
         pid: Pid,
-    ) -> Result<NormalizedUserAddrs> {
+    ) -> Result<UserOutput> {
         normalize_user_addrs_sorted_impl(addrs.iter().copied(), pid, self.build_ids)
     }
 
@@ -125,10 +126,10 @@ impl Normalizer {
     /// [`Normalizer::normalize_user_addrs_sorted`] instead will result in
     /// slightly faster normalization.
     #[cfg_attr(feature = "tracing", crate::log::instrument(skip(self)))]
-    pub fn normalize_user_addrs(&self, addrs: &[Addr], pid: Pid) -> Result<NormalizedUserAddrs> {
+    pub fn normalize_user_addrs(&self, addrs: &[Addr], pid: Pid) -> Result<UserOutput> {
         util::with_ordered_elems(
             addrs,
-            |normalized: &mut NormalizedUserAddrs| normalized.addrs.as_mut_slice(),
+            |normalized: &mut UserOutput| normalized.outputs.as_mut_slice(),
             |sorted_addrs| normalize_user_addrs_sorted_impl(sorted_addrs, pid, self.build_ids),
         )
     }
@@ -186,11 +187,11 @@ mod tests {
         let normalized = normalizer
             .normalize_user_addrs_sorted(addrs.as_slice(), Pid::Slf)
             .unwrap();
-        assert_eq!(normalized.addrs.len(), 2);
+        assert_eq!(normalized.outputs.len(), 2);
         assert_eq!(normalized.meta.len(), 1);
         assert_eq!(normalized.meta[0], Unknown::default().into());
-        assert_eq!(normalized.addrs[0].1, 0);
-        assert_eq!(normalized.addrs[1].1, 0);
+        assert_eq!(normalized.outputs[0].1, 0);
+        assert_eq!(normalized.outputs[1].1, 0);
     }
 
     /// Check that we can normalize user addresses.
@@ -215,13 +216,13 @@ mod tests {
         let normalized = normalizer
             .normalize_user_addrs(addrs.as_slice(), Pid::Slf)
             .unwrap();
-        assert_eq!(normalized.addrs.len(), 6);
+        assert_eq!(normalized.outputs.len(), 6);
 
-        let addrs = &normalized.addrs;
+        let outputs = &normalized.outputs;
         let meta = &normalized.meta;
         assert_eq!(meta.len(), 2);
 
-        let errno_meta_idx = addrs[errno_idx].1;
+        let errno_meta_idx = outputs[errno_idx].1;
         assert!(meta[errno_meta_idx]
             .elf()
             .unwrap()
@@ -264,12 +265,12 @@ mod tests {
         let normalized = normalizer
             .normalize_user_addrs_sorted([the_answer_addr as Addr].as_slice(), Pid::Slf)
             .unwrap();
-        assert_eq!(normalized.addrs.len(), 1);
+        assert_eq!(normalized.outputs.len(), 1);
         assert_eq!(normalized.meta.len(), 1);
 
-        let norm_addr = normalized.addrs[0];
-        assert_eq!(norm_addr.0, sym.addr);
-        let meta = &normalized.meta[norm_addr.1];
+        let output = normalized.outputs[0];
+        assert_eq!(output.0, sym.addr);
+        let meta = &normalized.meta[output.1];
         let so_path = Path::new(&env!("CARGO_MANIFEST_DIR"))
             .join("data")
             .join("libtest-so.so");
@@ -328,12 +329,12 @@ mod tests {
             let normalized = normalizer
                 .normalize_user_addrs_sorted([the_answer_addr as Addr].as_slice(), Pid::Slf)
                 .unwrap();
-            assert_eq!(normalized.addrs.len(), 1);
+            assert_eq!(normalized.outputs.len(), 1);
             assert_eq!(normalized.meta.len(), 1);
 
-            let norm_addr = normalized.addrs[0];
-            assert_eq!(norm_addr.0, sym.addr);
-            let meta = &normalized.meta[norm_addr.1];
+            let output = normalized.outputs[0];
+            assert_eq!(output.0, sym.addr);
+            let meta = &normalized.meta[output.1];
             let so_path = Path::new(&env!("CARGO_MANIFEST_DIR"))
                 .join("data")
                 .join(so_name);