[debug] Add manticore::debug

The `debug` module is intended to hold debugging helpers, to make
debugging Manticore tests easier. This will include:

- Redactable logging.
- Error creation capture (e.g., capturing where `Err` variants are
  created).

The generated logs can be captured by tests, and eventually get returned
through Cerberus's "debug log" functionality.

Signed-off-by: Miguel Young de la Sota <[email protected]>

Author: mcy

Cargo.toml

@@ -30,6 +30,10 @@ version = "0.3"
 optional = true
 features = ["arbitrary-derive"]
 
+[dependencies.log]
+version = "0.4"
+optional = true
+
 [dependencies.ring]
 version = "0.16.11"
 optional = true
@@ -42,13 +46,15 @@ default-features = false
 features = ["derive"]
 
 [dev-dependencies]
+ctor = "0.1"
+env_logger = "0.8"
 pretty_assertions = "0.6.1"
 ring = "0.16.11"
 serde_json = "1.0"
 testutil = { path = "testutil" }
 
 [features]
-default = ["std", "ring"]
+default = ["std", "ring", "log"]
 
 # Enables deriving `arbitrary::Arbitrary` for various manticore types.
 arbitrary-derive = ["libfuzzer-sys", "std"]

src/debug.rs

@@ -0,0 +1,107 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Debug-logging functionality.
+//!
+//! This module is still present when the `log` feature is disabled, but all
+//! logging operations are redacted. Redaction completely compiles out log
+//! statements: not even the format strings remain in the final binary.
+//!
+//! Manticore code *should not* call into the [`log`] crate directly outside of
+//! this module.
+
+#![allow(unused)]
+
+#[cfg(doc)]
+use __raw_log as log;
+
+/// Checks a condition, logging if it fails.
+///
+/// If the condition does not hold, constructs the given error, logs it, and
+/// returns out of the current function with it.
+macro_rules! check {
+    ($cond:expr, $error:expr) => {
+        if !$cond {
+            let e = $error;
+            error!(
+                "check failure: `{}`; returned {:?}"
+                stringify!($cond), e
+            );
+            return Err(e);
+        }
+    }
+}
+
+/// Logs a newly-created error value and returns it.
+///
+/// This function is useful for marking where errors originate in tests.
+/// For example, instead of writing `foo.ok_or(MyError)`, instead write
+/// `foo.ok_or_else(|| trace!(MyError))`.
+macro_rules! trace {
+    ($error:expr, $($format:tt)+) => {{
+        error!($($format)+);
+        $error
+    }};
+    ($error:expr) => {{
+        let e = $error;
+        error!("generated error: `{:?}`", e);
+        e
+    }};
+}
+
+/// Redactable version of [`log::info!()`].
+macro_rules! info {
+    ($($args:tt)*) => {
+        #[cfg(feature = "log")]
+        let _ = __raw_log::info!($($args)*);
+    }
+}
+
+/// Redactable version of [`log::warn!()`].
+macro_rules! warn {
+    ($($args:tt)*) => {
+        #[cfg(feature = "log")]
+        let _ = __raw_log::warn!($($args)*);
+    }
+}
+
+/// Redactable version of [`log::error!()`].
+macro_rules! error {
+    ($($args:tt)*) => {
+        #[cfg(feature = "log")]
+        let _ = __raw_log::error!($($args)*);
+    }
+}
+
+/// Set up some life-before-main code that initializes a basic logger for the
+/// test binary.
+///
+/// This needs to happen here, since the test binary's main() cannot be
+/// overriden.
+#[cfg(test)]
+#[ctor::ctor]
+fn init_test_logger() {
+    env_logger::builder()
+        .format(move |_, record| {
+            use std::io::Write;
+
+            let thread = std::thread::current();
+            let name = thread.name().unwrap_or("<unknown>");
+            for line in record.args().to_string().trim().lines() {
+                // NOTE: we explicitly print to stderr, since this allows the
+                // Rust test harness to supress log statements originating from
+                // passing tests.
+                eprintln!(
+                    "[{level}({thread}) {file}:{line}] {msg}",
+                    level = record.level(),
+                    thread = name,
+                    file = record.file().unwrap_or("<unknown>"),
+                    line = record.line().unwrap_or(0),
+                    msg = line,
+                )
+            }
+            Ok(())
+        })
+        .init();
+}

src/lib.rs

@@ -30,6 +30,8 @@
 //! - `ring` (default) enables the [`crypto::ring` module], which provides
 //!   software implementations for cryptography traits used by `manticore`.
 //!   This feature is not intended for on-device use-cases either.
+//! - `log` (default) enables debug logging throughout manticore, via the `log`
+//!   crate. This feature can be disabled to redact all logging.
 //! - `serde` enables implementations of `serde`'s (de)serialization traits.
 //! - `arbitrary-derive` enables implementations of fuzz-testing-related
 //!   traits.
@@ -46,8 +48,16 @@
 #![deny(unused)]
 #![deny(unsafe_code)]
 
+// Pull in the `log` crate via a different name, to help prevent code from
+// accidentally using it without going through the redactable versions in
+// `debug`.
+#[cfg(feature = "log")]
+extern crate log as __raw_log;
+
 #[macro_use]
 pub mod protocol;
+#[macro_use]
+mod debug;
 
 #[cfg(feature = "serde")]
 mod serde;