intel_crashlog/
lib.rs

1// Copyright (C) 2025 Intel Corporation
2// SPDX-License-Identifier: MIT
3
4#![cfg_attr(not(feature = "std"), no_std)]
5
6//! ## Getting Started
7//!
8//! ### Basic Decoding
9//!
10//! This crate exposes an API to decode Crash Log binaries generated by various Intel products.
11//! The high-level information stored in the records can be accessed as follows:
12//!
13//! ```
14//! use intel_crashlog::prelude::*;
15//!
16//! // Read the Crash Log binary from a file
17//! let data = std::fs::read("tests/samples/dummy_mca_rev1.crashlog").unwrap();
18//!
19//! // Parse the binary into a Crash Log object
20//! let crashlog = CrashLog::from_slice(&data).unwrap();
21//!
22//! // Record headers can be accessed directly
23//! assert_eq!(crashlog.regions[0].records[0].header.version.revision, 1);
24//!
25//! // Decode the headers of the Crash Log records into a register tree
26//! let nodes = crashlog.decode_without_cm();
27//!
28//! // Export the register tree to JSON
29//! assert_eq!(
30//!     serde_json::to_value(&nodes).unwrap(),
31//!     serde_json::json!({
32//!         "crashlog_data": {
33//!             "mca": {
34//!                 "hdr": {
35//!                     "agent_version": "0x0",
36//!                     "completion_status": {
37//!                         "completion_status": "0x0",
38//!                         "record_collection_completed": "0x0"
39//!                     },
40//!                     "reason": "0x0",
41//!                     "record_size": {
42//!                         "extended_record_size": "0x0",
43//!                         "record_size": "0xd0"
44//!                     },
45//!                     "timestamp": "0x0",
46//!                     "version": {
47//!                         "_value": "0x7e07a301",
48//!                         "header_type": "0x3",
49//!                         "product_id": "0x7a",
50//!                         "record_type": "0x3e",
51//!                         "revision": "0x1"
52//!                     }
53//!                 }
54//!             }
55//!         }
56//!     })
57//! );
58//! ```
59//!
60//! ### Decoding Product-specific Registers
61//!
62//! The basic decoding showcased in the previous section is only limited to the record headers.
63//! As the content of the record payloads is product-specific, a [collateral::CollateralManager]
64//! must be used to decode the registers stored in the record payloads. The
65//! [collateral::CollateralManager] provides a unified access to the product-specific definitions.
66//!
67//! ```
68//! use intel_crashlog::prelude::*;
69//!
70//! // Read the Crash Log binary from a file.
71//! let data = std::fs::read("tests/samples/three_strike_timeout_with_xq.crashlog").unwrap();
72//!
73//! // Parse the binary into a Crash Log object.
74//! let crashlog = CrashLog::from_slice(&data).unwrap();
75//!
76//! // Use product-specific decode definitions that are embedded in the crate's binary.
77//! let mut cm = CollateralManager::embedded_tree().unwrap();
78//!
79//! // Decode the content of the Crash Log records into a register tree.
80//! let nodes = crashlog.decode(&mut cm);
81//!
82//! // Get the status register of the fourth MCA bank from the register tree.
83//! let status = nodes.get_by_path(
84//!     "pcore.core0.thread0.thread.arch_state.mca.bank3.status"
85//! ).unwrap();
86//! assert_eq!(status.kind, NodeType::Field { value: 0xbe000000e1840400 });
87//!
88//! // Get the instruction pointer of the first core.
89//! let lip = nodes.get_by_path("pcore.core0.thread0.thread.arch_state.lip").unwrap();
90//! assert_eq!(lip.kind, NodeType::Field { value: 0xfffff80252753e75 });
91//!
92//! // Triage the crash
93//! let tags = Analyzer::default()
94//!     .with_input(&nodes)
95//!     .analyze()
96//!     .tags;
97//! assert_eq!(tags[0].to_string(), "CORE_TIMEOUT.SINGLE_STUCK_TRANSACTION.13014002340H");
98//! ```
99//!
100//! ## Default Features
101//!
102//! - `analysis`: provides functions to analyze the decoded Crash Log records.
103//! - `collateral_manager`: provides support for the project-specific decode definitions. See
104//!   [collateral] for more information.
105//! - `control_commands`: provides functions to execute Crash Log Control commands in the platform.
106//! - `extraction`: provides functions to extract the Crash Log record from the platform.
107//! - `embedded_collateral_tree`: embeds the collateral tree in the binary (requires
108//!   `collateral_manager`).
109//! - `ffi`: provides a C interface to the library (requires `embedded_collateral_tree`). See [ffi]
110//!   for more information.
111//! - `fs_collateral_tree`: provides support in the collateral manager for reading collateral tree
112//!   from the file system at runtime (requires `std` and `collateral_manager`).
113//! - `serialize`: provides [serde::Serialize] implementation for the [node::Node] objects. This is
114//!   required to export the register tree to JSON.
115//! - `std`: when disabled, the crate won't depend on the Rust's standard library. Please note
116//!   that a memory allocator is still required by this crate in `#![no_std]` environments.
117
118#[cfg(not(feature = "std"))]
119extern crate alloc;
120
121#[cfg(feature = "analysis")]
122pub mod analysis;
123mod bert;
124#[cfg(feature = "collateral_manager")]
125pub mod collateral;
126mod cper;
127mod crashlog;
128pub mod errata;
129mod error;
130#[cfg(feature = "ffi")]
131pub mod ffi;
132pub mod header;
133pub mod metadata;
134pub mod node;
135pub mod prelude;
136pub mod record;
137pub mod region;
138pub mod source;
139mod utils;
140
141pub use crashlog::CrashLog;
142pub use error::Error;
intel_crashlog/lib.rs

intel_crashlog/
lib.rs
