Skip to content

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 struct.calcsize.

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
  1. Enables the SeSystemEnvironmentPrivilege privilege for the current process.
  2. Imports and configures the GetSystemFirmwareTable and NtQuerySystemInformation 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.

__init__

__init__() -> None

Initializes the record parser.

set_up_logging

set_up_logging() -> None

Sets up logging during parsing.

handle_output_file

handle_output_file() -> TextIOWrapper

Parses and validates the output file arguments.

handle_input_file

handle_input_file() -> None

Parses and validates the input file argument.

get_uefi_version_model

get_uefi_version_model() -> (str, str)

Gets the uefi version and model from the file name.

write_text_header

write_text_header() -> None

Writes the header to the text file.

write_xml_header

write_xml_header() -> ET.Element

Writes the header to the XML file.

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.

write_fbpt

write_fbpt(fbpt_file: BinaryIO) -> None

Writes the header into the FBPT.

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.

main

main() -> None

Main function to execute the script.