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.