Fpdt parser
fpdt_parser ¶
FPDT Parser Tool.
Copyright © Microsoft Corporation SPDX-License-Identifier: BSD-2-Clause-Patent
This module provides functionality to parse the Firmware Performance Data Table (FPDT) and Firmware Basic Performance Table (FBPT) from Windows systems. It supports extracting and storing the parsed data in various formats such as text and XML.
Classes:
Name | Description |
---|---|
AcpiTableHeader |
Represents the header of an ACPI table and provides methods to parse, display, and convert it to XML. |
FwBasicBootPerformanceRecord |
Represents a Firmware Basic Boot Performance Record and provides methods to parse, display, and convert it to XML. |
FwBasicBootPerformanceTableHeader |
Represents the Firmware Basic Boot Performance Table Header and provides methods to parse, display, and convert it to XML. |
FbptRecordHeader |
Represents the header of a Firmware Boot Performance Table (FBPT) record and provides methods to parse, display, and convert it to XML. |
FwBasicBootPerformanceDataRecord |
Represents a firmware basic boot performance data record and provides methods to parse, display, and convert it to XML. |
GuidEventRecord |
Represents a GUID Event Record and provides methods to parse, display, and convert it to XML. |
DynamicStringEventRecord |
Represents a dynamic string event record and provides methods to parse, display, and convert it to XML. |
DualGuidStringEventRecord |
Represents a Dual GUID String Event Record and provides methods to parse, display, and convert it to XML. |
GuidQwordEventRecord |
Represents a GUID Qword Event Record and provides methods to parse, display, and convert it to XML. |
GuidQwordStringEventRecord |
Represents a GUID Qword String Event Record and provides methods to parse, display, and convert it to XML. |
SystemFirmwareTable |
Provides services to interact with system firmware tables using Windows APIs. |
Functions:
Name | Description |
---|---|
fbpt_parsing_factory |
BinaryIO, fbpt_records_list: list) -> int: Parses Firmware Boot Performance Table (FBPT) records from a binary file and appends them to a list. |
get_uefi_version |
Retrieves the UEFI version from the system's BIOS information. |
get_model |
Retrieves the model name of the computer system using WMI (Windows Management Instrumentation). |
Usage
This script can be executed as a standalone tool to parse FPDT and FBPT data. It supports command-line arguments for specifying input binary files, output text files, and output XML files.
Command-line Arguments
-t, --output_text: Name of the output text file to store FPDT information. -x, --output_xml: Name of the output XML file to store FPDT information. -b, --input_bin: Name of the input binary file containing the FBPT.
Example
python fpdt_parser.py -x fpdt_output.xml
AcpiTableHeader ¶
Represents the header of an ACPI table header.
Provides methods to parse, display, and convert the header data into different formats.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The struct format string used for unpacking the header. |
size |
int
|
The size of the ACPI table header in bytes. |
signature |
str
|
The signature of the ACPI table (decoded from bytes). |
length |
int
|
The length of the ACPI table in bytes. |
revision |
int
|
The revision of the ACPI table. |
checksum |
int
|
The checksum of the ACPI table. |
oem_id |
bytes
|
The OEM ID associated with the ACPI table. |
oem_table_id |
bytes
|
The OEM table ID associated with the ACPI table. |
oem_revision |
int
|
The OEM revision of the ACPI table. |
creator_id |
bytes
|
The ID of the creator of the ACPI table. |
creator_revision |
int
|
The revision of the creator of the ACPI table. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the ACPI table header to an XML representation. |
__init__ ¶
__init__(header_byte_array: bytes) -> None
Initialize an AcpiTableHeader instance by unpacking data from a byte array.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
header_byte_array |
bytes
|
A byte array containing the ACPI table header data. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
FwBasicBootPerformanceRecord ¶
Represents a Firmware Basic Boot Performance Record.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The struct format string used for unpacking the binary data. |
size |
int
|
The size of the structure in bytes, calculated using the struct format. |
performance_record_type |
int
|
The type of the performance record. |
record_length |
int
|
The length of the record. |
revision |
int
|
The revision of the record. |
reserved |
int
|
Reserved field for future use. |
fbpt_pointer |
int
|
Pointer to the Firmware Boot Performance Table (FBPT). |
Methods:
Name | Description |
---|---|
to_xml |
Converts the record's data into an XML representation. |
__init__ ¶
__init__(record_byte_array: bytes) -> None
Initializes an instance of the FwBasicBootPerformanceRecord class.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_byte_array |
bytes
|
A byte array containing the performance record data to be unpacked. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
FwBasicBootPerformanceTableHeader ¶
Represents the Firmware Basic Boot Performance Table Header.
This class is used to parse and represent the header of a firmware basic boot performance table. It provides methods to interpret the header data, convert it to a string representation, and serialize it into an XML format.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the header structure in bytes. |
signature |
str
|
The ASCII signature of the header. |
length |
int
|
The length of the header in bytes. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the record's data into an XML representation. |
__init__ ¶
__init__(header_byte_array: bytes) -> None
Initializes an instance of the FwBasicBootPerformanceTableHeader class.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
header_byte_array |
bytes
|
A byte array containing the header data. It is unpacked to extract the signature and length. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
FbptRecordHeader ¶
Represents the header of a Firmware Boot Performance Table (FBPT) record.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the header data. |
size |
int
|
The size of the header structure in bytes. |
performance_record_type |
int
|
The type of the performance record. |
record_length |
int
|
The length of the record. |
revision |
int
|
The revision of the record. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the record's data into an XML representation. |
__init__ ¶
__init__(header_byte_array: bytes) -> None
Initializes an instance of the class by parsing a header byte array.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
header_byte_array |
bytes
|
A byte array containing the header data to be parsed. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
FwBasicBootPerformanceDataRecord ¶
Represents a firmware basic boot performance data record.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the binary data structure in bytes. |
header |
The record header containing metadata about the performance data. |
|
reserved |
int
|
Reserved field in the performance data record. |
reset_end |
int
|
Timestamp indicating the end of the reset phase. |
os_loader_load_image_start |
int
|
Timestamp indicating the start of loading the OS loader image. |
os_loader_start_image_start |
int
|
Timestamp indicating the start of the OS loader image execution. |
exit_boot_services_entry |
int
|
Timestamp indicating the entry point of the ExitBootServices call. |
exit_boot_services_exit |
int
|
Timestamp indicating the exit point of the ExitBootServices call. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the performance data record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
) -> None
Initializes an instance of the FwBasicBootPerformanceDataRecord class.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header information for the firmware boot performance record. |
required |
contents_byte_array |
bytes
|
A byte array containing the performance data record contents. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
GuidEventRecord ¶
Represents a GUID Event Record parsed from a binary data structure.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the binary structure as calculated by |
Methods:
Name | Description |
---|---|
to_xml |
Converts the event record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
) -> None
Initializes a GuidEventRecord instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header of the record containing metadata. |
required |
contents_byte_array |
bytes
|
A byte array containing the data for the GUID event record. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
DynamicStringEventRecord ¶
Represents a dynamic string event record.
Provides methods to parse the binary data, represent the record as a string, and convert it to an XML representation.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used to unpack the binary data. |
size |
int
|
The size of the binary data structure. |
header |
The record header containing metadata. |
|
string |
str
|
The extracted and sanitized string from the binary data. |
progress_id |
int
|
The progress ID of the event. |
apic_id |
int
|
The APIC ID associated with the event. |
timestamp |
int
|
The timestamp of the event in raw format. |
guid_uint32 |
int
|
The first 32 bits of the GUID. |
guid_uint16_0 |
int
|
The first 16-bit segment of the GUID. |
guid_uint16_1 |
int
|
The second 16-bit segment of the GUID. |
guid_uint8_0 |
to guid_uint8_7 (int
|
The 8 individual bytes of the GUID. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the event record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
string_byte_array: bytes,
string_size: int,
) -> None
Initializes a DynamicStringEventRecord instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header of the FBPT record. |
required |
contents_byte_array |
bytes
|
Byte array containing the contents of the record. |
required |
string_byte_array |
bytes
|
Byte array containing the string data. |
required |
string_size |
int
|
The size of the string in bytes. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
DualGuidStringEventRecord ¶
Represents a Dual GUID String Event Record.
Provides methods to parse the binary data, represent it as a string, and convert it to an XML representation.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the binary structure based on the format string. |
header |
The record header associated with this event record. |
|
string |
str
|
The parsed string from the binary data. |
progress_id |
int
|
The progress ID of the event. |
apic_id |
int
|
The APIC ID of the event. |
timestamp |
int
|
The timestamp of the event in raw format. |
guid1_* |
int
|
Components of the first GUID (GUID1). |
guid2_* |
int
|
Components of the second GUID (GUID2). |
Methods:
Name | Description |
---|---|
to_xml |
Converts the event record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
string_byte_array: bytes,
string_size: int,
) -> None
Initializes a DualGuidStringEventRecord instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header of the record. |
required |
contents_byte_array |
bytes
|
Byte array containing the record's content data. |
required |
string_byte_array |
bytes
|
Byte array containing the string data. |
required |
string_size |
int
|
The size of the string in bytes. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
GuidQwordEventRecord ¶
Represents a GUID Qword Event Record.
Provides methods to convert the parsed data into human-readable string and XML representations.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the binary structure, calculated using the struct format. |
header |
The record header associated with the event. |
|
progress_id |
int
|
The progress ID of the event. |
apic_id |
int
|
The APIC ID of the event. |
timestamp |
int
|
The timestamp of the event in raw format. |
guid_uint32 |
int
|
The first 32 bits of the GUID. |
guid_uint16_0 |
int
|
The first 16-bit segment of the GUID. |
guid_uint16_1 |
int
|
The second 16-bit segment of the GUID. |
guid_uint8_0 |
to guid_uint8_7 (int
|
The 8 individual bytes of the GUID. |
qword |
int
|
A 64-bit value associated with the event. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the event record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
) -> None
Initializes a GuidQwordEventRecord instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header of the FBPT record. |
required |
contents_byte_array |
bytes
|
The byte array containing the record data. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
ET.Element: An XML element containing the serialized data of the object. |
GuidQwordStringEventRecord ¶
Represents a GUID Qword String Event Record.
GuidQwordStringEventRecord ¶
Represents a GUID Qword String Event Record, which parses and stores data from a binary record format.
Attributes:
Name | Type | Description |
---|---|---|
struct_format |
str
|
The format string used for unpacking the binary data. |
size |
int
|
The size of the binary structure as calculated by the struct format. |
header |
int
|
The header of the record. |
string |
str
|
The parsed string from the binary data, with non-printable characters replaced by '?'. |
progress_id |
int
|
The progress ID extracted from the binary data. |
apic_id |
int
|
The APIC ID extracted from the binary data. |
timestamp |
int
|
The timestamp extracted from the binary data. |
guid_uint32 |
int
|
The first 32 bits of the GUID. |
guid_uint16_0 |
int
|
The first 16 bits of the GUID. |
guid_uint16_1 |
int
|
The second 16 bits of the GUID. |
guid_uint8_0 |
to guid_uint8_7 (int
|
The remaining 8 bytes of the GUID. |
qword |
int
|
A 64-bit value extracted from the binary data. |
Methods:
Name | Description |
---|---|
to_xml |
Converts the event record to an XML representation. |
__init__ ¶
__init__(
record_header: FbptRecordHeader,
contents_byte_array: bytes,
string_byte_array: bytes,
string_size: int,
) -> None
Initializes a GuidQwordStringEventRecord instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
record_header |
FbptRecordHeader
|
The header of the FBPT record. |
required |
contents_byte_array |
bytes
|
Byte array containing the contents of the record. |
required |
string_byte_array |
bytes
|
Byte array containing the string data. |
required |
string_size |
int
|
The size of the string in bytes. |
required |
__str__ ¶
__str__() -> str
Generate a string representation of the object.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
A formatted string representation of the object's data. |
to_xml ¶
to_xml() -> ET.Element
Converts the object's data into an XML representation.
Returns:
Type | Description |
---|---|
Element
|
xml.etree.ElementTree.Element: The root XML element representing the object. |
SystemFirmwareTable ¶
Provides services to get system firmware tables.
Interacts with Windows APIs like GetSystemFirmwareTable
and NtQuerySystemInformation
to perform these
operations.
Methods:
Name | Description |
---|---|
get_acpi_table |
bytes) -> tuple: Retrieves an ACPI table from the system firmware. |
get_fbpt |
Retrieves the Firmware Boot Performance Table (FBPT) using the NtQuerySystemInformation API. |
__init__ ¶
__init__() -> None
Initializes the class and sets up the necessary privileges and system firmware APIs.
This constructor
- Enables the
SeSystemEnvironmentPrivilege
privilege for the current process. - Imports and configures the
GetSystemFirmwareTable
andNtQuerySystemInformation
functions from the Windows API for interacting with system firmware and querying system information.
Raises:
Type | Description |
---|---|
AttributeError
|
If the required firmware table functions are not available in the Windows API. |
get_acpi_table ¶
get_acpi_table(table_id: bytes) -> tuple
Retrieves an ACPI table from the system firmware.
This function uses the GetSystemFirmwareTable
Windows API to retrieve an ACPI table
identified by the provided table_id
. The function handles cases where the table size
exceeds the initial buffer length by dynamically resizing the buffer.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
table_id |
bytes
|
A 4-byte identifier for the ACPI table in little-endian format. |
required |
Returns:
Name | Type | Description |
---|---|---|
tuple |
tuple
|
A tuple containing: - int: Error code (0 for success, or a non-zero error code on failure). - bytes or None: The retrieved ACPI table as a byte array, or None if an error occurred. - str or None: An error message or additional information, or None if no error occurred. |
Notes
- The function logs detailed information and errors using the
logging
module. - If the
_get_system_firmware_table
attribute is not set, the function returns an error code of -20. - If the table retrieval fails, the function logs the error and returns the corresponding Windows error code.
get_fbpt ¶
get_fbpt() -> tuple[int, ctypes.c_char_p | None]
Retrieves the Firmware Boot Performance Table (FBPT) using the NtQuerySystemInformation API.
Returns:
Name | Type | Description |
---|---|---|
tuple |
tuple[int, c_char_p | None]
|
A tuple containing: - status (int): The status code of the operation. A value of 0 indicates success. - param1 (ctypes.c_char_p or None): A buffer containing the FBPT data if the operation is successful, or None if an error occurs. |
ParserApp ¶
The main execution environment to parse FPDT.
handle_output_file ¶
handle_output_file() -> TextIOWrapper
Parses and validates the output file arguments.
get_uefi_version_model ¶
get_uefi_version_model() -> (str, str)
Gets the uefi version and model from the file name.
write_fpdt_header ¶
write_fpdt_header(table: SystemFirmwareTable) -> None
Writes the general FPDT header to the output file.
find_fbpt_file ¶
find_fbpt_file(table: SystemFirmwareTable) -> BinaryIO
Looks for the FBPT file in a given path or a known system location.
gather_fbpt_records ¶
gather_fbpt_records(fbpt_file: BinaryIO) -> list
Collects FBPT records from an input file.
write_records ¶
write_records(fbpt_records_list: list) -> int
Writes FBPT records to an output file.
fbpt_parsing_factory ¶
fbpt_parsing_factory(
fbpt_contents_file: BinaryIO, fbpt_records_list: list
) -> int
Parses Firmware Boot Performance Table (FBPT) records from a binary file and appends them to a list.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
fbpt_contents_file |
BinaryIO
|
A binary file object containing the FBPT data. |
required |
fbpt_records_list |
list
|
A list to store the parsed FBPT records. |
required |
Returns:
Name | Type | Description |
---|---|---|
int |
int
|
0 upon successful parsing. |
Raises:
Type | Description |
---|---|
ValueError
|
If an unknown record type is encountered. |
Notes
- The function assumes that the binary file contains complete records and does not stop in the middle of a record header.
- If an unknown record type is encountered, a critical message is logged and the record is skipped.
get_uefi_version ¶
get_uefi_version() -> str
Retrieves the UEFI version from the system's BIOS information.
This function uses the Windows Management Instrumentation (WMI) interface to query the system's BIOS and extract the SMBIOS BIOS version.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
The UEFI version as a string if successfully retrieved, otherwise returns "Unknown". |
Logs
Logs an error message if the UEFI version cannot be retrieved.
get_model ¶
get_model() -> str
Retrieves the model name of the computer system using WMI (Windows Management Instrumentation).
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
The model name of the computer system. If an error occurs during retrieval, |
str
|
"Unknown" is returned and the error is logged. |