Start improving docs

Author: Marcondiro

CHANGELOG.md

@@ -16,10 +16,12 @@ _This changelog documents only changes relevant to users, internal changes might
 - 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,...>`
+- Block `raw()` now returns an `Option::<&[u8]>`
 - `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`
 - Some simple methods are now `const`
+- ~~`Class:Error`~~ -> `Class::Unknown`
 
 ### Removed
 

src/block/mod.rs

@@ -12,7 +12,7 @@ pub use decoder::*;
 /// A block of instructions.
 ///
 /// Instructions in this block are executed sequentially but are not necessarily
-/// contiguous in memory.  Users are expected to follow direct branches.
+/// contiguous in memory. Users are expected to follow direct branches.
 #[derive(Debug, Clone, Copy)]
 #[repr(transparent)]
 pub struct Block(pub(super) pt_block);
@@ -31,6 +31,7 @@ impl Block {
         self.0.end_ip
     }
 
+    // TODO: make this more rusty? at least with an Option? &Image?
     /// The image section that contains the instructions in this block.
     ///
     /// A value of zero means that the section did not have an identifier.
@@ -50,7 +51,7 @@ impl Block {
 
     /// The instruction class for the last instruction in this block.
     ///
-    /// This field may be set to `Class::Error` to indicate that the instruction
+    /// This field may be set to `Class::Unknown` to indicate that the instruction
     /// class is not available. The block decoder may choose to not provide
     /// the instruction class in some cases for performance reasons.
     #[must_use]
@@ -68,31 +69,29 @@ impl Block {
     /// The raw bytes of the last instruction in this block in case the
     /// instruction does not fit entirely into this block's section.
     ///
-    /// This field is only valid if truncated is set.
+    /// This field is `Some`only if `truncated()` is true.
     #[must_use]
-    pub fn raw(&self) -> &[u8] {
-        &self.0.raw[..self.0.size as usize]
+    pub fn raw(&self) -> Option<&[u8]> {
+        if self.truncated() {
+            Some(&self.0.raw[..self.0.size as usize])
+        } else {
+            None
+        }
     }
 
-    /// A collection of flags giving additional information about the
-    /// instructions in this block.
-    ///
-    /// - all instructions in this block were executed speculatively.
+    /// All instructions in this block were executed speculatively.
     #[must_use]
     pub fn speculative(&self) -> bool {
         self.0.speculative() > 0
     }
 
-    /// A collection of flags giving additional information about the
-    /// instructions in this block.
-    ///
-    /// - the last instruction in this block is truncated.
+    /// The last instruction in this block is truncated.
     ///
     /// It starts in this block's section but continues in one or more
     /// other sections depending on how fragmented the memory image is.
     ///
-    /// The raw bytes for the last instruction are provided in \@raw and
-    /// its size in \@size in this case.
+    /// The raw bytes for the last instruction are provided in @raw and
+    /// its size in @size in this case.
     #[must_use]
     pub fn truncated(&self) -> bool {
         self.0.truncated() > 0
@@ -125,9 +124,9 @@ mod test {
         assert_eq!(blk.end_ip(), 2);
         assert_eq!(blk.isid(), 3);
         assert_eq!(blk.mode(), ExecModeType::Bit32);
-        assert_eq!(blk.class(), Class::Error);
+        assert_eq!(blk.class(), Class::Unknown);
         assert_eq!(blk.ninsn(), 4);
-        assert_eq!(blk.raw(), &data[..8]);
+        assert_eq!(blk.raw(), Some(&data[..8]));
         assert!(blk.truncated());
         assert!(!blk.speculative());
     }
@@ -153,9 +152,9 @@ mod test {
         assert_eq!(blk.end_ip(), 2);
         assert_eq!(blk.isid(), 3);
         assert_eq!(blk.mode(), ExecModeType::Bit32);
-        assert_eq!(blk.class(), Class::Error);
+        assert_eq!(blk.class(), Class::Unknown);
         assert_eq!(blk.ninsn(), 4);
-        assert!(blk.raw().len() > 0);
+        assert!(blk.raw().is_none());
         assert!(!blk.truncated());
         assert!(!blk.speculative());
     }

src/insn/class.rs

@@ -2,10 +2,10 @@
 #![allow(clippy::unnecessary_cast)]
 
 use libipt_sys::{
-    pt_insn_class_ptic_call, pt_insn_class_ptic_cond_jump, pt_insn_class_ptic_error,
-    pt_insn_class_ptic_far_call, pt_insn_class_ptic_far_jump, pt_insn_class_ptic_far_return,
-    pt_insn_class_ptic_jump, pt_insn_class_ptic_other, pt_insn_class_ptic_ptwrite,
-    pt_insn_class_ptic_return,
+    pt_insn_class_ptic_call, pt_insn_class_ptic_cond_jump, pt_insn_class_ptic_far_call,
+    pt_insn_class_ptic_far_jump, pt_insn_class_ptic_far_return, pt_insn_class_ptic_jump,
+    pt_insn_class_ptic_other, pt_insn_class_ptic_ptwrite, pt_insn_class_ptic_return,
+    pt_insn_class_ptic_unknown,
 };
 use num_enum::TryFromPrimitive;
 
@@ -21,7 +21,7 @@ pub enum Class {
     /// The instruction is a near conditional jump.
     CondJump = pt_insn_class_ptic_cond_jump as u32,
     /// The instruction could not be classified.
-    Error = pt_insn_class_ptic_error as u32,
+    Unknown = pt_insn_class_ptic_unknown as u32,
     /// The instruction is a call-like far transfer.
     /// E.g. SYSCALL, SYSENTER, or FAR CALL.
     FarCall = pt_insn_class_ptic_far_call as u32,

src/lib.rs

@@ -1,44 +1,40 @@
 #![warn(clippy::all, clippy::cargo)]
 
-/// The pt_config structure defines an Intel Processor Trace (Intel PT) encoder or decoder configuration.
-///
-/// It is required for allocating a trace packet encoder (see pt_alloc_encoder(3)),
-/// a trace packet decoder (see pt_pkt_alloc_decoder(3)),
-/// a query decoder (see pt_qry_alloc_decoder(3)),
-/// or an instruction flow decoder (see pt_insn_alloc_decoder(3)).
+/// Intel Processor Trace (Intel PT) encoder or decoder configuration.
 pub mod enc_dec_builder;
 
-/// The library uses a single error enum for all layers.
+/// Unique error enum used across the library.
 ///
-/// Not all errors may occur on every layer.
-/// Every API function specifies the errors it may return. (not accurate!)
+/// Not all errors may occur in every module's function.
+/// Every API function specifies the errors it may return (sometimes not exhaustively!).
 pub mod error;
 
-/// This layer deals with Intel PT packet encoding and decoding.
-///
-/// It can further be split into three sub-layers: opcodes, encoding, and decoding.
+/// Intel PT packet encoding and decoding.
 pub mod packet;
 
-/// The event layer deals with packet combinations that encode higher-level events.
+/// Higher-level events often resulting from the combination of different PT packets.
 ///
 /// It is used for reconstructing execution flow for users who need finer-grain control not available via the instruction flow layer
 /// or for users who want to integrate execution flow reconstruction with other functionality more tightly than it would be possible otherwise.
 pub mod event;
 
-/// The block layer provides a simple API for iterating over blocks of sequential instructions in execution order.
+/// Simple API for iterating over blocks of sequential instructions in execution order.
 ///
 /// The instructions in a block are sequential in the sense that no trace is required for reconstructing the instructions.
 /// The IP of the first instruction is given in struct `Block` and the IP of other instructions in the block can be determined by decoding and examining the previous instruction.
 pub mod block;
 
-/// The instruction flow layer provides a simple API for iterating over instructions in execution order.
+/// Simple API for iterating over instructions in execution order.
 pub mod insn;
 
 mod version;
 pub use version::Version;
 
+/// Module handling the memory images of the binaries beeing traced, used in high level decoding.
 pub mod image;
 
+/// Address Space Identifier
 pub mod asid;
 
+/// Info about the decoder status
 pub mod status;

src/version.rs

@@ -1,7 +1,7 @@
 use libipt_sys::{pt_library_version, pt_version};
 use std::ffi::CStr;
 
-/// The library version.
+/// The underlying C library (libipt) version.
 #[derive(Clone, Copy, Debug)]
 #[repr(transparent)]
 pub struct Version(pt_version);