From nobody Wed May 15 12:05:13 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+87799+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+87799+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=quicinc.com ARC-Seal: i=1; a=rsa-sha256; t=1647894075; cv=none; d=zohomail.com; s=zohoarc; b=dchoop+4Ms8iwfhsw5XRI+qU3vhhvsMfCocOwVfcF8a63s8mILVorXqKPin+oLXb7ofe+r7LAYuCZ5qo3KxfQ+2NbVkwXDd9kB3dUq0qUsrIpcw01qTknKVzCR6gkQto+9Bif1PTqGob62Vc1BuAeH0MG8g/WqHO03aq/Nv/8eQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1647894075; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=4cOe8tdesX0m1P7InVV2lAzPyekgZ4nWNxUxV6j8Hi0=; b=hL370P0CQZNpy5mZjhmEMzxqHqF1qZ6QSYWPeAF6Dy8fHn9vm4+rdKGzCwQWp/I4FfKACjB5e73BBH/K9mej+eF1KU5jFZhLPNhuhd3AEYSW5Vpwa3+qQS92QqG39Jvs39BOBEpUwZqj/djC7VUKhxHJRVPEyS5YEUFZDJS5w/Q= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+87799+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1647894075689688.8338359154956; Mon, 21 Mar 2022 13:21:15 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id IvMlYY1788612xyrKIFRnRZT; Mon, 21 Mar 2022 13:21:15 -0700 X-Received: from alexa-out-sd-02.qualcomm.com (alexa-out-sd-02.qualcomm.com [199.106.114.39]) by mx.groups.io with SMTP id smtpd.web09.847.1647894074411868328 for ; Mon, 21 Mar 2022 13:21:14 -0700 X-Received: from unknown (HELO ironmsg05-sd.qualcomm.com) ([10.53.140.145]) by alexa-out-sd-02.qualcomm.com with ESMTP; 21 Mar 2022 13:21:13 -0700 X-QCInternal: smtphost X-Received: from nasanex01c.na.qualcomm.com ([10.47.97.222]) by ironmsg05-sd.qualcomm.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Mar 2022 13:21:13 -0700 X-Received: from nalasex01a.na.qualcomm.com (10.47.209.196) by nasanex01c.na.qualcomm.com (10.47.97.222) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:13 -0700 X-Received: from linbox.ba.nuviainc.com (10.80.80.8) by nalasex01a.na.qualcomm.com (10.47.209.196) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:12 -0700 From: "Rebecca Cran" To: , Leif Lindholm , Michael D Kinney , Hao A Wu , Bob Feng , Liming Gao , Yuwei Chen CC: Rebecca Cran , Andrew Fish Subject: [edk2-devel] [PATCH v2 1/3] BaseTools: efi_debugging.py: Add debugger agnostic dbg Python Classes Date: Mon, 21 Mar 2022 14:20:46 -0600 Message-ID: <20220321202048.13567-2-quic_rcran@quicinc.com> In-Reply-To: <20220321202048.13567-1-quic_rcran@quicinc.com> References: <20220321202048.13567-1-quic_rcran@quicinc.com> MIME-Version: 1.0 X-Originating-IP: [10.80.80.8] X-ClientProxiedBy: nasanex01a.na.qualcomm.com (10.52.223.231) To nalasex01a.na.qualcomm.com (10.47.209.196) Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,quic_rcran@quicinc.com X-Gm-Message-State: TP4bdXZTc960iOSHlFvXl6eHx1787277AA= Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1647894075; bh=u6SEr3B7tSZ6YWQE1DF9mBCFLaqAIlrc9n5GGVEqbn0=; h=CC:Content-Type:Date:From:Reply-To:Subject:To; b=tVnCjHMvVrqa6XVEYVoxOlL7gODyNZyH9v71wqw4s0DF0+VEenxnK3QQKH1BiEUJV68 xlcriARF1cKHjMamkNey9nuEyavJJqpx4ptq2qVNdf39XvKF5Vt3tIiramJEky2Q/KZP8 fjtzrKbJIuuhCI4DNjlcXV/CxyX7FK+QdA8= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1647894076536100002 Add Scripts/efi_debugging.py to provide debugger agnostic debugging utility Python classes. Cc: Leif Lindholm Cc: Michael D Kinney Cc: Hao A Wu Cc: Bob Feng Cc: Liming Gao Cc: Yuwei Chen Signed-off-by: Rebecca Cran Acked-by: Liming Gao Reviewed-by: Bob Feng --- BaseTools/Scripts/efi_debugging.py | 2185 ++++++++++++++++++++ 1 file changed, 2185 insertions(+) diff --git a/BaseTools/Scripts/efi_debugging.py b/BaseTools/Scripts/efi_deb= ugging.py new file mode 100755 index 000000000000..af975f4e6ceb --- /dev/null +++ b/BaseTools/Scripts/efi_debugging.py @@ -0,0 +1,2185 @@ +#!/usr/bin/python3 +''' +Copyright (c) Apple Inc. 2021 +SPDX-License-Identifier: BSD-2-Clause-Patent + +Class that abstracts PE/COFF debug info parsing via a Python file like +object. You can port this code into an arbitrary debugger by invoking +the classes and passing in a file like object that abstracts the debugger +reading memory. + +If you run this file directly it will parse the passed in PE/COFF files +for debug info: +python3 ./efi_pefcoff.py DxeCore.efi +IA32`/DxeCore.dll load =3D 0x00000000 +EntryPoint =3D 0x000030d2 TextAddress =3D 0x00000240 DataAddress =3D 0x00= 0042c0 +.text 0x00000240 (0x04080) flags:0x60000020 +.data 0x000042C0 (0x001C0) flags:0xC0000040 +.reloc 0x00004480 (0x00240) flags:0x42000040 + +Note: PeCoffClass uses virtual addresses and not file offsets. + It needs to work when images are loaded into memory. + as long as virtual address map to file addresses this + code can process binary files. + +Note: This file can also contain generic worker functions (like GuidNames) + that abstract debugger agnostic services to the debugger. + +This file should never import debugger specific modules. +''' + +import sys +import os +import uuid +import struct +import re +from ctypes import c_char, c_uint8, c_uint16, c_uint32, c_uint64, c_void_p +from ctypes import ARRAY, sizeof +from ctypes import Structure, LittleEndianStructure + +# +# The empty LittleEndianStructure must have _fields_ assigned prior to use= or +# sizeof(). Anything that is size UINTN may need to get adjusted. +# +# The issue is ctypes matches our local machine, not the machine we are +# trying to debug. Call patch_ctypes() passing in the byte width from the +# debugger python to make sure you are in sync. +# +# Splitting out the _field_ from the Structure (LittleEndianStructure) cla= ss +# allows it to be patched. +# + + +class EFI_LOADED_IMAGE_PROTOCOL(LittleEndianStructure): + pass + + +EFI_LOADED_IMAGE_PROTOCOL_fields_ =3D [ + ('Revision', c_uint32), + ('ParentHandle', c_void_p), + ('SystemTable', c_void_p), + ('DeviceHandle', c_void_p), + ('FilePath', c_void_p), + ('Reserved', c_void_p), + ('LoadOptionsSize', c_uint32), + ('LoadOptions', c_void_p), + ('ImageBase', c_void_p), + ('ImageSize', c_uint64), + ('ImageCodeType', c_uint32), + ('ImageDataType', c_uint32), + ('Unload', c_void_p), +] + + +class EFI_GUID(LittleEndianStructure): + _fields_ =3D [ + ('Data1', c_uint32), + ('Data2', c_uint16), + ('Data3', c_uint16), + ('Data4', ARRAY(c_uint8, 8)) + ] + + +class EFI_SYSTEM_TABLE_POINTER(LittleEndianStructure): + _fields_ =3D [ + ('Signature', c_uint64), + ('EfiSystemTableBase', c_uint64), + ('Crc32', c_uint32) + ] + + +class EFI_DEBUG_IMAGE_INFO_NORMAL(LittleEndianStructure): + pass + + +EFI_DEBUG_IMAGE_INFO_NORMAL_fields_ =3D [ + ('ImageInfoType', c_uint32), + ('LoadedImageProtocolInstance', c_void_p), + ('ImageHandle', c_void_p) +] + + +class EFI_DEBUG_IMAGE_INFO(LittleEndianStructure): + pass + + +EFI_DEBUG_IMAGE_INFO_fields_ =3D [ + ('NormalImage', c_void_p), +] + + +class EFI_DEBUG_IMAGE_INFO_TABLE_HEADER(LittleEndianStructure): + pass + + +EFI_DEBUG_IMAGE_INFO_TABLE_HEADER_fields_ =3D [ + ('UpdateStatus', c_uint32), + ('TableSize', c_uint32), + ('EfiDebugImageInfoTable', c_void_p), +] + + +class EFI_TABLE_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('Signature', c_uint64), + ('Revision', c_uint32), + ('HeaderSize', c_uint32), + ('CRC32', c_uint32), + ('Reserved', c_uint32), + ] + + +class EFI_CONFIGURATION_TABLE(LittleEndianStructure): + pass + + +EFI_CONFIGURATION_TABLE_fields_ =3D [ + ('VendorGuid', EFI_GUID), + ('VendorTable', c_void_p) +] + + +class EFI_SYSTEM_TABLE(LittleEndianStructure): + pass + + +EFI_SYSTEM_TABLE_fields_ =3D [ + ('Hdr', EFI_TABLE_HEADER), + ('FirmwareVendor', c_void_p), + ('FirmwareRevision', c_uint32), + ('ConsoleInHandle', c_void_p), + ('ConIn', c_void_p), + ('ConsoleOutHandle', c_void_p), + ('ConOut', c_void_p), + ('StandardErrHandle', c_void_p), + ('StdErr', c_void_p), + ('RuntimeService', c_void_p), + ('BootService', c_void_p), + ('NumberOfTableEntries', c_void_p), + ('ConfigurationTable', c_void_p), +] + + +class EFI_IMAGE_DATA_DIRECTORY(LittleEndianStructure): + _fields_ =3D [ + ('VirtualAddress', c_uint32), + ('Size', c_uint32) + ] + + +class EFI_TE_IMAGE_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('Signature', ARRAY(c_char, 2)), + ('Machine', c_uint16), + ('NumberOfSections', c_uint8), + ('Subsystem', c_uint8), + ('StrippedSize', c_uint16), + ('AddressOfEntryPoint', c_uint32), + ('BaseOfCode', c_uint32), + ('ImageBase', c_uint64), + ('DataDirectoryBaseReloc', EFI_IMAGE_DATA_DIRECTORY), + ('DataDirectoryDebug', EFI_IMAGE_DATA_DIRECTORY) + ] + + +class EFI_IMAGE_DOS_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('e_magic', c_uint16), + ('e_cblp', c_uint16), + ('e_cp', c_uint16), + ('e_crlc', c_uint16), + ('e_cparhdr', c_uint16), + ('e_minalloc', c_uint16), + ('e_maxalloc', c_uint16), + ('e_ss', c_uint16), + ('e_sp', c_uint16), + ('e_csum', c_uint16), + ('e_ip', c_uint16), + ('e_cs', c_uint16), + ('e_lfarlc', c_uint16), + ('e_ovno', c_uint16), + ('e_res', ARRAY(c_uint16, 4)), + ('e_oemid', c_uint16), + ('e_oeminfo', c_uint16), + ('e_res2', ARRAY(c_uint16, 10)), + ('e_lfanew', c_uint16) + ] + + +class EFI_IMAGE_FILE_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('Machine', c_uint16), + ('NumberOfSections', c_uint16), + ('TimeDateStamp', c_uint32), + ('PointerToSymbolTable', c_uint32), + ('NumberOfSymbols', c_uint32), + ('SizeOfOptionalHeader', c_uint16), + ('Characteristics', c_uint16) + ] + + +class EFI_IMAGE_OPTIONAL_HEADER32(LittleEndianStructure): + _fields_ =3D [ + ('Magic', c_uint16), + ('MajorLinkerVersion', c_uint8), + ('MinorLinkerVersion', c_uint8), + ('SizeOfCode', c_uint32), + ('SizeOfInitializedData', c_uint32), + ('SizeOfUninitializedData', c_uint32), + ('AddressOfEntryPoint', c_uint32), + ('BaseOfCode', c_uint32), + ('BaseOfData', c_uint32), + ('ImageBase', c_uint32), + ('SectionAlignment', c_uint32), + ('FileAlignment', c_uint32), + ('MajorOperatingSystemVersion', c_uint16), + ('MinorOperatingSystemVersion', c_uint16), + ('MajorImageVersion', c_uint16), + ('MinorImageVersion', c_uint16), + ('MajorSubsystemVersion', c_uint16), + ('MinorSubsystemVersion', c_uint16), + ('Win32VersionValue', c_uint32), + ('SizeOfImage', c_uint32), + ('SizeOfHeaders', c_uint32), + ('CheckSum', c_uint32), + ('Subsystem', c_uint16), + ('DllCharacteristics', c_uint16), + ('SizeOfStackReserve', c_uint32), + ('SizeOfStackCommit', c_uint32), + ('SizeOfHeapReserve', c_uint32), + ('SizeOfHeapCommit', c_uint32), + ('LoaderFlags', c_uint32), + ('NumberOfRvaAndSizes', c_uint32), + ('DataDirectory', ARRAY(EFI_IMAGE_DATA_DIRECTORY, = 16)) + ] + + +class EFI_IMAGE_NT_HEADERS32(LittleEndianStructure): + _fields_ =3D [ + ('Signature', c_uint32), + ('FileHeader', EFI_IMAGE_FILE_HEADER), + ('OptionalHeader', EFI_IMAGE_OPTIONAL_HEADER32) + ] + + +class EFI_IMAGE_OPTIONAL_HEADER64(LittleEndianStructure): + _fields_ =3D [ + ('Magic', c_uint16), + ('MajorLinkerVersion', c_uint8), + ('MinorLinkerVersion', c_uint8), + ('SizeOfCode', c_uint32), + ('SizeOfInitializedData', c_uint32), + ('SizeOfUninitializedData', c_uint32), + ('AddressOfEntryPoint', c_uint32), + ('BaseOfCode', c_uint32), + ('BaseOfData', c_uint32), + ('ImageBase', c_uint32), + ('SectionAlignment', c_uint32), + ('FileAlignment', c_uint32), + ('MajorOperatingSystemVersion', c_uint16), + ('MinorOperatingSystemVersion', c_uint16), + ('MajorImageVersion', c_uint16), + ('MinorImageVersion', c_uint16), + ('MajorSubsystemVersion', c_uint16), + ('MinorSubsystemVersion', c_uint16), + ('Win32VersionValue', c_uint32), + ('SizeOfImage', c_uint32), + ('SizeOfHeaders', c_uint32), + ('CheckSum', c_uint32), + ('Subsystem', c_uint16), + ('DllCharacteristics', c_uint16), + ('SizeOfStackReserve', c_uint64), + ('SizeOfStackCommit', c_uint64), + ('SizeOfHeapReserve', c_uint64), + ('SizeOfHeapCommit', c_uint64), + ('LoaderFlags', c_uint32), + ('NumberOfRvaAndSizes', c_uint32), + ('DataDirectory', ARRAY(EFI_IMAGE_DATA_DIRECTORY, = 16)) + ] + + +class EFI_IMAGE_NT_HEADERS64(LittleEndianStructure): + _fields_ =3D [ + ('Signature', c_uint32), + ('FileHeader', EFI_IMAGE_FILE_HEADER), + ('OptionalHeader', EFI_IMAGE_OPTIONAL_HEADER64) + ] + + +class EFI_IMAGE_DEBUG_DIRECTORY_ENTRY(LittleEndianStructure): + _fields_ =3D [ + ('Characteristics', c_uint32), + ('TimeDateStamp', c_uint32), + ('MajorVersion', c_uint16), + ('MinorVersion', c_uint16), + ('Type', c_uint32), + ('SizeOfData', c_uint32), + ('RVA', c_uint32), + ('FileOffset', c_uint32), + ] + + +class EFI_IMAGE_SECTION_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('Name', ARRAY(c_char, 8)), + ('VirtualSize', c_uint32), + ('VirtualAddress', c_uint32), + ('SizeOfRawData', c_uint32), + ('PointerToRawData', c_uint32), + ('PointerToRelocations', c_uint32), + ('PointerToLinenumbers', c_uint32), + ('NumberOfRelocations', c_uint16), + ('NumberOfLinenumbers', c_uint16), + ('Characteristics', c_uint32), + ] + + +EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC =3D 0x10b +EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC =3D 0x20b + +DIRECTORY_DEBUG =3D 6 + + +image_machine_dict =3D { + 0x014c: "IA32", + 0x0200: "IPF", + 0x0EBC: "EBC", + 0x8664: "X64", + 0x01c2: "ARM", + 0xAA64: "AArch64", + 0x5032: "RISC32", + 0x5064: "RISC64", + 0x5128: "RISCV128", +} + + +def patch_void_p_to_ctype(patch_type, to_patch): + '''Optionally patch c_void_p in the Structure._fields_''' + if patch_type is None: + return to_patch + + result =3D [] + for name, c_type in to_patch: + if type(c_type) =3D=3D type(c_void_p): + result.append((name, c_uint32)) + else: + result.append((name, c_type)) + return result + + +def patch_ctypes(pointer_width=3D8): + ''' + Pass in the pointer width of the system being debugged. If it is not + the same as c_void_p then patch the _fields_ with the correct type. + For any ctypes Structure that has a c_void_p this function needs to be + called prior to use or sizeof() to initialize _fields_. + ''' + + if sizeof(c_void_p) =3D=3D pointer_width: + patch_type =3D None + elif pointer_width =3D=3D 16: + assert False + elif pointer_width =3D=3D 8: + patch_type =3D c_uint64 + elif pointer_width =3D=3D 4: + patch_type =3D c_uint32 + else: + raise Exception(f'ERROR: Unkown pointer_width =3D {pointer_width}') + + # If you add a ctypes Structure class with a c_void_p you need to add + # it to this list. Note: you should use c_void_p for UINTN values. + EFI_LOADED_IMAGE_PROTOCOL._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_LOADED_IMAGE_PROTOCOL_fields_) + EFI_DEBUG_IMAGE_INFO_NORMAL._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_DEBUG_IMAGE_INFO_NORMAL_fields_) + EFI_DEBUG_IMAGE_INFO._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_DEBUG_IMAGE_INFO_fields_) + EFI_DEBUG_IMAGE_INFO_TABLE_HEADER._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_DEBUG_IMAGE_INFO_TABLE_HEADER_fields_) + EFI_CONFIGURATION_TABLE._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_CONFIGURATION_TABLE_fields_) + EFI_SYSTEM_TABLE._fields_ =3D patch_void_p_to_ctype( + patch_type, EFI_SYSTEM_TABLE_fields_) + + # patch up anything else that needs to know pointer_width + EfiStatusClass(pointer_width) + + +def ctype_to_str(ctype, indent=3D'', hide_list=3D[]): + ''' + Given a ctype object print out as a string by walking the _fields_ + in the cstring Class + ''' + result =3D '' + for field in ctype._fields_: + attr =3D getattr(ctype, field[0]) + tname =3D type(attr).__name__ + if field[0] in hide_list: + continue + + result +=3D indent + f'{field[0]} =3D ' + if tname =3D=3D 'EFI_GUID': + result +=3D GuidNames.to_name(GuidNames.to_uuid(attr)) + '\n' + elif issubclass(type(attr), Structure): + result +=3D f'{tname}\n' + \ + ctype_to_str(attr, indent + ' ', hide_list) + elif isinstance(attr, int): + result +=3D f'0x{attr:x}\n' + else: + result +=3D f'{attr}\n' + + return result + + +def hexline(addr, data): + hexstr =3D '' + printable =3D '' + for i in range(0, len(data)): + hexstr +=3D f'{data[i]:02x} ' + printable +=3D chr(data[i]) if data[i] > 0x20 and data[i] < 0x7f e= lse '.' + return f'{addr:04x} {hexstr:48s} |{printable:s}|' + + +def hexdump(data, indent=3D''): + if not isinstance(data, bytearray): + data =3D bytearray(data) + + result =3D '' + for i in range(0, len(data), 16): + result +=3D indent + hexline(i, data[i:i+16]) + '\n' + return result + + +class EfiTpl: + ''' Return string for EFI_TPL''' + + def __init__(self, tpl): + self.tpl =3D tpl + + def __str__(self): + if self.tpl < 4: + result =3D f'{self.tpl:d}' + elif self.tpl < 8: + result =3D "TPL_APPLICATION" + if self.tpl - 4 > 0: + result +=3D f' + {self.tpl - 4:d}' + elif self.tpl < 16: + result =3D "TPL_CALLBACK" + if self.tpl - 8 > 0: + result +=3D f' + {self.tpl - 8:d}' + elif self.tpl < 31: + result =3D "TPL_NOTIFY" + if self.tpl - 16 > 0: + result +=3D f' + {self.tpl - 16:d}' + elif self.tpl =3D=3D 31: + result =3D "TPL_HIGH_LEVEL" + else: + result =3D f'Invalid TPL =3D {self.tpl:d}' + return result + + +class EfiBootMode: + ''' + Class to return human readable string for EFI_BOOT_MODE + + Methods + ----------- + to_str(boot_mode, default) + return string for boot_mode, and return default if there is not a + match. + ''' + + EFI_BOOT_MODE_dict =3D { + 0x00: "BOOT_WITH_FULL_CONFIGURATION", + 0x01: "BOOT_WITH_MINIMAL_CONFIGURATION", + 0x02: "BOOT_ASSUMING_NO_CONFIGURATION_CHANGES", + 0x03: "BOOT_WITH_FULL_CONFIGURATION_PLUS_DIAGNOSTICS", + 0x04: "BOOT_WITH_DEFAULT_SETTINGS", + 0x05: "BOOT_ON_S4_RESUME", + 0x06: "BOOT_ON_S5_RESUME", + 0x07: "BOOT_WITH_MFG_MODE_SETTINGS", + 0x10: "BOOT_ON_S2_RESUME", + 0x11: "BOOT_ON_S3_RESUME", + 0x12: "BOOT_ON_FLASH_UPDATE", + 0x20: "BOOT_IN_RECOVERY_MODE", + } + + def __init__(self, boot_mode): + self._boot_mode =3D boot_mode + + def __str__(self): + return self.to_str(self._boot_mode) + + @classmethod + def to_str(cls, boot_mode, default=3D''): + return cls.EFI_BOOT_MODE_dict.get(boot_mode, default) + + +class EfiStatusClass: + ''' + Class to decode EFI_STATUS to a human readable string. You need to + pass in pointer_width to get the corret value since the EFI_STATUS + code values are different based on the sizeof UINTN. The default is + sizeof(UINTN) =3D=3D 8. + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94 + _dict_ : dictionary + dictionary of EFI_STATUS that has beed updated to match + pointer_width. + + Methods + ----------- + patch_dictionary(pointer_width) + + to_str(status, default) + ''' + + _dict_ =3D {} + _EFI_STATUS_UINT32_dict =3D { + 0: "Success", + 1: "Warning Unknown Glyph", + 2: "Warning Delete Failure", + 3: "Warning Write Failure", + 4: "Warning Buffer Too Small", + 5: "Warning Stale Data", + 6: "Warngin File System", + (0x20000000 | 0): "Warning interrupt source pending", + (0x20000000 | 1): "Warning interrupt source quiesced", + + (0x80000000 | 1): "Load Error", + (0x80000000 | 2): "Invalid Parameter", + (0x80000000 | 3): "Unsupported", + (0x80000000 | 4): "Bad Buffer Size", + (0x80000000 | 5): "Buffer Too Small", + (0x80000000 | 6): "Not Ready", + (0x80000000 | 7): "Device Error", + (0x80000000 | 8): "Write Protected", + (0x80000000 | 9): "Out of Resources", + (0x80000000 | 10): "Volume Corrupt", + (0x80000000 | 11): "Volume Full", + (0x80000000 | 12): "No Media", + (0x80000000 | 13): "Media changed", + (0x80000000 | 14): "Not Found", + (0x80000000 | 15): "Access Denied", + (0x80000000 | 16): "No Response", + (0x80000000 | 17): "No mapping", + (0x80000000 | 18): "Time out", + (0x80000000 | 19): "Not started", + (0x80000000 | 20): "Already started", + (0x80000000 | 21): "Aborted", + (0x80000000 | 22): "ICMP Error", + (0x80000000 | 23): "TFTP Error", + (0x80000000 | 24): "Protocol Error", + (0x80000000 | 25): "Incompatible Version", + (0x80000000 | 26): "Security Violation", + (0x80000000 | 27): "CRC Error", + (0x80000000 | 28): "End of Media", + (0x80000000 | 31): "End of File", + (0x80000000 | 32): "Invalid Language", + (0x80000000 | 33): "Compromised Data", + (0x80000000 | 35): "HTTP Error", + + (0xA0000000 | 0): "Interrupt Pending", + } + + def __init__(self, status=3DNone, pointer_width=3D8): + self.status =3D status + # this will convert to 64-bit version if needed + self.patch_dictionary(pointer_width) + + def __str__(self): + return self.to_str(self.status) + + @classmethod + def to_str(cls, status, default=3D''): + return cls._dict_.get(status, default) + + @classmethod + def patch_dictionary(cls, pointer_width): + '''Patch UINTN upper bits like values ''' + + if cls._dict_: + # only patch the class variable once + return False + + if pointer_width =3D=3D 4: + cls._dict =3D cls._EFI_STATUS_UINT32_dict + elif pointer_width =3D=3D 8: + for key, value in cls._EFI_STATUS_UINT32_dict.items(): + mask =3D (key & 0xE0000000) << 32 + new_key =3D (key & 0x1FFFFFFF) | mask + cls._dict_[new_key] =3D value + return True + else: + return False + + +class GuidNames: + ''' + Class to expose the C names of EFI_GUID's. The _dict_ starts with + common EFI System Table entry EFI_GUID's. _dict_ can get updated with = the + build generated Guid.xref file if a path to a module is passed + into add_build_guid_file(). If symbols are loaded for any module + in the build the path the build product should imply the + relative location of that builds Guid.xref file. + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94---- + _dict_ : dictionary + dictionary of EFI_GUID (uuid) strings to C global names + + Methods + ------- + to_uuid(uuid) + convert a hex UUID string or bytearray to a uuid.UUID + to_name(uuid) + convert a UUID string to a C global constant name. + to_guid(guid_name) + convert a C global constant EFI_GUID name to uuid hex string. + is_guid_str(name) + name is a hex UUID string. + Example: 49152E77-1ADA-4764-B7A2-7AFEFED95E8B + + to_c_guid(value) + convert a uuid.UUID or UUID string to a c_guid string + (see is_c_guid()) + from_c_guid(value) + covert a C guid string to a hex UUID string. + is_c_guid(name) + name is the C initialization value for an EFI_GUID. Example: + { 0x414e6bdd, 0xe47b, 0x47cc, { 0xb2, 0x44, 0xbb, 0x61, + 0x02, 0x0c, 0xf5, 0x16 }} + + add_build_guid_file(module_path, custom_file): + assume module_path is an edk2 build product and load the Guid.xref + file from that build to fill in _dict_. If you know the path and + file name of a custom Guid.xref you can pass it in as custom_file. + + ''' + _dict_ =3D { # Common EFI System Table values + '05AD34BA-6F02-4214-952E-4DA0398E2BB9': + 'gEfiDxeServicesTableGuid', + '7739F24C-93D7-11D4-9A3A-0090273FC14D': + 'gEfiHobListGuid', + '4C19049F-4137-4DD3-9C10-8B97A83FFDFA': + 'gEfiMemoryTypeInformationGuid', + '49152E77-1ADA-4764-B7A2-7AFEFED95E8B': + 'gEfiDebugImageInfoTableGuid', + '060CC026-4C0D-4DDA-8F41-595FEF00A502': + 'gMemoryStatusCodeRecordGuid', + 'EB9D2D31-2D88-11D3-9A16-0090273FC14D': + 'gEfiSmbiosTableGuid', + 'EB9D2D30-2D88-11D3-9A16-0090273FC14D': + 'gEfiAcpi10TableGuid', + '8868E871-E4F1-11D3-BC22-0080C73C8881': + 'gEfiAcpi20TableGuid', + } + + guid_files =3D [] + + def __init__(self, uuid=3DNone, pointer_width=3D8): + self.uuid =3D None if uuid is None else self.to_uuid(uuid) + + def __str__(self): + if self.uuid is None: + result =3D '' + for key, value in GuidNames._dict_.items(): + result +=3D f'{key}: {value}\n' + else: + result =3D self.to_name(self.uuid) + + return result + + @classmethod + def to_uuid(cls, obj): + try: + return uuid.UUID(bytes_le=3Dbytes(obj)) + except (ValueError, TypeError): + try: + return uuid.UUID(bytes_le=3Dobj) + except (ValueError, TypeError): + return uuid.UUID(obj) + + @classmethod + def to_name(cls, uuid): + if not isinstance(uuid, str): + uuid =3D str(uuid) + if cls.is_c_guid(uuid): + uuid =3D cls.from_c_guid(uuid) + return cls._dict_.get(uuid.upper(), uuid.upper()) + + @classmethod + def to_guid(cls, guid_name): + for key, value in cls._dict_.items(): + if guid_name =3D=3D value: + return key.upper() + else: + raise KeyError(key) + + @classmethod + def is_guid_str(cls, name): + if not isinstance(name, str): + return False + return name.count('-') >=3D 4 + + @classmethod + def to_c_guid(cls, value): + if isinstance(value, uuid.UUID): + guid =3D value + else: + guid =3D uuid.UUID(value) + + (data1, data2, data3, + data4_0, data4_1, data4_2, data4_3, + data4_4, data4_5, data4_6, data4_7) =3D struct.unpack( + '/Build/OvmfX64/DEBUG_XCODE5/X64/../DxeCore.dll + # Walk backwards looking for a toolchain like name. + # Then look for GUID database: + # Build/OvmfX64//DEBUG_XCODE5/FV/Guid.xref + for i in reversed(module_path.split(os.sep)): + if (i.startswith('DEBUG_') or + i.startswith('RELEASE_') or + i.startswith('NOOPT_')): + build_root =3D os.path.join( + module_path.rsplit(i, 1)[0], i) + break + + xref =3D os.path.join(build_root, 'FV', 'Guid.xref') + + if xref in cls.guid_files: + # only processes the file one time + return True + + with open(xref) as f: + content =3D f.readlines() + cls.guid_files.append(xref) + + for lines in content: + try: + if cls.is_guid_str(lines): + # a regex would be more pedantic + words =3D lines.split() + cls._dict_[words[0].upper()] =3D words[1].strip('\= n') + except ValueError: + pass + + return True + + return False + + +class EFI_HOB_GENERIC_HEADER(LittleEndianStructure): + _fields_ =3D [ + ('HobType', c_uint16), + ('HobLength', c_uint16), + ('Reserved', c_uint32) + ] + + +class EFI_HOB_HANDOFF_INFO_TABLE(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('Version', c_uint32), + ('BootMode', c_uint32), + ('EfiMemoryTop', c_uint64), + ('EfiMemoryBottom', c_uint64), + ('EfiFreeMemoryTop', c_uint64), + ('EfiFreeMemoryBottom', c_uint64), + ('EfiEndOfHobList', c_uint64), + ] + + +class EFI_HOB_MEMORY_ALLOCATION(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('Name', EFI_GUID), + ('MemoryBaseAddress', c_uint64), + ('MemoryLength', c_uint64), + ('MemoryType', c_uint32), + ('Reserved', c_uint32), + ] + + +class EFI_HOB_RESOURCE_DESCRIPTOR(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('Owner', EFI_GUID), + ('ResourceType', c_uint32), + ('ResourceAttribute', c_uint32), + ('PhysicalStart', c_uint64), + ('ResourceLength', c_uint64), + ] + + +class EFI_HOB_GUID_TYPE(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('Name', EFI_GUID), + ] + + +class EFI_HOB_FIRMWARE_VOLUME(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('BaseAddress', c_uint64), + ('Length', c_uint64), + ] + + +class EFI_HOB_CPU(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('SizeOfMemorySpace', c_uint8), + ('SizeOfIoSpace', c_uint8), + ('Reserved', ARRAY(c_uint8, 6)), + ] + + +class EFI_HOB_MEMORY_POOL(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ] + + +class EFI_HOB_FIRMWARE_VOLUME2(LittleEndianStructure): + _fields_ =3D [ + ('Header', EFI_HOB_GENERIC_HEADER), + ('BaseAddress', c_uint64), + ('Length', c_uint64), + ('FvName', EFI_GUID), + ('FileName', EFI_GUID) + ] + + +class EFI_HOB_FIRMWARE_VOLUME3(LittleEndianStructure): + _fields_ =3D [ + ('HobType', c_uint16), + ('HobLength', c_uint16), + ('Reserved', c_uint32), + ('BaseAddress', c_uint64), + ('Length', c_uint64), + ('AuthenticationStatus', c_uint32), + ('ExtractedFv', c_uint8), + ('FvName', EFI_GUID), + ('FileName', EFI_GUID), + ] + + +class EFI_HOB_UEFI_CAPSULE(LittleEndianStructure): + _fields_ =3D [ + ('HobType', c_uint16), + ('HobLength', c_uint16), + ('Reserved', c_uint32), + ('BaseAddress', c_uint64), + ('Length', c_uint64), + ] + + +class EfiHob: + ''' + Parse EFI Device Paths based on the edk2 C Structures defined above. + In the context of this class verbose means hexdump extra data. + + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94 + Hob : list + List of HOBs. Each entry contains the name, HOB type, HOB length, + the ctype struct for the HOB, and any extra data. + + Methods + ----------- + get_hob_by_type(hob_type) + return string that decodes the HOBs of hob_type. If hob_type is + None then return all HOBs. + ''' + + Hob =3D [] + verbose =3D False + + hob_dict =3D { + 1: EFI_HOB_HANDOFF_INFO_TABLE, + 2: EFI_HOB_MEMORY_ALLOCATION, + 3: EFI_HOB_RESOURCE_DESCRIPTOR, + 4: EFI_HOB_GUID_TYPE, + 5: EFI_HOB_FIRMWARE_VOLUME, + 6: EFI_HOB_CPU, + 7: EFI_HOB_MEMORY_POOL, + 9: EFI_HOB_FIRMWARE_VOLUME2, + 0xb: EFI_HOB_UEFI_CAPSULE, + 0xc: EFI_HOB_FIRMWARE_VOLUME3, + 0xffff: EFI_HOB_GENERIC_HEADER, + } + + def __init__(self, file, address=3DNone, verbose=3DFalse, count=3D1000= ): + self._file =3D file + EfiHob.verbose =3D verbose + + if len(EfiHob.Hob) !=3D 0 and address is None: + return + + if address is not None: + hob_ptr =3D address + else: + hob_ptr =3D EfiConfigurationTable(file).GetConfigTable( + '7739F24C-93D7-11D4-9A3A-0090273FC14D') + + self.read_hobs(hob_ptr) + + @ classmethod + def __str__(cls): + return cls.get_hob_by_type(None) + + @ classmethod + def get_hob_by_type(cls, hob_type): + result =3D "" + for (Name, HobType, HobLen, chob, extra) in cls.Hob: + if hob_type is not None: + if hob_type !=3D HobType: + continue + + result +=3D f'Type: {Name:s} (0x{HobType:01x}) Len: 0x{HobLen:= 03x}\n' + result +=3D ctype_to_str(chob, ' ', ['Reserved']) + if cls.verbose: + if extra is not None: + result +=3D hexdump(extra, ' ') + + return result + + def read_hobs(self, hob_ptr, count=3D1000): + if hob_ptr is None: + return + + try: + for _ in range(count): # while True + hdr, _ =3D self._ctype_read_ex(EFI_HOB_GENERIC_HEADER, hob= _ptr) + if hdr.HobType =3D=3D 0xffff: + break + + type_str =3D self.hob_dict.get( + hdr.HobType, EFI_HOB_GENERIC_HEADER) + hob, extra =3D self._ctype_read_ex( + type_str, hob_ptr, hdr.HobLength) + EfiHob.Hob.append( + (type(hob).__name__, + hdr.HobType, + hdr.HobLength, + hob, + extra)) + hob_ptr +=3D hdr.HobLength + except ValueError: + pass + + def _ctype_read_ex(self, ctype_struct, offset=3D0, rsize=3DNone): + if offset !=3D 0: + self._file.seek(offset) + + type_size =3D sizeof(ctype_struct) + size =3D rsize if rsize else type_size + data =3D self._file.read(size) + cdata =3D ctype_struct.from_buffer(bytearray(data)) + + if size > type_size: + return cdata, data[type_size:] + else: + return cdata, None + + +class EFI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Type', c_uint8), + ('SubType', c_uint8), + + # UINT8 Length[2] + # Cheat and use c_uint16 since we don't care about alignment + ('Length', c_uint16) + ] + + +class PCI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Function', c_uint8), + ('Device', c_uint8) + ] + + +class PCCARD_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('FunctionNumber', c_uint8), + ] + + +class MEMMAP_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('StartingAddress', c_uint64), + ('EndingAddress', c_uint64), + ] + + +class VENDOR_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Guid', EFI_GUID), + ] + + +class CONTROLLER_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('ControllerNumber', c_uint32), + ] + + +class BMC_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('InterfaceType', c_uint8), + ('BaseAddress', ARRAY(c_uint8, 8)), + ] + + +class BBS_BBS_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('DeviceType', c_uint16), + ('StatusFlag', c_uint16) + ] + + +class ACPI_HID_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('HID', c_uint32), + ('UID', c_uint32) + ] + + +class ACPI_EXTENDED_HID_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('HID', c_uint32), + ('UID', c_uint32), + ('CID', c_uint32) + ] + + +class ACPI_ADR_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('ARD', c_uint32) + ] + + +class ACPI_NVDIMM_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('NFITDeviceHandle', c_uint32) + ] + + +class ATAPI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("PrimarySecondary", c_uint8), + ("SlaveMaster", c_uint8), + ("Lun", c_uint16) + ] + + +class SCSI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Pun", c_uint16), + ("Lun", c_uint16) + ] + + +class FIBRECHANNEL_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Reserved", c_uint32), + ("WWN", c_uint64), + ("Lun", c_uint64) + ] + + +class F1394_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Reserved", c_uint32), + ("Guid", c_uint64) + ] + + +class USB_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("ParentPortNumber", c_uint8), + ("InterfaceNumber", c_uint8), + ] + + +class I2O_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Tid", c_uint32) + ] + + +class INFINIBAND_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("ResourceFlags", c_uint32), + ("PortGid", ARRAY(c_uint8, 16)), + ("ServiceId", c_uint64), + ("TargetPortId", c_uint64), + ("DeviceId", c_uint64) + ] + + +class UART_FLOW_CONTROL_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Guid", EFI_GUID), + ("FlowControlMap", c_uint32) + ] + + +class SAS_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Guid", EFI_GUID), + ("Reserved", c_uint32), + ("SasAddress", c_uint64), + ("Lun", c_uint64), + ("DeviceTopology", c_uint16), + ("RelativeTargetPort", c_uint16) + ] + + +class EFI_MAC_ADDRESS(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ("Addr", ARRAY(c_uint8, 32)), + ] + + +class MAC_ADDR_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('MacAddress', EFI_MAC_ADDRESS), + ('IfType', c_uint8) + ] + + +class IPv4_ADDRESS(LittleEndianStructure): + _fields_ =3D [ + ("Addr", ARRAY(c_uint8, 4)), + ] + + +class IPv4_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('LocalIpAddress', IPv4_ADDRESS), + ('RemoteIpAddress', IPv4_ADDRESS), + ('LocalPort', c_uint16), + ('RemotePort', c_uint16), + ('Protocol', c_uint16), + ('StaticIpAddress', c_uint8), + ('GatewayIpAddress', IPv4_ADDRESS), + ('SubnetMask', IPv4_ADDRESS) + ] + + +class IPv6_ADDRESS(LittleEndianStructure): + _fields_ =3D [ + ("Addr", ARRAY(c_uint8, 16)), + ] + + +class IPv6_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('LocalIpAddress', IPv6_ADDRESS), + ('RemoteIpAddress', IPv6_ADDRESS), + ('LocalPort', c_uint16), + ('RemotePort', c_uint16), + ('Protocol', c_uint16), + ('IpAddressOrigin', c_uint8), + ('PrefixLength', c_uint8), + ('GatewayIpAddress', IPv6_ADDRESS) + ] + + +class UART_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Reserved', c_uint32), + ('BaudRate', c_uint64), + ('DataBits', c_uint8), + ('Parity', c_uint8), + ('StopBits', c_uint8) + ] + + +class USB_CLASS_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('VendorId', c_uint16), + ('ProductId', c_uint16), + ('DeviceClass', c_uint8), + ('DeviceCSjblass', c_uint8), + ('DeviceProtocol', c_uint8), + ] + + +class USB_WWID_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('InterfaceNumber', c_uint16), + ('VendorId', c_uint16), + ('ProductId', c_uint16), + ] + + +class DEVICE_LOGICAL_UNIT_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Lun', c_uint8) + ] + + +class SATA_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('HBAPortNumber', c_uint16), + ('PortMultiplierPortNumber', c_uint16), + ('Lun', c_uint16), + ] + + +class ISCSI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('NetworkProtocol', c_uint16), + ('LoginOption', c_uint16), + ('Lun', c_uint64), + ('TargetPortalGroupTag', c_uint16), + ] + + +class VLAN_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("VlandId", c_uint16) + ] + + +class FIBRECHANNELEX_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Reserved", c_uint16), + ("WWN", ARRAY(c_uint8, 8)), + ("Lun", ARRAY(c_uint8, 8)), + ] + + +class SASEX_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("SasAddress", ARRAY(c_uint8, 8)), + ("Lun", ARRAY(c_uint8, 8)), + ("DeviceTopology", c_uint16), + ("RelativeTargetPort", c_uint16) + ] + + +class NVME_NAMESPACE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("NamespaceId", c_uint32), + ("NamespaceUuid", c_uint64) + ] + + +class DNS_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("IsIPv6", c_uint8), + ("DnsServerIp", IPv6_ADDRESS) + + ] + + +class UFS_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Pun", c_uint8), + ("Lun", c_uint8), + ] + + +class SD_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("SlotNumber", c_uint8) + ] + + +class BLUETOOTH_ADDRESS(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ("Address", ARRAY(c_uint8, 6)) + ] + + +class BLUETOOTH_LE_ADDRESS(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ("Format", c_uint8), + ("Class", c_uint16) + ] + + +class BLUETOOTH_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("BD_ADDR", BLUETOOTH_ADDRESS) + ] + + +class WIFI_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("SSId", ARRAY(c_uint8, 32)) + ] + + +class EMMC_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("SlotNumber", c_uint8) + ] + + +class BLUETOOTH_LE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("BD_ADDR", BLUETOOTH_LE_ADDRESS) + ] + + +class NVDIMM_NAMESPACE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("Uuid", EFI_GUID) + ] + + +class REST_SERVICE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("RESTService", c_uint8), + ("AccessMode", c_uint8) + ] + + +class REST_VENDOR_SERVICE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ("RESTService", c_uint8), + ("AccessMode", c_uint8), + ("Guid", EFI_GUID), + ] + + +class HARDDRIVE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('PartitionNumber', c_uint32), + ('PartitionStart', c_uint64), + ('PartitionSize', c_uint64), + ('Signature', ARRAY(c_uint8, 16)), + ('MBRType', c_uint8), + ('SignatureType', c_uint8) + ] + + +class CDROM_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('BootEntry', c_uint32), + ('PartitionStart', c_uint64), + ('PartitionSize', c_uint64) + ] + + +class MEDIA_PROTOCOL_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Protocol', EFI_GUID) + ] + + +class MEDIA_FW_VOL_FILEPATH_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('FvFileName', EFI_GUID) + ] + + +class MEDIA_FW_VOL_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('FvName', EFI_GUID) + ] + + +class MEDIA_RELATIVE_OFFSET_RANGE_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('Reserved', c_uint32), + ('StartingOffset', c_uint64), + ('EndingOffset', c_uint64) + ] + + +class MEDIA_RAM_DISK_DEVICE_PATH(LittleEndianStructure): + _pack_ =3D 1 + _fields_ =3D [ + ('Header', EFI_DEVICE_PATH), + ('StartingAddr', c_uint64), + ('EndingAddr', c_uint64), + ('TypeGuid', EFI_GUID), + ('Instance', c_uint16) + ] + + +class EfiDevicePath: + ''' + Parse EFI Device Paths based on the edk2 C Structures defined above. + In the context of this class verbose means hexdump extra data. + + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94 + DevicePath : list + List of devixe path instances. Each instance is a list of nodes + for the given Device Path instance. + + Methods + ----------- + device_path_node(address) + return the Device Path ctype hdr, ctype, and any extra data in + the Device Path node. This is just a single Device Path node, + not the entire Device Path. + device_path_node_str(address) + return the device path node (not the entire Device Path) as a stri= ng + ''' + + DevicePath =3D [] + + device_path_dict =3D { + # ( Type, SubType ) : Device Path C typedef + # HARDWARE_DEVICE_PATH + (1, 1): PCI_DEVICE_PATH, + (1, 2): PCCARD_DEVICE_PATH, + (1, 3): MEMMAP_DEVICE_PATH, + (1, 4): VENDOR_DEVICE_PATH, + (1, 5): CONTROLLER_DEVICE_PATH, + (1, 6): BMC_DEVICE_PATH, + + # ACPI_DEVICE_PATH + (2, 1): ACPI_HID_DEVICE_PATH, + (2, 2): ACPI_EXTENDED_HID_DEVICE_PATH, + (2, 3): ACPI_ADR_DEVICE_PATH, + (2, 4): ACPI_NVDIMM_DEVICE_PATH, + + # MESSAGING_DEVICE_PATH + (3, 1): ATAPI_DEVICE_PATH, + (3, 2): SCSI_DEVICE_PATH, + (3, 3): FIBRECHANNEL_DEVICE_PATH, + (3, 4): F1394_DEVICE_PATH, + (3, 5): USB_DEVICE_PATH, + (3, 6): I2O_DEVICE_PATH, + + (3, 9): INFINIBAND_DEVICE_PATH, + (3, 10): VENDOR_DEVICE_PATH, + (3, 11): MAC_ADDR_DEVICE_PATH, + (3, 12): IPv4_DEVICE_PATH, + (3, 13): IPv6_DEVICE_PATH, + (3, 14): UART_DEVICE_PATH, + (3, 15): USB_CLASS_DEVICE_PATH, + (3, 16): USB_WWID_DEVICE_PATH, + (3, 17): DEVICE_LOGICAL_UNIT_DEVICE_PATH, + (3, 18): SATA_DEVICE_PATH, + (3, 19): ISCSI_DEVICE_PATH, + (3, 20): VLAN_DEVICE_PATH, + (3, 21): FIBRECHANNELEX_DEVICE_PATH, + (3, 22): SASEX_DEVICE_PATH, + (3, 23): NVME_NAMESPACE_DEVICE_PATH, + (3, 24): DNS_DEVICE_PATH, + (3, 25): UFS_DEVICE_PATH, + (3, 26): SD_DEVICE_PATH, + (3, 27): BLUETOOTH_DEVICE_PATH, + (3, 28): WIFI_DEVICE_PATH, + (3, 29): EMMC_DEVICE_PATH, + (3, 30): BLUETOOTH_LE_DEVICE_PATH, + (3, 31): DNS_DEVICE_PATH, + (3, 32): NVDIMM_NAMESPACE_DEVICE_PATH, + + (3, 33): REST_SERVICE_DEVICE_PATH, + (3, 34): REST_VENDOR_SERVICE_DEVICE_PATH, + + # MEDIA_DEVICE_PATH + (4, 1): HARDDRIVE_DEVICE_PATH, + (4, 2): CDROM_DEVICE_PATH, + (4, 3): VENDOR_DEVICE_PATH, + (4, 4): EFI_DEVICE_PATH, + (4, 5): MEDIA_PROTOCOL_DEVICE_PATH, + (4, 6): MEDIA_FW_VOL_FILEPATH_DEVICE_PATH, + (4, 7): MEDIA_FW_VOL_DEVICE_PATH, + (4, 8): MEDIA_RELATIVE_OFFSET_RANGE_DEVICE_PATH, + (4, 9): MEDIA_RAM_DISK_DEVICE_PATH, + + # BBS_DEVICE_PATH + (5, 1): BBS_BBS_DEVICE_PATH, + + } + + guid_override_dict =3D { + uuid.UUID('37499A9D-542F-4C89-A026-35DA142094E4'): + UART_FLOW_CONTROL_DEVICE_PATH, + uuid.UUID('D487DDB4-008B-11D9-AFDC-001083FFCA4D'): + SAS_DEVICE_PATH, + } + + def __init__(self, file, ptr=3DNone, verbose=3DFalse, count=3D64): + ''' + Convert ptr into a list of Device Path nodes. If verbose also hexd= ump + extra data. + ''' + self._file =3D file + self._verbose =3D verbose + if ptr is None: + return + + try: + instance =3D [] + for _ in range(count): # while True + hdr, _ =3D self._ctype_read_ex(EFI_DEVICE_PATH, ptr) + if hdr.Length < sizeof(EFI_DEVICE_PATH): + # Not a valid device path + break + + if hdr.Type =3D=3D 0x7F: # END_DEVICE_PATH_TYPE + self.DevicePath.append(instance) + if hdr.SubType =3D=3D 0xFF: # END_ENTIRE_DEVICE_PATH_= SUBTYPE + break + if hdr.SubType =3D=3D 0x01: # END_INSTANCE_DEVICE_PAT= H_SUBTYPE + # start new device path instance + instance =3D [] + + type_str =3D self.device_path_dict.get( + (hdr.Type, hdr.SubType), EFI_DEVICE_PATH) + node, extra =3D self._ctype_read_ex(type_str, ptr, hdr.Len= gth) + if 'VENDOR_DEVICE_PATH' in type(node).__name__: + guid_type =3D self.guid_override_dict.get( + GuidNames.to_uuid(node.Guid), None) + if guid_type: + # use the ctype associated with the GUID + node, extra =3D self._ctype_read_ex( + guid_type, ptr, hdr.Length) + + instance.append((type(node).__name__, hdr.Type, + hdr.SubType, hdr.Length, node, extra)) + ptr +=3D hdr.Length + except ValueError: + pass + + def __str__(self): + ''' ''' + if not self.valid(): + return '' + + result =3D "" + for instance in self.DevicePath: + for (Name, Type, SubType, Length, cnode, extra) in instance: + result +=3D f'{Name:s} {Type:2d}:{SubType:2d} Len: {Length= :3d}\n' + result +=3D ctype_to_str(cnode, ' ', ['Reserved']) + if self._verbose: + if extra is not None: + result +=3D hexdump(extra, ' ') + result +=3D '\n' + + return result + + def valid(self): + return True if self.DevicePath else False + + def device_path_node(self, address): + try: + hdr, _ =3D self._ctype_read_ex(EFI_DEVICE_PATH, address) + if hdr.Length < sizeof(EFI_DEVICE_PATH): + return None, None, None + + type_str =3D self.device_path_dict.get( + (hdr.Type, hdr.SubType), EFI_DEVICE_PATH) + cnode, extra =3D self._ctype_read_ex(type_str, address, hdr.Le= ngth) + return hdr, cnode, extra + except ValueError: + return None, None, None + + def device_path_node_str(self, address, verbose=3DFalse): + hdr, cnode, extra =3D self.device_path_node(address) + if hdr is None: + return '' + + cname =3D type(cnode).__name__ + result =3D f'{cname:s} {hdr.Type:2d}:{hdr.SubType:2d} ' + result +=3D f'Len: 0x{hdr.Length:03x}\n' + result +=3D ctype_to_str(cnode, ' ', ['Reserved']) + if verbose: + if extra is not None: + result +=3D hexdump(extra, ' ') + + return result + + def _ctype_read_ex(self, ctype_struct, offset=3D0, rsize=3DNone): + if offset !=3D 0: + self._file.seek(offset) + + type_size =3D sizeof(ctype_struct) + size =3D rsize if rsize else type_size + data =3D self._file.read(size) + if data is None: + return None, None + + cdata =3D ctype_struct.from_buffer(bytearray(data)) + + if size > type_size: + return cdata, data[type_size:] + else: + return cdata, None + + +class EfiConfigurationTable: + ''' + A class to abstract EFI Configuration Tables from gST->ConfigurationTa= ble + and gST->NumberOfTableEntries. Pass in the gST pointer from EFI, + likely you need to look up this address after you have loaded symbols + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94 + ConfigurationTableDict : dictionary + dictionary of EFI Configuration Table entries + + Methods + ----------- + GetConfigTable(uuid) + pass in VendorGuid and return VendorTable from EFI System Table + DebugImageInfo(table) + return tuple of load address and size of PE/COFF images + ''' + + ConfigurationTableDict =3D {} + + def __init__(self, file, gST_addr=3DNone): + self._file =3D file + if gST_addr is None: + # ToDo add code to search for gST via EFI_SYSTEM_TABLE_POINTER + return + + gST =3D self._ctype_read(EFI_SYSTEM_TABLE, gST_addr) + self.read_efi_config_table(gST.NumberOfTableEntries, + gST.ConfigurationTable, + self._ctype_read) + + @ classmethod + def __str__(cls): + '''return EFI_CONFIGURATION_TABLE entries as a string''' + result =3D "" + for key, value in cls.ConfigurationTableDict.items(): + result +=3D f'{GuidNames().to_name(key):>37s}: ' + result +=3D f'VendorTable =3D 0x{value:08x}\n' + + return result + + def _ctype_read(self, ctype_struct, offset=3D0): + '''ctype worker function to read data''' + if offset !=3D 0: + self._file.seek(offset) + + data =3D self._file.read(sizeof(ctype_struct)) + return ctype_struct.from_buffer(bytearray(data)) + + @ classmethod + def read_efi_config_table(cls, table_cnt, table_ptr, ctype_read): + '''Create a dictionary of EFI Configuration table entries''' + EmptryTables =3D EFI_CONFIGURATION_TABLE * table_cnt + Tables =3D ctype_read(EmptryTables, table_ptr) + for i in range(table_cnt): + cls.ConfigurationTableDict[str(GuidNames.to_uuid( + Tables[i].VendorGuid)).upper()] =3D Tables[i].VendorTable + + return cls.ConfigurationTableDict + + def GetConfigTable(self, uuid): + ''' Return VendorTable for VendorGuid (uuid.UUID) or None''' + return self.ConfigurationTableDict.get(uuid.upper()) + + def DebugImageInfo(self, table=3DNone): + ''' + Walk the debug image info table to find the LoadedImage protocols + for all the loaded PE/COFF images and return a list of load address + and image size. + ''' + ImageLoad =3D [] + + if table is None: + table =3D self.GetConfigTable('49152e77-1ada-4764-b7a2-7afefed= 95e8b') + + DbgInfoHdr =3D self._ctype_read(EFI_DEBUG_IMAGE_INFO_TABLE_HEADER,= table) + NormalImageArray =3D EFI_DEBUG_IMAGE_INFO * DbgInfoHdr.TableSize + NormalImageArray =3D self._ctype_read( + NormalImageArray, DbgInfoHdr.EfiDebugImageInfoTable) + for i in range(DbgInfoHdr.TableSize): + ImageInfo =3D self._ctype_read( + EFI_DEBUG_IMAGE_INFO_NORMAL, NormalImageArray[i].NormalIma= ge) + LoadedImage =3D self._ctype_read( + EFI_LOADED_IMAGE_PROTOCOL, + ImageInfo.LoadedImageProtocolInstance) + ImageLoad.append((LoadedImage.ImageBase, LoadedImage.ImageSize= )) + + return ImageLoad + + +class PeTeImage: + ''' + A class to abstract PE/COFF or TE image processing via passing in a + Python file like object. If you pass in an address the PE/COFF is pars= ed, + if you pass in NULL for an address then you get a class instance you c= an + use to search memory for a PE/COFF hader given a pc value. + + Attributes + =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94 + LoadAddress : int + Load address of the PE/COFF image + AddressOfEntryPoint : int + Address of the Entry point of the PE/COFF image + TextAddress : int + Start of the PE/COFF text section + DataAddress : int + Start of the PE/COFF data section + CodeViewPdb : str + File name of the symbols file + CodeViewUuid : uuid:UUID + GUID for "RSDS" Debug Directory entry, or Mach-O UUID for "MTOC" + + Methods + ----------- + pcToPeCoff(address, step, max_range, rom_range) + Given an address(pc) find the PE/COFF image it is in + sections_to_str() + return a string giving info for all the PE/COFF sections + ''' + + def __init__(self, file, address=3D0): + self._file =3D file + + # book keeping, but public + self.PeHdr =3D None + self.TeHdr =3D None + self.Machine =3D None + self.Subsystem =3D None + self.CodeViewSig =3D None + self.e_lfanew =3D 0 + self.NumberOfSections =3D 0 + self.Sections =3D None + + # Things debuggers may want to know + self.LoadAddress =3D 0 if address is None else address + self.EndLoadAddress =3D 0 + self.AddressOfEntryPoint =3D 0 + self.TextAddress =3D 0 + self.DataAddress =3D 0 + self.CodeViewPdb =3D None + self.CodeViewUuid =3D None + self.TeAdjust =3D 0 + + self.dir_name =3D { + 0: 'Export Table', + 1: 'Import Table', + 2: 'Resource Table', + 3: 'Exception Table', + 4: 'Certificate Table', + 5: 'Relocation Table', + 6: 'Debug', + 7: 'Architecture', + 8: 'Global Ptr', + 9: 'TLS Table', + 10: 'Load Config Table', + 11: 'Bound Import', + 12: 'IAT', + 13: 'Delay Import Descriptor', + 14: 'CLR Runtime Header', + 15: 'Reserved', + } + + if address is not None: + if self.maybe(): + self.parse() + + def __str__(self): + if self.PeHdr is None and self.TeHdr is None: + # no PE/COFF header found + return "" + + if self.CodeViewPdb: + pdb =3D f'{self.Machine}`{self.CodeViewPdb}' + else: + pdb =3D 'No Debug Info:' + + if self.CodeViewUuid: + guid =3D f'{self.CodeViewUuid}:' + else: + guid =3D '' + + slide =3D f'slide =3D {self.TeAdjust:d} ' if self.TeAdjust !=3D 0 = else ' ' + res =3D guid + f'{pdb} load =3D 0x{self.LoadAddress:08x} ' + slide + return res + + def _seek(self, offset): + """ + seek() relative to start of PE/COFF (TE) image + """ + self._file.seek(self.LoadAddress + offset) + + def _read_offset(self, size, offset=3DNone): + """ + read() relative to start of PE/COFF (TE) image + if offset is not None then seek() before the read + """ + if offset is not None: + self._seek(offset) + + return self._file.read(size) + + def _read_ctype(self, ctype_struct, offset=3DNone): + data =3D self._read_offset(sizeof(ctype_struct), offset) + return ctype_struct.from_buffer(bytearray(data), 0) + + def _unsigned(self, i): + """return a 32-bit unsigned int (UINT32) """ + return int.from_bytes(i, byteorder=3D'little', signed=3DFalse) + + def pcToPeCoff(self, + address, + step=3DNone, + max_range=3DNone, + rom_range=3D[0xFE800000, 0xFFFFFFFF]): + """ + Given an address search backwards for PE/COFF (TE) header + For DXE 4K is probably OK + For PEI you might have to search every 4 bytes. + """ + if step is None: + step =3D 0x1000 + + if max_range is None: + max_range =3D 0x200000 + + if address in range(*rom_range): + # The XIP code in the ROM ends up 4 byte aligned. + step =3D 4 + max_range =3D min(max_range, 0x100000) + + # Align address to page boundary for memory image search. + address =3D address & ~(step-1) + # Search every step backward + offset_range =3D list(range(0, min(max_range, address), step)) + for offset in offset_range: + if self.maybe(address - offset): + if self.parse(): + return True + + return False + + def maybe(self, offset=3DNone): + """Probe to see if this offset is likely a PE/COFF or TE file """ + self.LoadAddress =3D 0 + e_magic =3D self._read_offset(2, offset) + header_ok =3D e_magic =3D=3D b'MZ' or e_magic =3D=3D b'VZ' + if offset is not None and header_ok: + self.LoadAddress =3D offset + return header_ok + + def parse(self): + """Parse PE/COFF (TE) debug directory entry """ + DosHdr =3D self._read_ctype(EFI_IMAGE_DOS_HEADER, 0) + if DosHdr.e_magic =3D=3D self._unsigned(b'VZ'): + # TE image + self.TeHdr =3D self._read_ctype(EFI_TE_IMAGE_HEADER, 0) + + self.TeAdjust =3D sizeof(self.TeHdr) - self.TeHdr.StrippedSize + self.Machine =3D image_machine_dict.get(self.TeHdr.Machine, No= ne) + self.Subsystem =3D self.TeHdr.Subsystem + self.AddressOfEntryPoint =3D self.TeHdr.AddressOfEntryPoint + + debug_dir_size =3D self.TeHdr.DataDirectoryDebug.Size + debug_dir_offset =3D (self.TeAdjust + + self.TeHdr.DataDirectoryDebug.VirtualAddre= ss) + else: + if DosHdr.e_magic =3D=3D self._unsigned(b'MZ'): + self.e_lfanew =3D DosHdr.e_lfanew + else: + self.e_lfanew =3D 0 + + self.PeHdr =3D self._read_ctype( + EFI_IMAGE_NT_HEADERS64, self.e_lfanew) + if self.PeHdr.Signature !=3D self._unsigned(b'PE\0\0'): + return False + + if self.PeHdr.OptionalHeader.Magic =3D=3D \ + EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC: + self.PeHdr =3D self._read_ctype( + EFI_IMAGE_NT_HEADERS32, self.e_lfanew) + + if self.PeHdr.OptionalHeader.NumberOfRvaAndSizes <=3D \ + DIRECTORY_DEBUG: + return False + + self.Machine =3D image_machine_dict.get( + self.PeHdr.FileHeader.Machine, None) + self.Subsystem =3D self.PeHdr.OptionalHeader.Subsystem + self.AddressOfEntryPoint =3D \ + self.PeHdr.OptionalHeader.AddressOfEntryPoint + self.TeAdjust =3D 0 + + debug_dir_size =3D self.PeHdr.OptionalHeader.DataDirectory[ + DIRECTORY_DEBUG].Size + debug_dir_offset =3D self.PeHdr.OptionalHeader.DataDirectory[ + DIRECTORY_DEBUG].VirtualAddress + + if self.Machine is None or self.Subsystem not in [0, 10, 11, 12]: + return False + + self.AddressOfEntryPoint +=3D self.LoadAddress + + self.sections() + return self.processDebugDirEntry(debug_dir_offset, debug_dir_size) + + def sections(self): + '''Parse the PE/COFF (TE) section table''' + if self.Sections is not None: + return + elif self.TeHdr is not None: + self.NumberOfSections =3D self.TeHdr.NumberOfSections + offset =3D sizeof(EFI_TE_IMAGE_HEADER) + elif self.PeHdr is not None: + self.NumberOfSections =3D self.PeHdr.FileHeader.NumberOfSectio= ns + offset =3D sizeof(c_uint32) + \ + sizeof(EFI_IMAGE_FILE_HEADER) + offset +=3D self.PeHdr.FileHeader.SizeOfOptionalHeader + offset +=3D self.e_lfanew + else: + return + + self.Sections =3D EFI_IMAGE_SECTION_HEADER * self.NumberOfSections + self.Sections =3D self._read_ctype(self.Sections, offset) + + for i in range(self.NumberOfSections): + name =3D str(self.Sections[i].Name, 'ascii', 'ignore') + addr =3D self.Sections[i].VirtualAddress + addr +=3D self.LoadAddress + self.TeAdjust + if name =3D=3D '.text': + self.TextAddress =3D addr + elif name =3D=3D '.data': + self.DataAddress =3D addr + + end_addr =3D addr + self.Sections[i].VirtualSize - 1 + if end_addr > self.EndLoadAddress: + self.EndLoadAddress =3D end_addr + + def sections_to_str(self): + # return text summary of sections + # name virt addr (virt size) flags:Characteristics + result =3D '' + for i in range(self.NumberOfSections): + name =3D str(self.Sections[i].Name, 'ascii', 'ignore') + result +=3D f'{name:8s} ' + result +=3D f'0x{self.Sections[i].VirtualAddress:08X} ' + result +=3D f'(0x{self.Sections[i].VirtualSize:05X}) ' + result +=3D f'flags:0x{self.Sections[i].Characteristics:08X}\n' + + return result + + def directory_to_str(self): + result =3D '' + if self.TeHdr: + debug_size =3D self.TeHdr.DataDirectoryDebug.Size + if debug_size > 0: + debug_offset =3D (self.TeAdjust + + self.TeHdr.DataDirectoryDebug.VirtualAdd= ress) + result +=3D f"Debug 0x{debug_offset:08X} 0x{debug_size}\n" + + relocation_size =3D self.TeHdr.DataDirectoryBaseReloc.Size + if relocation_size > 0: + relocation_offset =3D ( + self.TeAdjust + + self.TeHdr.DataDirectoryBaseReloc.VirtualAddress) + result +=3D f'Relocation 0x{relocation_offset:08X} ' + result +=3D f' 0x{relocation_size}\n' + + elif self.PeHdr: + for i in range(self.PeHdr.OptionalHeader.NumberOfRvaAndSizes): + size =3D self.PeHdr.OptionalHeader.DataDirectory[i].Size + if size =3D=3D 0: + continue + + virt_addr =3D self.PeHdr.OptionalHeader.DataDirectory[ + i].VirtualAddress + name =3D self.dir_name.get(i, '?') + result +=3D f'{name:s} 0x{virt_addr:08X} 0x{size:X}\n' + + return result + + def processDebugDirEntry(self, virt_address, virt_size): + """Process PE/COFF Debug Directory Entry""" + if (virt_address =3D=3D 0 or + virt_size < sizeof(EFI_IMAGE_DEBUG_DIRECTORY_ENTRY)): + return False + + data =3D bytearray(self._read_offset(virt_size, virt_address)) + for offset in range(0, + virt_size, + sizeof(EFI_IMAGE_DEBUG_DIRECTORY_ENTRY)): + DirectoryEntry =3D EFI_IMAGE_DEBUG_DIRECTORY_ENTRY.from_buffer( + data[offset:]) + if DirectoryEntry.Type !=3D 2: + continue + + entry =3D self._read_offset( + DirectoryEntry.SizeOfData, DirectoryEntry.RVA + self.TeAdj= ust) + self.CodeViewSig =3D entry[:4] + if self.CodeViewSig =3D=3D b'MTOC': + self.CodeViewUuid =3D uuid.UUID(bytes_le=3Dentry[4:4+16]) + PdbOffset =3D 20 + elif self.CodeViewSig =3D=3D b'RSDS': + self.CodeViewUuid =3D uuid.UUID(bytes_le=3Dentry[4:4+16]) + PdbOffset =3D 24 + elif self.CodeViewSig =3D=3D b'NB10': + PdbOffset =3D 16 + else: + continue + + # can't find documentation about Pdb string encoding? + # guessing utf-8 since that will match file systems in macOS + # and Linux Windows is UTF-16, or ANSI adjusted for local. + # We might need a different value for Windows here? + self.CodeViewPdb =3D entry[PdbOffset:].split(b'\x00')[ + 0].decode('utf-8') + return True + return False + + +def main(): + '''Process arguments as PE/COFF files''' + for fname in sys.argv[1:]: + with open(fname, 'rb') as f: + image =3D PeTeImage(f) + print(image) + res =3D f'EntryPoint =3D 0x{image.AddressOfEntryPoint:08x} ' + res +=3D f'TextAddress =3D 0x{image.TextAddress:08x} ' + res +=3D f'DataAddress =3D 0x{image.DataAddress:08x}' + print(res) + print(image.sections_to_str()) + print('Data Directories:') + print(image.directory_to_str()) + + +if __name__ =3D=3D "__main__": + main() --=20 2.34.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#87799): https://edk2.groups.io/g/devel/message/87799 Mute This Topic: https://groups.io/mt/89937664/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Wed May 15 12:05:13 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+87800+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+87800+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=quicinc.com ARC-Seal: i=1; a=rsa-sha256; t=1647894076; cv=none; d=zohomail.com; s=zohoarc; b=K+6YQMzdlNV7flAnLnafU+hKGOAuR2Vv8RIlwmlDvGfFLt5ecN6H9WKXse+PNDPXRyaJXUbrZHEEhAROTGcOUCdeuILYFkOZ8LoyH6PgKaE1JX1RQeqGVsG28Ywn9kOa8PDs883rz66T2yet9x79YPanSKJU/GRGwyypl5/vSCI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1647894076; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=At7comavRklO3t0k16NYt1vZNbRwhs7AM9F1v/qH3PA=; b=WgT6G8TqA5Wq35Qx7arpKm+pTQ4p5eRj69KreX5K8Bpfh79RaZavBQ5oYoQzpOPVZUfKtLG3IkCYtnL8YnGhDQYovBhjz3i+0/1BYXM4QjXgVbBXe3Bgr39n2p5LgarAUs25RH6mIMrXLUcfQBSM8XSdsXT6XcQeOW/DrGfvqRM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+87800+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1647894076349578.9182181501061; Mon, 21 Mar 2022 13:21:16 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id flSeYY1788612xH66BUK3Llb; Mon, 21 Mar 2022 13:21:16 -0700 X-Received: from alexa-out-sd-01.qualcomm.com (alexa-out-sd-01.qualcomm.com [199.106.114.38]) by mx.groups.io with SMTP id smtpd.web09.849.1647894075374674017 for ; Mon, 21 Mar 2022 13:21:15 -0700 X-Received: from unknown (HELO ironmsg01-sd.qualcomm.com) ([10.53.140.141]) by alexa-out-sd-01.qualcomm.com with ESMTP; 21 Mar 2022 13:21:14 -0700 X-QCInternal: smtphost X-Received: from nasanex01c.na.qualcomm.com ([10.47.97.222]) by ironmsg01-sd.qualcomm.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Mar 2022 13:21:14 -0700 X-Received: from nalasex01a.na.qualcomm.com (10.47.209.196) by nasanex01c.na.qualcomm.com (10.47.97.222) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:13 -0700 X-Received: from linbox.ba.nuviainc.com (10.80.80.8) by nalasex01a.na.qualcomm.com (10.47.209.196) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:13 -0700 From: "Rebecca Cran" To: , Leif Lindholm , Michael D Kinney , Hao A Wu , Bob Feng , Liming Gao , Yuwei Chen CC: Rebecca Cran , Andrew Fish Subject: [edk2-devel] [PATCH v2 2/3] BaseTools: Scripts/efi_gdb.py: Add gdb EFI commands and pretty Print Date: Mon, 21 Mar 2022 14:20:47 -0600 Message-ID: <20220321202048.13567-3-quic_rcran@quicinc.com> In-Reply-To: <20220321202048.13567-1-quic_rcran@quicinc.com> References: <20220321202048.13567-1-quic_rcran@quicinc.com> MIME-Version: 1.0 X-Originating-IP: [10.80.80.8] X-ClientProxiedBy: nasanex01a.na.qualcomm.com (10.52.223.231) To nalasex01a.na.qualcomm.com (10.47.209.196) Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,quic_rcran@quicinc.com X-Gm-Message-State: 41SSKs7SXYdjMntymEiIyNwyx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1647894076; bh=9PeTu9PuttgQlVmJt41G0xxFyxUD15puvzkx2tmS4ic=; h=CC:Content-Type:Date:From:Reply-To:Subject:To; b=oev9uieVfuut4J1NLOmE1rBSacTS+NXoYUjOz3Wegqu4HtV+fPRjhU4FYOuICPdFoNm UvE9rI0JJCIIVZ9f7cqgwOLH+A/vEUa+/krXc3nnbvCTJKmYJFcM+ySBPVcRxlC0RJSUo 8akInBXG4HWajThGQnTrzG6kQfs6sxsfDD8= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1647894078619100008 Content-Type: text/plain; charset="utf-8" https://bugzilla.tianocore.org/show_bug.cgi?id=3D3500 Use efi_debugging.py Python Classes to implement EFI gdb commands: (gdb) help efi Commands for debugging EFI. efi List of efi subcommands: efi devicepath -- Display an EFI device path. efi guid -- Display info about EFI GUID's. efi hob -- Dump EFI HOBs. Type 'hob -h' for more info. efi symbols -- Load Symbols for EFI. Type 'efi_symbols -h' for more info. efi table -- Dump EFI System Tables. Type 'table -h' for more info. This module is coded against a generic gdb remote serial stub. It should work with QEMU, JTAG debugger, or a generic EFI gdb remote serial stub. No modifications of EFI is required to load symbols. Example usage: OvmfPkg/build.sh qemu -gdb tcp::9000 gdb -ex "target remote localhost:9000" -ex "source efi_gdb.py" Cc: Leif Lindholm Cc: Michael D Kinney Cc: Hao A Wu Cc: Bob Feng Cc: Liming Gao Cc: Yuwei Chen Signed-off-by: Rebecca Cran Acked-by: Liming Gao Reviewed-by: Bob Feng --- BaseTools/Scripts/efi_gdb.py | 918 ++++++++++++++++++++ 1 file changed, 918 insertions(+) diff --git a/BaseTools/Scripts/efi_gdb.py b/BaseTools/Scripts/efi_gdb.py new file mode 100755 index 000000000000..e9bae8e9b913 --- /dev/null +++ b/BaseTools/Scripts/efi_gdb.py @@ -0,0 +1,918 @@ +#!/usr/bin/python3 +''' +Copyright 2021 (c) Apple Inc. All rights reserved. +SPDX-License-Identifier: BSD-2-Clause-Patent + +EFI gdb commands based on efi_debugging classes. + +Example usage: +OvmfPkg/build.sh qemu -gdb tcp::9000 +gdb -ex "target remote localhost:9000" -ex "source efi_gdb.py" + +(gdb) help efi +Commands for debugging EFI. efi + +List of efi subcommands: + +efi devicepath -- Display an EFI device path. +efi guid -- Display info about EFI GUID's. +efi hob -- Dump EFI HOBs. Type 'hob -h' for more info. +efi symbols -- Load Symbols for EFI. Type 'efi_symbols -h' for more info. +efi table -- Dump EFI System Tables. Type 'table -h' for more info. + +This module is coded against a generic gdb remote serial stub. It should w= ork +with QEMU, JTAG debugger, or a generic EFI gdb remote serial stub. + +If you are debugging with QEMU or a JTAG hardware debugger you can insert +a CpuDeadLoop(); in your code, attach with gdb, and then `p Index=3D1` to +step past. If you have a debug stub in EFI you can use CpuBreakpoint();. +''' + +from gdb.printing import RegexpCollectionPrettyPrinter +from gdb.printing import register_pretty_printer +import gdb +import os +import sys +import uuid +import optparse +import shlex + +# gdb will not import from the same path as this script. +# so lets fix that for gdb... +sys.path.append(os.path.dirname(os.path.abspath(__file__))) + +from efi_debugging import PeTeImage, patch_ctypes # noqa: E402 +from efi_debugging import EfiHob, GuidNames, EfiStatusClass # noqa: E402 +from efi_debugging import EfiBootMode, EfiDevicePath # noqa: E402 +from efi_debugging import EfiConfigurationTable, EfiTpl # noqa: E402 + + +class GdbFileObject(object): + '''Provide a file like object required by efi_debugging''' + + def __init__(self): + self.inferior =3D gdb.selected_inferior() + self.offset =3D 0 + + def tell(self): + return self.offset + + def read(self, size=3D-1): + if size =3D=3D -1: + # arbitrary default size + size =3D 0x1000000 + + try: + data =3D self.inferior.read_memory(self.offset, size) + except MemoryError: + data =3D bytearray(size) + assert False + if len(data) !=3D size: + raise MemoryError( + f'gdb could not read memory 0x{size:x}' + + f' bytes from 0x{self.offset:08x}') + else: + # convert memoryview object to a bytestring. + return data.tobytes() + + def readable(self): + return True + + def seek(self, offset, whence=3D0): + if whence =3D=3D 0: + self.offset =3D offset + elif whence =3D=3D 1: + self.offset +=3D offset + else: + # whence =3D=3D 2 is seek from end + raise NotImplementedError + + def seekable(self): + return True + + def write(self, data): + self.inferior.write_memory(self.offset, data) + return len(data) + + def writable(self): + return True + + def truncate(self, size=3DNone): + raise NotImplementedError + + def flush(self): + raise NotImplementedError + + def fileno(self): + raise NotImplementedError + + +class EfiSymbols: + """Class to manage EFI Symbols""" + + loaded =3D {} + stride =3D None + range =3D None + verbose =3D False + + def __init__(self, file=3DNone): + EfiSymbols.file =3D file if file else GdbFileObject() + + @ classmethod + def __str__(cls): + return ''.join(f'{value}\n' for value in cls.loaded.values()) + + @ classmethod + def configure_search(cls, stride, range=3DNone, verbose=3DFalse): + cls.stride =3D stride + cls.range =3D range + cls.verbose =3D verbose + + @ classmethod + def clear(cls): + cls.loaded =3D {} + + @ classmethod + def add_symbols_for_pecoff(cls, pecoff): + '''Tell lldb the location of the .text and .data sections.''' + + if pecoff.TextAddress in cls.loaded: + return 'Already Loaded: ' + try: + res =3D 'Loading Symbols Failed:' + res =3D gdb.execute('add-symbol-file ' + pecoff.CodeViewPdb + + ' ' + hex(pecoff.TextAddress) + + ' -s .data ' + hex(pecoff.DataAddress), + False, True) + + cls.loaded[pecoff.TextAddress] =3D pecoff + if cls.verbose: + print(f'\n{res:s}\n') + return '' + except gdb.error: + return res + + @ classmethod + def address_to_symbols(cls, address, reprobe=3DFalse): + ''' + Given an address search backwards for a PE/COFF (or TE) header + and load symbols. Return a status string. + ''' + if not isinstance(address, int): + address =3D int(address) + + pecoff =3D cls.address_in_loaded_pecoff(address) + if not reprobe and pecoff is not None: + # skip the probe of the remote + return f'{pecoff} is already loaded' + + pecoff =3D PeTeImage(cls.file, None) + if pecoff.pcToPeCoff(address, cls.stride, cls.range): + res =3D cls.add_symbols_for_pecoff(pecoff) + return f'{res}{pecoff}' + else: + return f'0x{address:08x} not in a PE/COFF (or TE) image' + + @ classmethod + def address_in_loaded_pecoff(cls, address): + if not isinstance(address, int): + address =3D int(address) + + for value in cls.loaded.values(): + if (address >=3D value.LoadAddress and + address <=3D value.EndLoadAddress): + return value + + return None + + @ classmethod + def unload_symbols(cls, address): + if not isinstance(address, int): + address =3D int(address) + + pecoff =3D cls.address_in_loaded_pecoff(address) + try: + res =3D 'Unloading Symbols Failed:' + res =3D gdb.execute( + f'remove-symbol-file -a {hex(pecoff.TextAddress):s}', + False, True) + del cls.loaded[pecoff.LoadAddress] + return res + except gdb.error: + return res + + +class CHAR16_PrettyPrinter(object): + + def __init__(self, val): + self.val =3D val + + def to_string(self): + if int(self.val) < 0x20: + return f"L'\\x{int(self.val):02x}'" + else: + return f"L'{chr(self.val):s}'" + + +class EFI_TPL_PrettyPrinter(object): + + def __init__(self, val): + self.val =3D val + + def to_string(self): + return str(EfiTpl(int(self.val))) + + +class EFI_STATUS_PrettyPrinter(object): + + def __init__(self, val): + self.val =3D val + + def to_string(self): + status =3D int(self.val) + return f'{str(EfiStatusClass(status)):s} (0x{status:08x})' + + +class EFI_BOOT_MODE_PrettyPrinter(object): + + def __init__(self, val): + self.val =3D val + + def to_string(self): + return str(EfiBootMode(int(self.val))) + + +class EFI_GUID_PrettyPrinter(object): + """Print 'EFI_GUID' as 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'""" + + def __init__(self, val): + self.val =3D val + + def to_string(self): + # if we could get a byte like object of *(unsigned char (*)[16]) + # then we could just use uuid.UUID() to convert + Data1 =3D int(self.val['Data1']) + Data2 =3D int(self.val['Data2']) + Data3 =3D int(self.val['Data3']) + Data4 =3D self.val['Data4'] + guid =3D f'{Data1:08X}-{Data2:04X}-' + guid +=3D f'{Data3:04X}-' + guid +=3D f'{int(Data4[0]):02X}{int(Data4[1]):02X}-' + guid +=3D f'{int(Data4[2]):02X}{int(Data4[3]):02X}' + guid +=3D f'{int(Data4[4]):02X}{int(Data4[5]):02X}' + guid +=3D f'{int(Data4[6]):02X}{int(Data4[7]):02X}' + return str(GuidNames(guid)) + + +def build_pretty_printer(): + # Turn off via: disable pretty-printer global EFI + pp =3D RegexpCollectionPrettyPrinter("EFI") + # you can also tell gdb `x/sh
` to print CHAR16 string + pp.add_printer('CHAR16', '^CHAR16$', CHAR16_PrettyPrinter) + pp.add_printer('EFI_BOOT_MODE', '^EFI_BOOT_MODE$', + EFI_BOOT_MODE_PrettyPrinter) + pp.add_printer('EFI_GUID', '^EFI_GUID$', EFI_GUID_PrettyPrinter) + pp.add_printer('EFI_STATUS', '^EFI_STATUS$', EFI_STATUS_PrettyPrinter) + pp.add_printer('EFI_TPL', '^EFI_TPL$', EFI_TPL_PrettyPrinter) + return pp + + +class EfiDevicePathCmd (gdb.Command): + """Display an EFI device path. Type 'efi devicepath -h' for more info"= "" + + def __init__(self): + super(EfiDevicePathCmd, self).__init__( + "efi devicepath", gdb.COMMAND_NONE) + + self.file =3D GdbFileObject() + + def create_options(self, arg, from_tty): + usage =3D "usage: %prog [options] [arg]" + description =3D ( + "Command that can load EFI PE/COFF and TE image symbols. ") + + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi devicepath', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'hex dump extra data', + default=3DFalse) + + self.parser.add_option( + '-n', + '--node', + action=3D'store_true', + dest=3D'node', + help=3D'dump a single device path node', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + return self.parser.parse_args(shlex.split(arg)) + + def invoke(self, arg, from_tty): + '''gdb command to dump EFI device paths''' + + try: + (options, _) =3D self.create_options(arg, from_tty) + if options.help: + self.parser.print_help() + return + + dev_addr =3D int(gdb.parse_and_eval(arg)) + except ValueError: + print("Invalid argument!") + return + + if options.node: + print(EfiDevicePath( + self.file).device_path_node_str(dev_addr, + options.verbose)) + else: + device_path =3D EfiDevicePath(self.file, dev_addr, options.ver= bose) + if device_path.valid(): + print(device_path) + + +class EfiGuidCmd (gdb.Command): + """Display info about EFI GUID's. Type 'efi guid -h' for more info""" + + def __init__(self): + super(EfiGuidCmd, self).__init__("efi guid", + gdb.COMMAND_NONE, + gdb.COMPLETE_EXPRESSION) + self.file =3D GdbFileObject() + + def create_options(self, arg, from_tty): + usage =3D "usage: %prog [options] [arg]" + description =3D ( + "Show EFI_GUID values and the C name of the EFI_GUID variables" + "in the C code. If symbols are loaded the Guid.xref file" + "can be processed and the complete GUID database can be shown." + "This command also suports generating new GUID's, and showing" + "the value used to initialize the C variable.") + + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi guid', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-n', + '--new', + action=3D'store_true', + dest=3D'new', + help=3D'Generate a new GUID', + default=3DFalse) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'Also display GUID C structure values', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + return self.parser.parse_args(shlex.split(arg)) + + def invoke(self, arg, from_tty): + '''gdb command to dump EFI System Tables''' + + try: + (options, args) =3D self.create_options(arg, from_tty) + if options.help: + self.parser.print_help() + return + if len(args) >=3D 1: + # guid { 0x414e6bdd, 0xe47b, 0x47cc, + # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }} + # this generates multiple args + guid =3D ' '.join(args) + except ValueError: + print('bad arguments!') + return + + if options.new: + guid =3D uuid.uuid4() + print(str(guid).upper()) + print(GuidNames.to_c_guid(guid)) + return + + if len(args) > 0: + if GuidNames.is_guid_str(arg): + # guid 05AD34BA-6F02-4214-952E-4DA0398E2BB9 + key =3D guid.upper() + name =3D GuidNames.to_name(key) + elif GuidNames.is_c_guid(arg): + # guid { 0x414e6bdd, 0xe47b, 0x47cc, + # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }} + key =3D GuidNames.from_c_guid(arg) + name =3D GuidNames.to_name(key) + else: + # guid gEfiDxeServicesTableGuid + name =3D guid + try: + key =3D GuidNames.to_guid(name) + name =3D GuidNames.to_name(key) + except ValueError: + return + + extra =3D f'{GuidNames.to_c_guid(key)}: ' if options.verbose e= lse '' + print(f'{key}: {extra}{name}') + + else: + for key, value in GuidNames._dict_.items(): + if options.verbose: + extra =3D f'{GuidNames.to_c_guid(key)}: ' + else: + extra =3D '' + print(f'{key}: {extra}{value}') + + +class EfiHobCmd (gdb.Command): + """Dump EFI HOBs. Type 'hob -h' for more info.""" + + def __init__(self): + super(EfiHobCmd, self).__init__("efi hob", gdb.COMMAND_NONE) + self.file =3D GdbFileObject() + + def create_options(self, arg, from_tty): + usage =3D "usage: %prog [options] [arg]" + description =3D ( + "Command that can load EFI PE/COFF and TE image symbols. ") + + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi hob', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-a', + '--address', + type=3D"int", + dest=3D'address', + help=3D'Parse HOBs from address', + default=3DNone) + + self.parser.add_option( + '-t', + '--type', + type=3D"int", + dest=3D'type', + help=3D'Only dump HOBS of his type', + default=3DNone) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'hex dump extra data', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + return self.parser.parse_args(shlex.split(arg)) + + def invoke(self, arg, from_tty): + '''gdb command to dump EFI System Tables''' + + try: + (options, _) =3D self.create_options(arg, from_tty) + if options.help: + self.parser.print_help() + return + except ValueError: + print('bad arguments!') + return + + if options.address: + try: + value =3D gdb.parse_and_eval(options.address) + address =3D int(value) + except ValueError: + address =3D None + else: + address =3D None + + hob =3D EfiHob(self.file, + address, + options.verbose).get_hob_by_type(options.type) + print(hob) + + +class EfiTablesCmd (gdb.Command): + """Dump EFI System Tables. Type 'table -h' for more info.""" + + def __init__(self): + super(EfiTablesCmd, self).__init__("efi table", gdb.COMMAND_NONE) + + self.file =3D GdbFileObject() + + def create_options(self, arg, from_tty): + usage =3D "usage: %prog [options] [arg]" + description =3D "Dump EFI System Tables. Requires symbols to be lo= aded" + + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi table', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + return self.parser.parse_args(shlex.split(arg)) + + def invoke(self, arg, from_tty): + '''gdb command to dump EFI System Tables''' + + try: + (options, _) =3D self.create_options(arg, from_tty) + if options.help: + self.parser.print_help() + return + except ValueError: + print('bad arguments!') + return + + gST =3D gdb.lookup_global_symbol('gST') + if gST is None: + print('Error: This command requires symbols for gST to be load= ed') + return + + table =3D EfiConfigurationTable( + self.file, int(gST.value(gdb.selected_frame()))) + if table: + print(table, '\n') + + +class EfiSymbolsCmd (gdb.Command): + """Load Symbols for EFI. Type 'efi symbols -h' for more info.""" + + def __init__(self): + super(EfiSymbolsCmd, self).__init__("efi symbols", + gdb.COMMAND_NONE, + gdb.COMPLETE_EXPRESSION) + self.file =3D GdbFileObject() + self.gST =3D None + self.efi_symbols =3D EfiSymbols(self.file) + + def create_options(self, arg, from_tty): + usage =3D "usage: %prog [options]" + description =3D ( + "Command that can load EFI PE/COFF and TE image symbols. " + "If you are having trouble in PEI try adding --pei. " + "Given any address search backward for the PE/COFF (or TE head= er) " + "and then parse the PE/COFF image to get debug info. " + "The address can come from the current pc, pc values in the " + "frame, or an address provided to the command" + "") + + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi symbols', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-a', + '--address', + type=3D"str", + dest=3D'address', + help=3D'Load symbols for image that contains address', + default=3DNone) + + self.parser.add_option( + '-c', + '--clear', + action=3D'store_true', + dest=3D'clear', + help=3D'Clear the cache of loaded images', + default=3DFalse) + + self.parser.add_option( + '-f', + '--frame', + action=3D'store_true', + dest=3D'frame', + help=3D'Load symbols for current stack frame', + default=3DFalse) + + self.parser.add_option( + '-p', + '--pc', + action=3D'store_true', + dest=3D'pc', + help=3D'Load symbols for pc', + default=3DFalse) + + self.parser.add_option( + '--pei', + action=3D'store_true', + dest=3D'pei', + help=3D'Load symbols for PEI (searches every 4 bytes)', + default=3DFalse) + + self.parser.add_option( + '-e', + '--extended', + action=3D'store_true', + dest=3D'extended', + help=3D'Try to load all symbols based on config tables', + default=3DFalse) + + self.parser.add_option( + '-r', + '--range', + type=3D"long", + dest=3D'range', + help=3D'How far to search backward for start of PE/COFF Image', + default=3DNone) + + self.parser.add_option( + '-s', + '--stride', + type=3D"long", + dest=3D'stride', + help=3D'Boundary to search for PE/COFF header', + default=3DNone) + + self.parser.add_option( + '-t', + '--thread', + action=3D'store_true', + dest=3D'thread', + help=3D'Load symbols for the frames of all threads', + default=3DFalse) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'Show more info on symbols loading in gdb', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + return self.parser.parse_args(shlex.split(arg)) + + def save_user_state(self): + self.pagination =3D gdb.parameter("pagination") + if self.pagination: + gdb.execute("set pagination off") + + self.user_selected_thread =3D gdb.selected_thread() + self.user_selected_frame =3D gdb.selected_frame() + + def restore_user_state(self): + self.user_selected_thread.switch() + self.user_selected_frame.select() + + if self.pagination: + gdb.execute("set pagination on") + + def canonical_address(self, address): + ''' + Scrub out 48-bit non canonical addresses + Raw frames in gdb can have some funky values + ''' + + # Skip lowest 256 bytes to avoid interrupt frames + if address > 0xFF and address < 0x00007FFFFFFFFFFF: + return True + if address >=3D 0xFFFF800000000000: + return True + + return False + + def pc_set_for_frames(self): + '''Return a set for the PC's in the current frame''' + pc_list =3D [] + frame =3D gdb.newest_frame() + while frame: + pc =3D int(frame.read_register('pc')) + if self.canonical_address(pc): + pc_list.append(pc) + frame =3D frame.older() + + return set(pc_list) + + def invoke(self, arg, from_tty): + '''gdb command to symbolicate all the frames from all the threads'= '' + + try: + (options, _) =3D self.create_options(arg, from_tty) + if options.help: + self.parser.print_help() + return + except ValueError: + print('bad arguments!') + return + + self.dont_repeat() + + self.save_user_state() + + if options.clear: + self.efi_symbols.clear() + return + + if options.pei: + # XIP code can be 4 byte aligned in the FV + options.stride =3D 4 + options.range =3D 0x100000 + self.efi_symbols.configure_search(options.stride, + options.range, + options.verbose) + + if options.thread: + thread_list =3D gdb.selected_inferior().threads() + else: + thread_list =3D (gdb.selected_thread(),) + + address =3D None + if options.address: + value =3D gdb.parse_and_eval(options.address) + address =3D int(value) + elif options.pc: + address =3D gdb.selected_frame().pc() + + if address: + res =3D self.efi_symbols.address_to_symbols(address) + print(res) + else: + + for thread in thread_list: + thread.switch() + + # You can not iterate over frames as you load symbols. Loa= ding + # symbols changes the frames gdb can see due to inlining a= nd + # boom. So we loop adding symbols for the current frame, a= nd + # we test to see if new frames have shown up. If new frames + # show up we process those new frames. Thus 1st pass is the + # raw frame, and other passes are only new PC values. + NewPcSet =3D self.pc_set_for_frames() + while NewPcSet: + PcSet =3D self.pc_set_for_frames() + for pc in NewPcSet: + res =3D self.efi_symbols.address_to_symbols(pc) + print(res) + + NewPcSet =3D PcSet.symmetric_difference( + self.pc_set_for_frames()) + + # find the EFI System tables the 1st time + if self.gST is None: + gST =3D gdb.lookup_global_symbol('gST') + if gST is not None: + self.gST =3D int(gST.value(gdb.selected_frame())) + table =3D EfiConfigurationTable(self.file, self.gST) + else: + table =3D None + else: + table =3D EfiConfigurationTable(self.file, self.gST) + + if options.extended and table: + # load symbols from EFI System Table entry + for address, _ in table.DebugImageInfo(): + res =3D self.efi_symbols.address_to_symbols(address) + print(res) + + # sync up the GUID database from the build output + for m in gdb.objfiles(): + if GuidNames.add_build_guid_file(str(m.filename)): + break + + self.restore_user_state() + + +class EfiCmd (gdb.Command): + """Commands for debugging EFI. efi """ + + def __init__(self): + super(EfiCmd, self).__init__("efi", + gdb.COMMAND_NONE, + gdb.COMPLETE_NONE, + True) + + def invoke(self, arg, from_tty): + '''default to loading symbols''' + if '-h' in arg or '--help' in arg: + gdb.execute('help efi') + else: + # default to loading all symbols + gdb.execute('efi symbols --extended') + + +class LoadEmulatorEfiSymbols(gdb.Breakpoint): + ''' + breakpoint for EmulatorPkg to load symbols + Note: make sure SecGdbScriptBreak is not optimized away! + Also turn off the dlopen() flow like on macOS. + ''' + def stop(self): + symbols =3D EfiSymbols() + # Emulator adds SizeOfHeaders so we need file alignment to search + symbols.configure_search(0x20) + + frame =3D gdb.newest_frame() + + try: + # gdb was looking at spill address, pre spill :( + LoadAddress =3D frame.read_register('rdx') + AddSymbolFlag =3D frame.read_register('rcx') + except gdb.error: + LoadAddress =3D frame.read_var('LoadAddress') + AddSymbolFlag =3D frame.read_var('AddSymbolFlag') + + if AddSymbolFlag =3D=3D 1: + res =3D symbols.address_to_symbols(LoadAddress) + else: + res =3D symbols.unload_symbols(LoadAddress) + print(res) + + # keep running + return False + + +# Get python backtraces to debug errors in this script +gdb.execute("set python print-stack full") + +# tell efi_debugging how to walk data structures with pointers +try: + pointer_width =3D gdb.lookup_type('int').pointer().sizeof +except ValueError: + pointer_width =3D 8 +patch_ctypes(pointer_width) + +register_pretty_printer(None, build_pretty_printer(), replace=3DTrue) + +# gdb commands that we are adding +# add `efi` prefix gdb command +EfiCmd() + +# subcommands for `efi` +EfiSymbolsCmd() +EfiTablesCmd() +EfiHobCmd() +EfiDevicePathCmd() +EfiGuidCmd() + +# +bp =3D LoadEmulatorEfiSymbols('SecGdbScriptBreak', internal=3DTrue) +if bp.pending: + try: + gdb.selected_frame() + # Not the emulator so do this when you attach + gdb.execute('efi symbols --frame --extended', True) + gdb.execute('bt') + # If you want to skip the above commands comment them out + pass + except gdb.error: + # If you load the script and there is no target ignore the error. + pass +else: + # start the emulator + gdb.execute('run') --=20 2.34.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#87800): https://edk2.groups.io/g/devel/message/87800 Mute This Topic: https://groups.io/mt/89937667/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Wed May 15 12:05:13 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+87801+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+87801+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=quicinc.com Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1647894075065481.0570943361878; Mon, 21 Mar 2022 13:21:15 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id 3KVNYY1788612xwzr12aIRmz; Mon, 21 Mar 2022 13:21:16 -0700 X-Received: from alexa-out.qualcomm.com (alexa-out.qualcomm.com [129.46.98.28]) by mx.groups.io with SMTP id smtpd.web11.834.1647894075651035841 for ; Mon, 21 Mar 2022 13:21:15 -0700 X-Received: from ironmsg09-lv.qualcomm.com ([10.47.202.153]) by alexa-out.qualcomm.com with ESMTP; 21 Mar 2022 13:21:15 -0700 X-QCInternal: smtphost X-Received: from nasanex01c.na.qualcomm.com ([10.47.97.222]) by ironmsg09-lv.qualcomm.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Mar 2022 13:21:15 -0700 X-Received: from nalasex01a.na.qualcomm.com (10.47.209.196) by nasanex01c.na.qualcomm.com (10.47.97.222) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:14 -0700 X-Received: from linbox.ba.nuviainc.com (10.80.80.8) by nalasex01a.na.qualcomm.com (10.47.209.196) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.22; Mon, 21 Mar 2022 13:21:13 -0700 From: "Rebecca Cran" To: , Leif Lindholm , Michael D Kinney , Hao A Wu , Bob Feng , Liming Gao , Yuwei Chen CC: Rebecca Cran , Andrew Fish Subject: [edk2-devel] [PATCH v2 3/3] BaseTools: Scripts/efi_lldb.py: Add lldb EFI commands and pretty Print Date: Mon, 21 Mar 2022 14:20:48 -0600 Message-ID: <20220321202048.13567-4-quic_rcran@quicinc.com> In-Reply-To: <20220321202048.13567-1-quic_rcran@quicinc.com> References: <20220321202048.13567-1-quic_rcran@quicinc.com> MIME-Version: 1.0 X-Originating-IP: [10.80.80.8] X-ClientProxiedBy: nasanex01a.na.qualcomm.com (10.52.223.231) To nalasex01a.na.qualcomm.com (10.47.209.196) Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,quic_rcran@quicinc.com X-Gm-Message-State: TPcR7gaPL1K0qM7eTGtAdZJrx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1647894076; bh=itK76GizL1zdL4qbo5CufTxgI4fzhHwTvgGWkkyYEoo=; h=CC:Content-Type:Date:From:Reply-To:Subject:To; b=J4MJuDwc2eFp/MR1IVUE2ERwDlueP6vYsGxLie82WcbuJyFhlrtTamQIM37MMoHndII YU1jX0ZrVipu8KGMaeO/luTC/Bg8sixbwfDbLMOTA6b+ltBZ0Yuypwgo0hDuqqqiEe5aq 9rmNnCC6vML8cRyewOJRFW84cRACLQYmNIg= X-ZohoMail-DKIM: fail (Signature date is -1 seconds in the future.) X-ZM-MESSAGEID: 1647894082952100001 Content-Type: text/plain; charset="utf-8" https://bugzilla.tianocore.org/show_bug.cgi?id=3D3500 Use efi_debugging.py Python Classes to implement EFI gdb commands: efi_symbols, guid, table, hob, and devicepath You can attach to any standard gdb or kdp remote server and get EFI symbols. No modifications of EFI are required. Example usage: OvmfPkg/build.sh qemu -gdb tcp::9000 lldb -o "gdb-remote localhost:9000" -o "command script import efi_lldb.py" Note you may also have to teach lldb about QEMU: -o "settings set plugin.process.gdb-remote.target-definition-file x86_64_target_definition.py" Cc: Leif Lindholm Cc: Michael D Kinney Cc: Hao A Wu Cc: Bob Feng Cc: Liming Gao Cc: Yuwei Chen Signed-off-by: Rebecca Cran Acked-by: Liming Gao Reviewed-by: Bob Feng --- BaseTools/Scripts/efi_lldb.py | 1044 ++++++++++++++++++++ 1 file changed, 1044 insertions(+) diff --git a/BaseTools/Scripts/efi_lldb.py b/BaseTools/Scripts/efi_lldb.py new file mode 100755 index 000000000000..089b6ba58ab8 --- /dev/null +++ b/BaseTools/Scripts/efi_lldb.py @@ -0,0 +1,1044 @@ +#!/usr/bin/python3 +''' +Copyright (c) Apple Inc. 2021 +SPDX-License-Identifier: BSD-2-Clause-Patent + +Example usage: +OvmfPkg/build.sh qemu -gdb tcp::9000 +lldb -o "gdb-remote localhost:9000" -o "command script import efi_lldb.py" +''' + +import optparse +import shlex +import subprocess +import uuid +import sys +import os +from pathlib import Path +from efi_debugging import EfiDevicePath, EfiConfigurationTable, EfiTpl +from efi_debugging import EfiHob, GuidNames, EfiStatusClass, EfiBootMode +from efi_debugging import PeTeImage, patch_ctypes + +try: + # Just try for LLDB in case PYTHONPATH is already correctly setup + import lldb +except ImportError: + try: + env =3D os.environ.copy() + env['LLDB_DEFAULT_PYTHON_VERSION'] =3D str(sys.version_info.major) + lldb_python_path =3D subprocess.check_output( + ["xcrun", "lldb", "-P"], env=3Denv).decode("utf-8").strip() + sys.path.append(lldb_python_path) + import lldb + except ValueError: + print("Couldn't find LLDB.framework from lldb -P") + print("PYTHONPATH should match the currently selected lldb") + sys.exit(-1) + + +class LldbFileObject(object): + ''' + Class that fakes out file object to abstract lldb from the generic cod= e. + For lldb this is memory so we don't have a concept of the end of the f= ile. + ''' + + def __init__(self, process): + # _exe_ctx is lldb.SBExecutionContext + self._process =3D process + self._offset =3D 0 + self._SBError =3D lldb.SBError() + + def tell(self): + return self._offset + + def read(self, size=3D-1): + if size =3D=3D -1: + # arbitrary default size + size =3D 0x1000000 + + data =3D self._process.ReadMemory(self._offset, size, self._SBErro= r) + if self._SBError.fail: + raise MemoryError( + f'lldb could not read memory 0x{size:x} ' + f' bytes from 0x{self._offset:08x}') + else: + return data + + def readable(self): + return True + + def seek(self, offset, whence=3D0): + if whence =3D=3D 0: + self._offset =3D offset + elif whence =3D=3D 1: + self._offset +=3D offset + else: + # whence =3D=3D 2 is seek from end + raise NotImplementedError + + def seekable(self): + return True + + def write(self, data): + result =3D self._process.WriteMemory(self._offset, data, self._SBE= rror) + if self._SBError.fail: + raise MemoryError( + f'lldb could not write memory to 0x{self._offset:08x}') + return result + + def writable(self): + return True + + def truncate(self, size=3DNone): + raise NotImplementedError + + def flush(self): + raise NotImplementedError + + def fileno(self): + raise NotImplementedError + + +class EfiSymbols: + """ + Class to manage EFI Symbols + You need to pass file, and exe_ctx to load symbols. + You can print(EfiSymbols()) to see the currently loaded symbols + """ + + loaded =3D {} + stride =3D None + range =3D None + verbose =3D False + + def __init__(self, target=3DNone): + if target: + EfiSymbols.target =3D target + EfiSymbols._file =3D LldbFileObject(target.process) + + @ classmethod + def __str__(cls): + return ''.join(f'{pecoff}\n' for (pecoff, _) in cls.loaded.values(= )) + + @ classmethod + def configure_search(cls, stride, range, verbose=3DFalse): + cls.stride =3D stride + cls.range =3D range + cls.verbose =3D verbose + + @ classmethod + def clear(cls): + cls.loaded =3D {} + + @ classmethod + def add_symbols_for_pecoff(cls, pecoff): + '''Tell lldb the location of the .text and .data sections.''' + + if pecoff.LoadAddress in cls.loaded: + return 'Already Loaded: ' + + module =3D cls.target.AddModule(None, None, str(pecoff.CodeViewUui= d)) + if not module: + module =3D cls.target.AddModule(pecoff.CodeViewPdb, + None, + str(pecoff.CodeViewUuid)) + if module.IsValid(): + SBError =3D cls.target.SetModuleLoadAddress( + module, pecoff.LoadAddress + pecoff.TeAdjust) + if SBError.success: + cls.loaded[pecoff.LoadAddress] =3D (pecoff, module) + return '' + + return 'Symbols NOT FOUND: ' + + @ classmethod + def address_to_symbols(cls, address, reprobe=3DFalse): + ''' + Given an address search backwards for a PE/COFF (or TE) header + and load symbols. Return a status string. + ''' + if not isinstance(address, int): + address =3D int(address) + + pecoff, _ =3D cls.address_in_loaded_pecoff(address) + if not reprobe and pecoff is not None: + # skip the probe of the remote + return f'{pecoff} is already loaded' + + pecoff =3D PeTeImage(cls._file, None) + if pecoff.pcToPeCoff(address, cls.stride, cls.range): + res =3D cls.add_symbols_for_pecoff(pecoff) + return f'{res}{pecoff}' + else: + return f'0x{address:08x} not in a PE/COFF (or TE) image' + + @ classmethod + def address_in_loaded_pecoff(cls, address): + if not isinstance(address, int): + address =3D int(address) + + for (pecoff, module) in cls.loaded.values(): + if (address >=3D pecoff.LoadAddress and + address <=3D pecoff.EndLoadAddress): + + return pecoff, module + + return None, None + + @ classmethod + def unload_symbols(cls, address): + pecoff, module =3D cls.address_in_loaded_pecoff(address) + if module: + name =3D str(module) + cls.target.ClearModuleLoadAddress(module) + cls.target.RemoveModule(module) + del cls.loaded[pecoff.LoadAddress] + return f'{name:s} was unloaded' + return f'0x{address:x} was not in a loaded image' + + +def arg_to_address(frame, arg): + ''' convert an lldb command arg into a memory address (addr_t)''' + + if arg is None: + return None + + arg_str =3D arg if isinstance(arg, str) else str(arg) + SBValue =3D frame.EvaluateExpression(arg_str) + if SBValue.error.fail: + return arg + + if (SBValue.TypeIsPointerType() or + SBValue.value_type =3D=3D lldb.eValueTypeRegister or + SBValue.value_type =3D=3D lldb.eValueTypeRegisterSet or + SBValue.value_type =3D=3D lldb.eValueTypeConstResult): + try: + addr =3D SBValue.GetValueAsAddress() + except ValueError: + addr =3D SBValue.unsigned + else: + try: + addr =3D SBValue.address_of.GetValueAsAddress() + except ValueError: + addr =3D SBValue.address_of.unsigned + + return addr + + +def arg_to_data(frame, arg): + ''' convert an lldb command arg into a data vale (uint32_t/uint64_t)''' + if not isinstance(arg, str): + arg_str =3D str(str) + + SBValue =3D frame.EvaluateExpression(arg_str) + return SBValue.unsigned + + +class EfiDevicePathCommand: + + def create_options(self): + ''' standard lldb command help/options parser''' + usage =3D "usage: %prog [options]" + description =3D '''Command that can EFI Config Tables +''' + + # Pass add_help_option =3D False, since this keeps the command in = line + # with lldb commands, and we wire up "help command" to work by + # providing the long & short help methods below. + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'devicepath', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'hex dump extra data', + default=3DFalse) + + self.parser.add_option( + '-n', + '--node', + action=3D'store_true', + dest=3D'node', + help=3D'dump a single device path node', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + def get_short_help(self): + '''standard lldb function method''' + return "Display EFI Tables" + + def get_long_help(self): + '''standard lldb function method''' + return self.help_string + + def __init__(self, debugger, internal_dict): + '''standard lldb function method''' + self.create_options() + self.help_string =3D self.parser.format_help() + + def __call__(self, debugger, command, exe_ctx, result): + '''standard lldb function method''' + # Use the Shell Lexer to properly parse up command options just li= ke a + # shell would + command_args =3D shlex.split(command) + + try: + (options, args) =3D self.parser.parse_args(command_args) + dev_list =3D [] + for arg in args: + dev_list.append(arg_to_address(exe_ctx.frame, arg)) + except ValueError: + # if you don't handle exceptions, passing an incorrect argument + # to the OptionParser will cause LLDB to exit (courtesy of + # OptParse dealing with argument errors by throwing SystemExit) + result.SetError("option parsing failed") + return + + if options.help: + self.parser.print_help() + return + + file =3D LldbFileObject(exe_ctx.process) + + for dev_addr in dev_list: + if options.node: + print(EfiDevicePath(file).device_path_node_str( + dev_addr, options.verbose)) + else: + device_path =3D EfiDevicePath(file, dev_addr, options.verb= ose) + if device_path.valid(): + print(device_path) + + +class EfiHobCommand: + def create_options(self): + ''' standard lldb command help/options parser''' + usage =3D "usage: %prog [options]" + description =3D '''Command that can EFI dump EFI HOBs''' + + # Pass add_help_option =3D False, since this keeps the command in = line + # with lldb commands, and we wire up "help command" to work by + # providing the long & short help methods below. + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'table', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-a', + '--address', + type=3D"int", + dest=3D'address', + help=3D'Parse HOBs from address', + default=3DNone) + + self.parser.add_option( + '-t', + '--type', + type=3D"int", + dest=3D'type', + help=3D'Only dump HOBS of his type', + default=3DNone) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'hex dump extra data', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + def get_short_help(self): + '''standard lldb function method''' + return "Display EFI Hobs" + + def get_long_help(self): + '''standard lldb function method''' + return self.help_string + + def __init__(self, debugger, internal_dict): + '''standard lldb function method''' + self.create_options() + self.help_string =3D self.parser.format_help() + + def __call__(self, debugger, command, exe_ctx, result): + '''standard lldb function method''' + # Use the Shell Lexer to properly parse up command options just li= ke a + # shell would + command_args =3D shlex.split(command) + + try: + (options, _) =3D self.parser.parse_args(command_args) + except ValueError: + # if you don't handle exceptions, passing an incorrect argument + # to the OptionParser will cause LLDB to exit (courtesy of + # OptParse dealing with argument errors by throwing SystemExit) + result.SetError("option parsing failed") + return + + if options.help: + self.parser.print_help() + return + + address =3D arg_to_address(exe_ctx.frame, options.address) + + file =3D LldbFileObject(exe_ctx.process) + hob =3D EfiHob(file, address, options.verbose).get_hob_by_type( + options.type) + print(hob) + + +class EfiTableCommand: + + def create_options(self): + ''' standard lldb command help/options parser''' + usage =3D "usage: %prog [options]" + description =3D '''Command that can display EFI Config Tables +''' + + # Pass add_help_option =3D False, since this keeps the command in = line + # with lldb commands, and we wire up "help command" to work by + # providing the long & short help methods below. + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'table', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + def get_short_help(self): + '''standard lldb function method''' + return "Display EFI Tables" + + def get_long_help(self): + '''standard lldb function method''' + return self.help_string + + def __init__(self, debugger, internal_dict): + '''standard lldb function method''' + self.create_options() + self.help_string =3D self.parser.format_help() + + def __call__(self, debugger, command, exe_ctx, result): + '''standard lldb function method''' + # Use the Shell Lexer to properly parse up command options just li= ke a + # shell would + command_args =3D shlex.split(command) + + try: + (options, _) =3D self.parser.parse_args(command_args) + except ValueError: + # if you don't handle exceptions, passing an incorrect argument + # to the OptionParser will cause LLDB to exit (courtesy of + # OptParse dealing with argument errors by throwing SystemExit) + result.SetError("option parsing failed") + return + + if options.help: + self.parser.print_help() + return + + gST =3D exe_ctx.target.FindFirstGlobalVariable('gST') + if gST.error.fail: + print('Error: This command requires symbols for gST to be load= ed') + return + + file =3D LldbFileObject(exe_ctx.process) + table =3D EfiConfigurationTable(file, gST.unsigned) + if table: + print(table, '\n') + + +class EfiGuidCommand: + + def create_options(self): + ''' standard lldb command help/options parser''' + usage =3D "usage: %prog [options]" + description =3D ''' + Command that can display all EFI GUID's or give info on a + specific GUID's + ''' + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'guid', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-n', + '--new', + action=3D'store_true', + dest=3D'new', + help=3D'Generate a new GUID', + default=3DFalse) + + self.parser.add_option( + '-v', + '--verbose', + action=3D'store_true', + dest=3D'verbose', + help=3D'Also display GUID C structure values', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + def get_short_help(self): + '''standard lldb function method''' + return "Display EFI GUID's" + + def get_long_help(self): + '''standard lldb function method''' + return self.help_string + + def __init__(self, debugger, internal_dict): + '''standard lldb function method''' + self.create_options() + self.help_string =3D self.parser.format_help() + + def __call__(self, debugger, command, exe_ctx, result): + '''standard lldb function method''' + # Use the Shell Lexer to properly parse up command options just li= ke a + # shell would + command_args =3D shlex.split(command) + + try: + (options, args) =3D self.parser.parse_args(command_args) + if len(args) >=3D 1: + # guid { 0x414e6bdd, 0xe47b, 0x47cc, + # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }} + # this generates multiple args + arg =3D ' '.join(args) + except ValueError: + # if you don't handle exceptions, passing an incorrect argument + # to the OptionParser will cause LLDB to exit (courtesy of + # OptParse dealing with argument errors by throwing SystemExit) + result.SetError("option parsing failed") + return + + if options.help: + self.parser.print_help() + return + + if options.new: + guid =3D uuid.uuid4() + print(str(guid).upper()) + print(GuidNames.to_c_guid(guid)) + return + + if len(args) > 0: + if GuidNames.is_guid_str(arg): + # guid 05AD34BA-6F02-4214-952E-4DA0398E2BB9 + key =3D arg.lower() + name =3D GuidNames.to_name(key) + elif GuidNames.is_c_guid(arg): + # guid { 0x414e6bdd, 0xe47b, 0x47cc, + # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }} + key =3D GuidNames.from_c_guid(arg) + name =3D GuidNames.to_name(key) + else: + # guid gEfiDxeServicesTableGuid + name =3D arg + try: + key =3D GuidNames.to_guid(name) + name =3D GuidNames.to_name(key) + except ValueError: + return + + extra =3D f'{GuidNames.to_c_guid(key)}: ' if options.verbose e= lse '' + print(f'{key}: {extra}{name}') + + else: + for key, value in GuidNames._dict_.items(): + if options.verbose: + extra =3D f'{GuidNames.to_c_guid(key)}: ' + else: + extra =3D '' + print(f'{key}: {extra}{value}') + + +class EfiSymbolicateCommand(object): + '''Class to abstract an lldb command''' + + def create_options(self): + ''' standard lldb command help/options parser''' + usage =3D "usage: %prog [options]" + description =3D '''Command that can load EFI PE/COFF and TE image + symbols. If you are having trouble in PEI try adding --pei. + ''' + + # Pass add_help_option =3D False, since this keeps the command in = line + # with lldb commands, and we wire up "help command" to work by + # providing the long & short help methods below. + self.parser =3D optparse.OptionParser( + description=3Ddescription, + prog=3D'efi_symbols', + usage=3Dusage, + add_help_option=3DFalse) + + self.parser.add_option( + '-a', + '--address', + type=3D"int", + dest=3D'address', + help=3D'Load symbols for image at address', + default=3DNone) + + self.parser.add_option( + '-f', + '--frame', + action=3D'store_true', + dest=3D'frame', + help=3D'Load symbols for current stack frame', + default=3DFalse) + + self.parser.add_option( + '-p', + '--pc', + action=3D'store_true', + dest=3D'pc', + help=3D'Load symbols for pc', + default=3DFalse) + + self.parser.add_option( + '--pei', + action=3D'store_true', + dest=3D'pei', + help=3D'Load symbols for PEI (searches every 4 bytes)', + default=3DFalse) + + self.parser.add_option( + '-e', + '--extended', + action=3D'store_true', + dest=3D'extended', + help=3D'Try to load all symbols based on config tables.', + default=3DFalse) + + self.parser.add_option( + '-r', + '--range', + type=3D"long", + dest=3D'range', + help=3D'How far to search backward for start of PE/COFF Image', + default=3DNone) + + self.parser.add_option( + '-s', + '--stride', + type=3D"long", + dest=3D'stride', + help=3D'Boundary to search for PE/COFF header', + default=3DNone) + + self.parser.add_option( + '-t', + '--thread', + action=3D'store_true', + dest=3D'thread', + help=3D'Load symbols for the frames of all threads', + default=3DFalse) + + self.parser.add_option( + '-h', + '--help', + action=3D'store_true', + dest=3D'help', + help=3D'Show help for the command', + default=3DFalse) + + def get_short_help(self): + '''standard lldb function method''' + return ( + "Load symbols based on an address that is part of" + " a PE/COFF EFI image.") + + def get_long_help(self): + '''standard lldb function method''' + return self.help_string + + def __init__(self, debugger, unused): + '''standard lldb function method''' + self.create_options() + self.help_string =3D self.parser.format_help() + + def lldb_print(self, lldb_str): + # capture command out like an lldb command + self.result.PutCString(lldb_str) + # flush the output right away + self.result.SetImmediateOutputFile( + self.exe_ctx.target.debugger.GetOutputFile()) + + def __call__(self, debugger, command, exe_ctx, result): + '''standard lldb function method''' + # Use the Shell Lexer to properly parse up command options just li= ke a + # shell would + command_args =3D shlex.split(command) + + try: + (options, _) =3D self.parser.parse_args(command_args) + except ValueError: + # if you don't handle exceptions, passing an incorrect argument + # to the OptionParser will cause LLDB to exit (courtesy of + # OptParse dealing with argument errors by throwing SystemExit) + result.SetError("option parsing failed") + return + + if options.help: + self.parser.print_help() + return + + file =3D LldbFileObject(exe_ctx.process) + efi_symbols =3D EfiSymbols(exe_ctx.target) + self.result =3D result + self.exe_ctx =3D exe_ctx + + if options.pei: + # XIP code ends up on a 4 byte boundary. + options.stride =3D 4 + options.range =3D 0x100000 + efi_symbols.configure_search(options.stride, options.range) + + if not options.pc and options.address is None: + # default to + options.frame =3D True + + if options.frame: + if not exe_ctx.frame.IsValid(): + result.SetError("invalid frame") + return + + threads =3D exe_ctx.process.threads if options.thread else [ + exe_ctx.thread] + + for thread in threads: + for frame in thread: + res =3D efi_symbols.address_to_symbols(frame.pc) + self.lldb_print(res) + + else: + if options.address is not None: + address =3D options.address + elif options.pc: + try: + address =3D exe_ctx.thread.GetSelectedFrame().pc + except ValueError: + result.SetError("invalid pc") + return + else: + address =3D 0 + + res =3D efi_symbols.address_to_symbols(address.pc) + print(res) + + if options.extended: + + gST =3D exe_ctx.target.FindFirstGlobalVariable('gST') + if gST.error.fail: + print('Error: This command requires symbols to be loaded') + else: + table =3D EfiConfigurationTable(file, gST.unsigned) + for address, _ in table.DebugImageInfo(): + res =3D efi_symbols.address_to_symbols(address) + self.lldb_print(res) + + # keep trying module file names until we find a GUID xref file + for m in exe_ctx.target.modules: + if GuidNames.add_build_guid_file(str(m.file)): + break + + +def CHAR16_TypeSummary(valobj, internal_dict): + ''' + Display CHAR16 as a String in the debugger. + Note: utf-8 is returned as that is the value for the debugger. + ''' + SBError =3D lldb.SBError() + Str =3D '' + if valobj.TypeIsPointerType(): + if valobj.GetValueAsUnsigned() =3D=3D 0: + return "NULL" + + # CHAR16 * max string size 1024 + for i in range(1024): + Char =3D valobj.GetPointeeData(i, 1).GetUnsignedInt16(SBError,= 0) + if SBError.fail or Char =3D=3D 0: + break + Str +=3D chr(Char) + return 'L"' + Str + '"' + + if valobj.num_children =3D=3D 0: + # CHAR16 + return "L'" + chr(valobj.unsigned) + "'" + + else: + # CHAR16 [] + for i in range(valobj.num_children): + Char =3D valobj.GetChildAtIndex(i).data.GetUnsignedInt16(SBErr= or, 0) + if Char =3D=3D 0: + break + Str +=3D chr(Char) + return 'L"' + Str + '"' + + return Str + + +def CHAR8_TypeSummary(valobj, internal_dict): + ''' + Display CHAR8 as a String in the debugger. + Note: utf-8 is returned as that is the value for the debugger. + ''' + SBError =3D lldb.SBError() + Str =3D '' + if valobj.TypeIsPointerType(): + if valobj.GetValueAsUnsigned() =3D=3D 0: + return "NULL" + + # CHAR8 * max string size 1024 + for i in range(1024): + Char =3D valobj.GetPointeeData(i, 1).GetUnsignedInt8(SBError, = 0) + if SBError.fail or Char =3D=3D 0: + break + Str +=3D chr(Char) + Str =3D '"' + Str + '"' + return Str + + if valobj.num_children =3D=3D 0: + # CHAR8 + return "'" + chr(valobj.unsigned) + "'" + else: + # CHAR8 [] + for i in range(valobj.num_children): + Char =3D valobj.GetChildAtIndex(i).data.GetUnsignedInt8(SBErro= r, 0) + if SBError.fail or Char =3D=3D 0: + break + Str +=3D chr(Char) + return '"' + Str + '"' + + return Str + + +def EFI_STATUS_TypeSummary(valobj, internal_dict): + if valobj.TypeIsPointerType(): + return '' + return str(EfiStatusClass(valobj.unsigned)) + + +def EFI_TPL_TypeSummary(valobj, internal_dict): + if valobj.TypeIsPointerType(): + return '' + return str(EfiTpl(valobj.unsigned)) + + +def EFI_GUID_TypeSummary(valobj, internal_dict): + if valobj.TypeIsPointerType(): + return '' + return str(GuidNames(bytes(valobj.data.uint8))) + + +def EFI_BOOT_MODE_TypeSummary(valobj, internal_dict): + if valobj.TypeIsPointerType(): + return '' + '''Return #define name for EFI_BOOT_MODE''' + return str(EfiBootMode(valobj.unsigned)) + + +def lldb_type_formaters(debugger, mod_name): + '''Teach lldb about EFI types''' + + category =3D debugger.GetDefaultCategory() + FormatBool =3D lldb.SBTypeFormat(lldb.eFormatBoolean) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("BOOLEAN"), FormatBool) + + FormatHex =3D lldb.SBTypeFormat(lldb.eFormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("UINT64"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("INT64"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("UINT32"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("INT32"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("UINT16"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("INT16"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("UINT8"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("INT8"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("UINTN"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("INTN"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("CHAR8"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("CHAR16"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier( + "EFI_PHYSICAL_ADDRESS"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier( + "PHYSICAL_ADDRESS"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier("EFI_LBA"), FormatHex) + category.AddTypeFormat( + lldb.SBTypeNameSpecifier("EFI_BOOT_MODE"), FormatHex) + category.AddTypeFormat(lldb.SBTypeNameSpecifier( + "EFI_FV_FILETYPE"), FormatHex) + + # + # Smart type printing for EFI + # + + debugger.HandleCommand( + f'type summary add GUID - -python-function ' + f'{mod_name}.EFI_GUID_TypeSummary') + debugger.HandleCommand( + f'type summary add EFI_GUID --python-function ' + f'{mod_name}.EFI_GUID_TypeSummary') + debugger.HandleCommand( + f'type summary add EFI_STATUS --python-function ' + f'{mod_name}.EFI_STATUS_TypeSummary') + debugger.HandleCommand( + f'type summary add EFI_TPL - -python-function ' + f'{mod_name}.EFI_TPL_TypeSummary') + debugger.HandleCommand( + f'type summary add EFI_BOOT_MODE --python-function ' + f'{mod_name}.EFI_BOOT_MODE_TypeSummary') + + debugger.HandleCommand( + f'type summary add CHAR16 --python-function ' + f'{mod_name}.CHAR16_TypeSummary') + + # W605 this is the correct escape sequence for the lldb command + debugger.HandleCommand( + f'type summary add --regex "CHAR16 \[[0-9]+\]" ' # noqa: W605 + f'--python-function {mod_name}.CHAR16_TypeSummary') + + debugger.HandleCommand( + f'type summary add CHAR8 --python-function ' + f'{mod_name}.CHAR8_TypeSummary') + + # W605 this is the correct escape sequence for the lldb command + debugger.HandleCommand( + f'type summary add --regex "CHAR8 \[[0-9]+\]" ' # noqa: W605 + f'--python-function {mod_name}.CHAR8_TypeSummary') + + +class LldbWorkaround: + needed =3D True + + @classmethod + def activate(cls): + if cls.needed: + lldb.debugger.HandleCommand("process handle SIGALRM -n false") + cls.needed =3D False + + +def LoadEmulatorEfiSymbols(frame, bp_loc, internal_dict): + # + # This is an lldb breakpoint script, and assumes the breakpoint is on a + # function with the same prototype as SecGdbScriptBreak(). The + # argument names are important as lldb looks them up. + # + # VOID + # SecGdbScriptBreak ( + # char *FileName, + # int FileNameLength, + # long unsigned int LoadAddress, + # int AddSymbolFlag + # ) + # { + # return; + # } + # + # When the emulator loads a PE/COFF image, it calls the stub function = with + # the filename of the symbol file, the length of the FileName, the + # load address and a flag to indicate if this is a load or unload oper= ation + # + LldbWorkaround().activate() + + symbols =3D EfiSymbols(frame.thread.process.target) + LoadAddress =3D frame.FindVariable("LoadAddress").unsigned + if frame.FindVariable("AddSymbolFlag").unsigned =3D=3D 1: + res =3D symbols.address_to_symbols(LoadAddress) + else: + res =3D symbols.unload_symbols(LoadAddress) + print(res) + + # make breakpoint command continue + return False + + +def __lldb_init_module(debugger, internal_dict): + ''' + This initializer is being run from LLDB in the embedded command interp= reter + ''' + + mod_name =3D Path(__file__).stem + lldb_type_formaters(debugger, mod_name) + + # Add any commands contained in this module to LLDB + debugger.HandleCommand( + f'command script add -c {mod_name}.EfiSymbolicateCommand efi_symbo= ls') + debugger.HandleCommand( + f'command script add -c {mod_name}.EfiGuidCommand guid') + debugger.HandleCommand( + f'command script add -c {mod_name}.EfiTableCommand table') + debugger.HandleCommand( + f'command script add -c {mod_name}.EfiHobCommand hob') + debugger.HandleCommand( + f'command script add -c {mod_name}.EfiDevicePathCommand devicepath= ') + + print('EFI specific commands have been installed.') + + # patch the ctypes c_void_p values if the debuggers OS and EFI have + # different ideas on the size of the debug. + try: + patch_ctypes(debugger.GetSelectedTarget().addr_size) + except ValueError: + # incase the script is imported and the debugger has not target + # defaults to sizeof(UINTN) =3D=3D sizeof(UINT64) + patch_ctypes() + + try: + target =3D debugger.GetSelectedTarget() + if target.FindFunctions('SecGdbScriptBreak').symbols: + breakpoint =3D target.BreakpointCreateByName('SecGdbScriptBrea= k') + # Set the emulator breakpoints, if we are in the emulator + cmd =3D 'breakpoint command add -s python -F ' + cmd +=3D f'efi_lldb.LoadEmulatorEfiSymbols {breakpoint.GetID()= }' + debugger.HandleCommand(cmd) + print('Type r to run emulator.') + else: + raise ValueError("No Emulator Symbols") + + except ValueError: + # default action when the script is imported + debugger.HandleCommand("efi_symbols --frame --extended") + debugger.HandleCommand("register read") + debugger.HandleCommand("bt all") + + +if __name__ =3D=3D '__main__': + pass --=20 2.34.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#87801): https://edk2.groups.io/g/devel/message/87801 Mute This Topic: https://groups.io/mt/89937669/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-