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

intel_crashlog/
lib.rs
