lib

Lightweight Crash Log Framework - Library

Features Overview

• Extracts Crash Log records from Windows Event Logs, Linux sysfs, and UEFI System Table.
• Decodes Crash Log records from ACPI BERT, CPER, or raw dumps.
• Provides a collateral manager for decoding product-specific information.
• Collateral tree can be read from the file system at runtime or embedded in the library.
• Offers FFI to interface with non-Rust applications.
• Supports no_std.
• Follows Semantic Versioning convention.

Usage

For Rust Projects

1. Add the following lines to your Cargo.toml file:

[dependencies.intel_crashlog]
version = "1.0"
git = "https://github.com/intel/crashlog"

2. If needed, specify the features needed in the library:

[dependencies.intel_crashlog]
version = "1.0"
git = "https://github.com/intel/crashlog"
default-features = false
features = ["serialize", "std"]

C/C++ projects

1. Build the library using the following command:

$ cargo build --release --features ffi

2. If needed, specify the features needed in the library:

$ cargo build --release --no-default-features --features ffi,serialize,std

3. The header files are generated under the target/include directory:

   • C Header: target/include/intel_crashlog.h
   • C++ Header: target/include/intel_crashlog.hpp

4. The generated system library is located in the target/release directory and can be linked to your C/C++ project:

   • Windows: target/release/intel_crashlog.dll
   • Linux: target/release/libintel_crashlog.so

Product Support

The product-specific support is provided by the collateral tree. The files included in the collateral tree can be embedded in the crate/library when the embedded_collateral_tree feature is enabled.

This can be configure at build-time using the following environment variables:

• CRASHLOG_COLLATERAL_TREE: Path to the collateral tree in the file system. If not set, the build script will embed the files located in the collateral folder.
• CRASHLOG_PRODUCTS: Comma-separated list of products (Three-Letter Acronyms) to include in the embedded tree. If not set or empty, all the available product supports found in the collateral tree are included.

Example:

$ CRASHLOG_COLLATERAL_TREE=./collateral CRASHLOG_PRODUCTS=LNL,LNC,SKT cargo build

Building Documentation

Generate the HTML documentation with:

$ cargo doc --all-features

The documentation will be available under the target/doc/intel_crashlog/ directory.

Examples

Basic Decoding

This crate provides an API to decode Crash Log binaries generated by various Intel products. You can access the high-level information stored in the records as follows:

use intel_crashlog::prelude::*;

// Read the Crash Log binary from a file
let data = std::fs::read("tests/samples/dummy_mca_rev1.crashlog").unwrap();

// Parse the binary into a Crash Log object
let crashlog = CrashLog::from_slice(&data).unwrap();

// Record headers can be accessed directly
assert_eq!(crashlog.regions[0].records[0].header.version.revision, 1);

// Decode the headers of the Crash Log records into a register tree
let nodes = crashlog.decode_without_cm();

// Export the register tree to JSON
assert_eq!(
    serde_json::to_value(&nodes).unwrap(),
    serde_json::json!({
        "crashlog_data": {
            "mca": {
                "hdr": {
                    "agent_version": "0x0",
                    "completion_status": {
                        "completion_status": "0x0",
                        "record_collection_completed": "0x0"
                    },
                    "reason": "0x0",
                    "record_size": {
                        "extended_record_size": "0x0",
                        "record_size": "0xd0"
                    },
                    "timestamp": "0x0",
                    "version": {
                        "header_type": "0x3",
                        "product_id": "0x7a",
                        "record_type": "0x3e",
                        "revision": "0x1"
                    }
                }
            }
        }
    })
);

Decoding Product-specific Registers

The basic decoding shown above is limited to record headers. To decode the registers stored in the record payloads, which are product-specific, use a collateral manager. This manager provides unified access to product-specific definitions.

use intel_crashlog::prelude::*;

// Read the Crash Log binary from a file.
let data = std::fs::read("tests/samples/dummy_mca_rev1.crashlog").unwrap();

// Parse the binary into a Crash Log object.
let crashlog = CrashLog::from_slice(&data).unwrap();

// Use product-specific decode definitions that are embedded in the crate's binary.
let mut cm = CollateralManager::embedded_tree().unwrap();

// Decode the content of the Crash Log records into a register tree.
let nodes = crashlog.decode(&mut cm);

// Get the status register of the fourth MCA bank from the register tree.
let status = nodes.get_by_path(
    "pcore.core0.thread0.thread.arch_state.mca.bank3.status"
).unwrap();
assert_eq!(status.kind, NodeType::Field { value: 0xbe000000e1840400 });

// Get the instruction pointer of the first core.
let lip = nodes.get_by_path("pcore.core0.thread0.thread.arch_state.lip").unwrap();
assert_eq!(lip.kind, NodeType::Field { value: 0xfffff80577036530 });

Development

Before submitting pull requests that modify any files in this directory, please run the following commands:

1. Ensure all unit tests pass:

$ cargo test --all-features

2. Verify the application builds on both Windows and Linux:

$ cargo build --target=x86_64-unknown-linux-gnu
$ cargo build --target=x86_64-pc-windows-gnu

3. Format the code according to style guidelines and run the linter:

$ cargo fmt
$ cargo clippy