From be88155cdf1531c3a770f9bc37f2391175893c04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20M=C3=BCller?= Date: Tue, 17 Oct 2023 09:51:52 -0700 Subject: [PATCH] Improve documentation some more MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This patch improves the documentation a bit more. Signed-off-by: Daniel Müller --- src/normalize/meta.rs | 12 ++++++++++-- src/normalize/mod.rs | 28 ++++++++++++++++++++-------- src/normalize/normalizer.rs | 7 ++++--- src/symbolize/source.rs | 17 ++++++++++++++--- 4 files changed, 48 insertions(+), 16 deletions(-) diff --git a/src/normalize/meta.rs b/src/normalize/meta.rs index 910e9ac1..a4d52b3e 100644 --- a/src/normalize/meta.rs +++ b/src/normalize/meta.rs @@ -7,6 +7,8 @@ type BuildId = Vec; /// Meta information about an APK. /// +/// This type is used in the [`UserMeta::Apk`] variant. +/// /// The corresponding file offset is normalized only to the APK container, not /// any potential internal ELF files. Use the /// [`Apk`][crate::symbolize::Source::Apk] symbolization source in order to @@ -47,6 +49,8 @@ pub struct Apk { /// Meta information about an ELF file (executable, shared object, ...). +/// +/// This type is used in the [`UserMeta::Elf`] variant. #[derive(Clone, Debug, PartialEq)] pub struct Elf { /// The canonical absolute path to the ELF file, including its name. @@ -60,8 +64,12 @@ pub struct Elf { /// Meta information about an address that could not be determined to be -/// belonging to a specific component. Such an address will be reported -/// in non-normalized form (as provided by the user). +/// belonging to a specific component. +/// +/// This type is used in the [`UserMeta::Unknown`] variant. +/// +/// An unknown address will be reported in non-normalized form (i.e., as +/// provided as input by the user). #[derive(Clone, Debug, Default, PartialEq)] pub struct Unknown { /// The struct is non-exhaustive and open to extension. diff --git a/src/normalize/mod.rs b/src/normalize/mod.rs index e30be3b6..f217d6f0 100644 --- a/src/normalize/mod.rs +++ b/src/normalize/mod.rs @@ -1,13 +1,21 @@ //! Functionality for address normalization. //! -//! Address normalization is one step of address symbolization: before an -//! address as captured in a process can be looked up in a file, it needs to be -//! converted into an address as it will be used inside the file. E.g., -//! addresses in a shared object (or any position independent binary) may be -//! relative to that file. When such a shared object is loaded into a process, -//! it is relocated. Normalization removes this relocation information and -//! similar adjustments made by the system (e.g., by address space layout -//! randomization). +//! Address normalization is one step of address symbolization. Typically only +//! used internally, it is also made accessible for users to enable remote +//! symbolization work flows. Remote symbolization refers to performing +//! symbolization on a system other than where the "raw" addresses were +//! originally captured. This is useful when working with embedded or locked +//! down systems, for example, where files necessary to perform the +//! symbolization are not available or not accessible. +//! +//! In such a setting address normalization would happen on the embedded device. +//! The result of this normalization would then be transferred to another one +//! that actually performs the symbolization. +//! +//! The [output][UserOutput] of address normalization is a set of file offsets +//! along with meta data. The meta data is expected to contain sufficient +//! information to identify the symbolization source to use (e.g., the ELF file +//! with symbols) on the symbolizing system. //! //! ```no_run //! use blazesym::normalize::Normalizer; @@ -41,6 +49,10 @@ pub use meta::Unknown; pub use meta::UserMeta; pub use normalizer::Builder; pub use normalizer::Normalizer; +// For reasons unknown, we need to `pub use` this type here or the documentation +// will not resolve links. See https://github.com/rust-lang/rust/issues/116854 +#[doc(hidden)] +pub use normalizer::Output; pub use user::UserOutput; pub(crate) use user::create_apk_elf_path; diff --git a/src/normalize/normalizer.rs b/src/normalize/normalizer.rs index b788fd97..07dda82b 100644 --- a/src/normalize/normalizer.rs +++ b/src/normalize/normalizer.rs @@ -23,7 +23,8 @@ pub struct Output { /// /// 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. + /// used with the [`symbolize::Input::FileOffset`][crate::symbolize::Input::FileOffset] + /// variant. pub outputs: Vec<(u64, usize)>, /// Meta information about the normalized outputs. pub meta: Vec, @@ -89,7 +90,7 @@ impl Normalizer { Builder::default() } - /// Normalize `addresses` belonging to a process. + /// Normalize addresses belonging to a process. /// /// Normalize all `addrs` in a given process. The `addrs` array has /// to be sorted in ascending order or an error will be returned. By @@ -117,7 +118,7 @@ impl Normalizer { } - /// Normalize `addresses` belonging to a process. + /// Normalize addresses belonging to a process. /// /// Normalize all `addrs` in a given process. Contrary to /// [`Normalizer::normalize_user_addrs_sorted`], the provided `addrs` array diff --git a/src/symbolize/source.rs b/src/symbolize/source.rs index 9ca91dde..c377a5a9 100644 --- a/src/symbolize/source.rs +++ b/src/symbolize/source.rs @@ -10,6 +10,8 @@ use super::Symbolizer; /// A single APK file. +/// +/// This type is used in the [`Source::Apk`] variant. #[derive(Clone)] pub struct Apk { /// The path to an APK file. @@ -48,6 +50,8 @@ impl Debug for Apk { /// A single ELF file. +/// +/// This type is used in the [`Source::Elf`] variant. #[derive(Clone)] pub struct Elf { /// The path to an ELF file. @@ -89,7 +93,9 @@ impl Debug for Elf { } -/// Linux Kernel's binary image and a copy of /proc/kallsyms +/// Linux Kernel's binary image and a copy of `/proc/kallsyms`. +/// +/// This type is used in the [`Source::Kernel`] variant. #[derive(Clone, Debug, Default, PartialEq)] pub struct Kernel { /// The path of a kallsyms copy. @@ -121,9 +127,12 @@ impl From for Source<'static> { /// Configuration for process based address symbolization. /// +/// This type is used in the [`Source::Process`] variant. +/// /// The corresponding addresses supplied to [`Symbolizer::symbolize`] are -/// expected to be absolute addresses as valid within the process identified -/// by the [`pid`][Process::pid] member. +/// expected to be absolute addresses +/// ([`Input::AbsAddr`][crate::symbolize::Input::AbsAddr]) as valid within the +/// process identified by the [`pid`][Process::pid] member. #[derive(Clone)] pub struct Process { /// The referenced process' ID. @@ -165,6 +174,8 @@ impl From for Source<'static> { /// Enumeration of supported Gsym sources. +/// +/// This type is used in the [`Source::Gsym`] variant. #[derive(Clone, Debug)] pub enum Gsym<'dat> { /// "Raw" Gsym data.