rtic-scope: finalize documentation

cargo-rtic-scope/src/build.rs

@@ -1,4 +1,4 @@
-//! Handle artifact building using cargo.
+//! Artifact building using a wrapper around a cargo sub-process call.
 use crate::diag;
 
 use std::env;
@@ -60,7 +60,7 @@ impl diag::DiagnosableError for CargoError {
     }
 }
 
-/// A functioality wrapper around subproccess calls to cargo in PATH.
+/// A functionality wrapper around subproccess calls to cargo in `PATH`.
 impl CargoWrapper {
     fn cmd() -> Command {
         Command::new(env::var_os("CARGO").unwrap_or_else(|| "cargo".into()))

cargo-rtic-scope/src/log.rs

@@ -1,3 +1,4 @@
+//! Auxilliary functions for logging information to `stdout`.
 use colored::Colorize;
 use crossterm::{
     cursor,

cargo-rtic-scope/src/main.rs

@@ -219,6 +219,11 @@ fn main() {
     }
 }
 
+// XXX This one is messy: a &mut 'a of the session is required to read
+// trace data from it, but sticking it in a Box at the tail-end of trace
+// requires it to be 'static.
+//
+// TODO remove this global
 static mut SESSION: Option<probe_rs::Session> = None;
 
 async fn main_try() -> Result<(), RTICScopeError> {
@@ -242,8 +247,9 @@ async fn main_try() -> Result<(), RTICScopeError> {
         }
     }
 
-    // Build RTIC application to be traced, and create a wrapper around
-    // cargo, reusing the target directory of the application.
+    // Build the RTIC application to be traced in the future (not
+    // necessary for some commands), and create a wrapper around cargo,
+    // reusing the target directory of the application.
     #[allow(clippy::needless_question_mark)]
     let cart = async {
         log::status("Building", "RTIC target application...".to_string());
@@ -260,7 +266,7 @@ async fn main_try() -> Result<(), RTICScopeError> {
     };
 
     // Configure source and sinks. Recover the information we need to
-    // map IRQ numbers to RTIC tasks.
+    // map ITM packets to RTIC tasks.
     let (source, mut sinks, metadata) = match opts.cmd {
         Command::Trace(ref opts) => match trace(opts, cart).await? {
             Some(tup) => tup,
@@ -716,7 +722,7 @@ async fn trace(
     let metadata = TraceMetadata::from(
         artifact.target.name,
         maps,
-        Local::now(), // XXX this is the reset timestamp
+        Local::now(), // XXX this is the approximate reset timestamp
         manip.tpiu_freq,
         opts.comment.clone(),
     );

cargo-rtic-scope/src/manifest.rs

@@ -1,3 +1,7 @@
+//! Parses the `[package.metadata.rtic-scope]` and
+//! `[workspace.metadata.rtic-scope]` blocks from the RTIC application
+//! manifest for persistent RTIC Scope options. Some options can be
+//! supplied/overridden via command-line options.
 use crate::build::CargoWrapper;
 use crate::diag;
 use crate::ManifestOptions;

cargo-rtic-scope/src/recovery.rs

@@ -1,3 +1,5 @@
+//! Module responsible for recovering RTIC application metadata to
+//! associate ITM packets with RTIC tasks.
 use crate::build::{self, CargoWrapper};
 use crate::diag;
 use crate::manifest::ManifestProperties;
@@ -59,8 +61,7 @@ impl diag::DiagnosableError for RecoveryError {
     }
 }
 
-/// Lookup maps for hardware and software tasks (along with software
-/// task dispatchers and relevant DWT units). Keys are ...
+/// Lookup maps for hardware and software tasks.
 #[derive(Clone, Serialize, Deserialize, Debug)]
 pub struct TraceLookupMaps {
     software: SoftwareMap,
@@ -311,19 +312,6 @@ impl HardwareMap {
         cargo: &CargoWrapper,
         manip: &ManifestProperties,
     ) -> Result<Self, RecoveryError> {
-        // XXX processor core exceptions (internal interrupts)
-        // XXX device-specific exceptions (external interrupts)
-
-        // Find the bound exceptions from the #[task(bound = ...)]
-        // arguments. Further, partition internal and external
-        // interrupts. List of already known exceptions is extracted
-        // from the ARMv7-M arch. reference manual, table B1-4.
-        //
-        // For external exceptions (those defined in PAC::Interrupt), we
-        // need to resolve the number we receive over ITM back to the
-        // interrupt name. For internal interrupts, the name of the
-        // exception is received over ITM.
-
         use cortex_m::peripheral::scb::Exception;
         macro_rules! resolve_core_interrupts {
             ($($excpt:ident),+) => {{
@@ -333,6 +321,17 @@ impl HardwareMap {
                 },)+]
             }}
         }
+        // Exceptions common to all ARMv7-M targets. Known as /processor
+        // core exceptions/ or /internal interrupts/ These exceptions
+        // will be received over ITM as-is, and no additional
+        // information need to be recovered to use them. These labels
+        // are the same ones one can bind hardware tasks to, e.g.
+        //
+        //    #[task(binds = SysTick)]
+        //    fn task(_: task::Context) {}
+        //
+        // This list is sourced from the ARMv7-M arch. reference manual,
+        // table B1-4.
         let internal_ints: IndexMap<String, Exception> = IndexMap::from_iter(
             resolve_core_interrupts!(
                 NonMaskableInt,
@@ -350,6 +349,12 @@ impl HardwareMap {
             .cloned(),
         );
 
+        // Find all bound exceptions from the #[task(bound = ...)]
+        // arguments in the now-parsed source file. Partition internal
+        // (see above) and external interrupts. Further recovery work is
+        // required for the external interrupts: over ITM we'll receive
+        // the IRQ number which we need to associate to a label (found
+        // in PAC::Interrupt).
         type TaskBindMaps = IndexMap<String, String>;
         let (known_maps, unknown_maps): (TaskBindMaps, TaskBindMaps) = app
             .hardware_tasks
@@ -614,6 +619,7 @@ impl TraceMetadata {
 mod test {
     use super::*;
 
+    /// Ensure an RTIC application can be properly parsed.
     #[test]
     fn parse_rtic_app() {
         let arguments = quote!(device = stm32f4::stm32f401);

cargo-rtic-scope/src/sinks/file.rs

@@ -1,3 +1,5 @@
+//! A simple file sink which receives JSON-serialized [`TraceData`].
+//! Used for replay functionality.
 use crate::recovery::TraceMetadata;
 use crate::sinks::{Sink, SinkError};
 use crate::TraceData;

cargo-rtic-scope/src/sinks/frontend.rs

@@ -1,3 +1,5 @@
+//! Sub-proccess sink which received JSON-serialized
+//! [`api::EventChunk`]s.
 use crate::sinks::{Sink, SinkError};
 use crate::TraceData;
 

cargo-rtic-scope/src/sinks/mod.rs

@@ -1,3 +1,5 @@
+//! A sink to which [`TraceData`] and [`api::EventChunk`]s are for
+//! online and post-mortem analysis.
 use crate::diag;
 use crate::TraceData;
 

cargo-rtic-scope/src/sources/file.rs

@@ -1,3 +1,5 @@
+//! File source from which serialized [`TraceData`] is read for replay
+//! purposes.
 use crate::recovery::TraceMetadata;
 use crate::sources::{BufferStatus, Source, SourceError};
 use crate::TraceData;

cargo-rtic-scope/src/sources/mod.rs

@@ -1,3 +1,6 @@
+//! A source from which trace information is read. This [`TraceData`] is
+//! mapped to RTIC tasks and forwarded to configured sinks (files and
+//! frontends).
 use crate::diag;
 use crate::TraceData;
 

cargo-rtic-scope/src/sources/probe.rs

@@ -1,3 +1,4 @@
+//! Source which reads [`TraceData`] from a [`Session`].
 use crate::manifest::ManifestProperties;
 use crate::sources::{Source, SourceError};
 use crate::TraceData;

cargo-rtic-scope/src/sources/raw_file.rs

@@ -1,3 +1,4 @@
+//! Source which reads raw ITM packets from a file.
 use crate::manifest::ManifestProperties;
 use crate::sources::{BufferStatus, Source, SourceError};
 use crate::TraceData;

cargo-rtic-scope/src/sources/tty.rs

@@ -1,3 +1,6 @@
+//! Source which reads raw ITM packets from a serial device after
+//! properly configuring it. Commonly used if `probe-rs` cannot read the
+//! target device.
 use crate::manifest::ManifestProperties;
 use crate::sources::{BufferStatus, Source, SourceError};
 use crate::TraceData;