Crate intel_crashlog 

Getting Started

Basic Decoding

This crate exposes an API to decode Crash Log binaries generated by various Intel products. The high-level information stored in the records can be accessed 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": {
                        "_value": "0x7e07a301",
                        "header_type": "0x3",
                        "product_id": "0x7a",
                        "record_type": "0x3e",
                        "revision": "0x1"
                    }
                }
            }
        }
    })
);

Decoding Product-specific Registers

The basic decoding showcased in the previous section is only limited to the record headers. As the content of the record payloads is product-specific, a collateral::CollateralManager must be used to decode the registers stored in the record payloads. The collateral::CollateralManager provides a unified access to the product-specific definitions.

use intel_crashlog::prelude::*;

// Read the Crash Log binary from a file.
let data = std::fs::read("tests/samples/three_strike_timeout.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 });

Default Features

• collateral_manager: provides support for the project-specific decode definitions. See collateral for more information.
• extraction: provides functions to extract the Crash Log record from the platform.
• embedded_collateral_tree: embeds the collateral tree in the binary (requires collateral_manager).
• ffi: provides a C interface to the library (requires embedded_collateral_tree). See ffi for more information.
• fs_collateral_tree: provides support in the collateral manager for reading collateral tree from the file system at runtime (requires std and collateral_manager).
• serialize: provides serde::Serialize implementation for the node::Node objects. This is required to export the register tree to JSON.
• std: when disabled, the crate won’t depend on the Rust’s standard library. Please note that a memory allocator is still required by this crate in #![no_std] environments.

Modules

collateralcollateral_manager

Management of the product-specific collateral required to decode the Crash Log records.

errata

Collection of erratas present in the Intel(R) Crash Log technology

ffiffi

C interface to the Intel Crash Log extraction and decoding functions.

header

Data structures used in the Crash Log record headers.

metadata

Information extracted alongside the Crash Log records.

node

A tree-like data structure containing the decoded Crash Log registers.

prelude

Convenience re-export of common structs

record

Provides access to the content of a Crash Log record.

region

Provides access to the records stored in a Crash Log region.

Structs

CrashLog

Set of all the Crash Log records captured on a platform.

Enums

Error

Errors reported by the Crash Log extraction and decoding functions.