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.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: 0xfffff80577036530 });
91//! ```
92//!
93//! ## Default Features
94//!
95//! - `collateral_manager`: provides support for the project-specific decode definitions. See
96//!   [collateral] for more information.
97//! - `extraction`: provides functions to extract the Crash Log record from the platform.
98//! - `embedded_collateral_tree`: embeds the collateral tree in the binary (requires
99//!   `collateral_manager`).
100//! - `ffi`: provides a C interface to the library (requires `embedded_collateral_tree`). See [ffi]
101//!   for more information.
102//! - `fs_collateral_tree`: provides support in the collateral manager for reading collateral tree
103//!   from the file system at runtime (requires `std` and `collateral_manager`).
104//! - `serialize`: provides [serde::Serialize] implementation for the [node::Node] objects. This is
105//!   required to export the register tree to JSON.
106//! - `std`: when disabled, the crate won't depend on the Rust's standard library. Please note
107//!   that a memory allocator is still required by this crate in `#![no_std]` environments.
108
109#[cfg(not(feature = "std"))]
110extern crate alloc;
111
112mod bert;
113#[cfg(feature = "collateral_manager")]
114pub mod collateral;
115mod cper;
116mod crashlog;
117pub mod errata;
118mod error;
119#[cfg(feature = "extraction")]
120mod extract;
121#[cfg(feature = "ffi")]
122pub mod ffi;
123pub mod header;
124pub mod metadata;
125pub mod node;
126pub mod prelude;
127pub mod record;
128pub mod region;
129mod utils;
130
131pub use crashlog::CrashLog;
132pub use error::Error;
intel_crashlog/lib.rs

intel_crashlog/
lib.rs
