diff options
author | Rebecca Cran <quic_rcran@quicinc.com> | 2022-03-22 04:20:48 +0800 |
---|---|---|
committer | mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> | 2022-04-09 05:13:56 +0000 |
commit | 4f4afcd28802ff8a3e78ad72e47b6acb6e24819c (patch) | |
tree | e8572b7c4f82d42b6ef4f9c25769f1f533172607 /BaseTools/Scripts | |
parent | 0d7fec9f79b3f24007ea55769419e72d747b1f7e (diff) | |
download | edk2-4f4afcd28802ff8a3e78ad72e47b6acb6e24819c.zip edk2-4f4afcd28802ff8a3e78ad72e47b6acb6e24819c.tar.gz edk2-4f4afcd28802ff8a3e78ad72e47b6acb6e24819c.tar.bz2 |
BaseTools: Scripts/efi_lldb.py: Add lldb EFI commands and pretty Print
https://bugzilla.tianocore.org/show_bug.cgi?id=3500
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 <quic_llindhol@quicinc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Hao A Wu <hao.a.wu@intel.com>
Cc: Bob Feng <bob.c.feng@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Yuwei Chen <yuwei.chen@intel.com>
Signed-off-by: Rebecca Cran <quic_rcran@quicinc.com>
Reviewed-by: Bob Feng <bob.c.feng@intel.com>
Acked-by: Liming Gao <gaoliming@byosoft.com.cn>
Diffstat (limited to 'BaseTools/Scripts')
-rwxr-xr-x | BaseTools/Scripts/efi_lldb.py | 1044 |
1 files changed, 1044 insertions, 0 deletions
diff --git a/BaseTools/Scripts/efi_lldb.py b/BaseTools/Scripts/efi_lldb.py new file mode 100755 index 0000000..6487e41 --- /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 = os.environ.copy()
+ env['LLDB_DEFAULT_PYTHON_VERSION'] = str(sys.version_info.major)
+ lldb_python_path = subprocess.check_output(
+ ["xcrun", "lldb", "-P"], env=env).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 code.
+ For lldb this is memory so we don't have a concept of the end of the file.
+ '''
+
+ def __init__(self, process):
+ # _exe_ctx is lldb.SBExecutionContext
+ self._process = process
+ self._offset = 0
+ self._SBError = lldb.SBError()
+
+ def tell(self):
+ return self._offset
+
+ def read(self, size=-1):
+ if size == -1:
+ # arbitrary default size
+ size = 0x1000000
+
+ data = self._process.ReadMemory(self._offset, size, self._SBError)
+ 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=0):
+ if whence == 0:
+ self._offset = offset
+ elif whence == 1:
+ self._offset += offset
+ else:
+ # whence == 2 is seek from end
+ raise NotImplementedError
+
+ def seekable(self):
+ return True
+
+ def write(self, data):
+ result = self._process.WriteMemory(self._offset, data, self._SBError)
+ 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=None):
+ 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 = {}
+ stride = None
+ range = None
+ verbose = False
+
+ def __init__(self, target=None):
+ if target:
+ EfiSymbols.target = target
+ EfiSymbols._file = 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=False):
+ cls.stride = stride
+ cls.range = range
+ cls.verbose = verbose
+
+ @ classmethod
+ def clear(cls):
+ cls.loaded = {}
+
+ @ 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 = cls.target.AddModule(None, None, str(pecoff.CodeViewUuid))
+ if not module:
+ module = cls.target.AddModule(pecoff.CodeViewPdb,
+ None,
+ str(pecoff.CodeViewUuid))
+ if module.IsValid():
+ SBError = cls.target.SetModuleLoadAddress(
+ module, pecoff.LoadAddress + pecoff.TeAdjust)
+ if SBError.success:
+ cls.loaded[pecoff.LoadAddress] = (pecoff, module)
+ return ''
+
+ return 'Symbols NOT FOUND: '
+
+ @ classmethod
+ def address_to_symbols(cls, address, reprobe=False):
+ '''
+ 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 = int(address)
+
+ pecoff, _ = 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 = PeTeImage(cls._file, None)
+ if pecoff.pcToPeCoff(address, cls.stride, cls.range):
+ res = 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 = int(address)
+
+ for (pecoff, module) in cls.loaded.values():
+ if (address >= pecoff.LoadAddress and
+ address <= pecoff.EndLoadAddress):
+
+ return pecoff, module
+
+ return None, None
+
+ @ classmethod
+ def unload_symbols(cls, address):
+ pecoff, module = cls.address_in_loaded_pecoff(address)
+ if module:
+ name = 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 = arg if isinstance(arg, str) else str(arg)
+ SBValue = frame.EvaluateExpression(arg_str)
+ if SBValue.error.fail:
+ return arg
+
+ if (SBValue.TypeIsPointerType() or
+ SBValue.value_type == lldb.eValueTypeRegister or
+ SBValue.value_type == lldb.eValueTypeRegisterSet or
+ SBValue.value_type == lldb.eValueTypeConstResult):
+ try:
+ addr = SBValue.GetValueAsAddress()
+ except ValueError:
+ addr = SBValue.unsigned
+ else:
+ try:
+ addr = SBValue.address_of.GetValueAsAddress()
+ except ValueError:
+ addr = 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 = str(str)
+
+ SBValue = frame.EvaluateExpression(arg_str)
+ return SBValue.unsigned
+
+
+class EfiDevicePathCommand:
+
+ def create_options(self):
+ ''' standard lldb command help/options parser'''
+ usage = "usage: %prog [options]"
+ description = '''Command that can EFI Config Tables
+'''
+
+ # Pass add_help_option = 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 = optparse.OptionParser(
+ description=description,
+ prog='devicepath',
+ usage=usage,
+ add_help_option=False)
+
+ self.parser.add_option(
+ '-v',
+ '--verbose',
+ action='store_true',
+ dest='verbose',
+ help='hex dump extra data',
+ default=False)
+
+ self.parser.add_option(
+ '-n',
+ '--node',
+ action='store_true',
+ dest='node',
+ help='dump a single device path node',
+ default=False)
+
+ self.parser.add_option(
+ '-h',
+ '--help',
+ action='store_true',
+ dest='help',
+ help='Show help for the command',
+ default=False)
+
+ 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 = 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 like a
+ # shell would
+ command_args = shlex.split(command)
+
+ try:
+ (options, args) = self.parser.parse_args(command_args)
+ dev_list = []
+ 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 = 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 = EfiDevicePath(file, dev_addr, options.verbose)
+ if device_path.valid():
+ print(device_path)
+
+
+class EfiHobCommand:
+ def create_options(self):
+ ''' standard lldb command help/options parser'''
+ usage = "usage: %prog [options]"
+ description = '''Command that can EFI dump EFI HOBs'''
+
+ # Pass add_help_option = 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 = optparse.OptionParser(
+ description=description,
+ prog='table',
+ usage=usage,
+ add_help_option=False)
+
+ self.parser.add_option(
+ '-a',
+ '--address',
+ type="int",
+ dest='address',
+ help='Parse HOBs from address',
+ default=None)
+
+ self.parser.add_option(
+ '-t',
+ '--type',
+ type="int",
+ dest='type',
+ help='Only dump HOBS of his type',
+ default=None)
+
+ self.parser.add_option(
+ '-v',
+ '--verbose',
+ action='store_true',
+ dest='verbose',
+ help='hex dump extra data',
+ default=False)
+
+ self.parser.add_option(
+ '-h',
+ '--help',
+ action='store_true',
+ dest='help',
+ help='Show help for the command',
+ default=False)
+
+ 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 = 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 like a
+ # shell would
+ command_args = shlex.split(command)
+
+ try:
+ (options, _) = 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 = arg_to_address(exe_ctx.frame, options.address)
+
+ file = LldbFileObject(exe_ctx.process)
+ hob = 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 = "usage: %prog [options]"
+ description = '''Command that can display EFI Config Tables
+'''
+
+ # Pass add_help_option = 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 = optparse.OptionParser(
+ description=description,
+ prog='table',
+ usage=usage,
+ add_help_option=False)
+
+ self.parser.add_option(
+ '-h',
+ '--help',
+ action='store_true',
+ dest='help',
+ help='Show help for the command',
+ default=False)
+
+ 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 = 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 like a
+ # shell would
+ command_args = shlex.split(command)
+
+ try:
+ (options, _) = 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 = exe_ctx.target.FindFirstGlobalVariable('gST')
+ if gST.error.fail:
+ print('Error: This command requires symbols for gST to be loaded')
+ return
+
+ file = LldbFileObject(exe_ctx.process)
+ table = EfiConfigurationTable(file, gST.unsigned)
+ if table:
+ print(table, '\n')
+
+
+class EfiGuidCommand:
+
+ def create_options(self):
+ ''' standard lldb command help/options parser'''
+ usage = "usage: %prog [options]"
+ description = '''
+ Command that can display all EFI GUID's or give info on a
+ specific GUID's
+ '''
+ self.parser = optparse.OptionParser(
+ description=description,
+ prog='guid',
+ usage=usage,
+ add_help_option=False)
+
+ self.parser.add_option(
+ '-n',
+ '--new',
+ action='store_true',
+ dest='new',
+ help='Generate a new GUID',
+ default=False)
+
+ self.parser.add_option(
+ '-v',
+ '--verbose',
+ action='store_true',
+ dest='verbose',
+ help='Also display GUID C structure values',
+ default=False)
+
+ self.parser.add_option(
+ '-h',
+ '--help',
+ action='store_true',
+ dest='help',
+ help='Show help for the command',
+ default=False)
+
+ 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 = 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 like a
+ # shell would
+ command_args = shlex.split(command)
+
+ try:
+ (options, args) = self.parser.parse_args(command_args)
+ if len(args) >= 1:
+ # guid { 0x414e6bdd, 0xe47b, 0x47cc,
+ # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }}
+ # this generates multiple args
+ arg = ' '.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 = 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 = arg.lower()
+ name = GuidNames.to_name(key)
+ elif GuidNames.is_c_guid(arg):
+ # guid { 0x414e6bdd, 0xe47b, 0x47cc,
+ # { 0xb2, 0x44, 0xbb, 0x61, 0x02, 0x0c,0xf5, 0x16 }}
+ key = GuidNames.from_c_guid(arg)
+ name = GuidNames.to_name(key)
+ else:
+ # guid gEfiDxeServicesTableGuid
+ name = arg
+ try:
+ key = GuidNames.to_guid(name)
+ name = GuidNames.to_name(key)
+ except ValueError:
+ return
+
+ extra = f'{GuidNames.to_c_guid(key)}: ' if options.verbose else ''
+ print(f'{key}: {extra}{name}')
+
+ else:
+ for key, value in GuidNames._dict_.items():
+ if options.verbose:
+ extra = f'{GuidNames.to_c_guid(key)}: '
+ else:
+ extra = ''
+ 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 = "usage: %prog [options]"
+ description = '''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 = 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 = optparse.OptionParser(
+ description=description,
+ prog='efi_symbols',
+ usage=usage,
+ add_help_option=False)
+
+ self.parser.add_option(
+ '-a',
+ '--address',
+ type="int",
+ dest='address',
+ help='Load symbols for image at address',
+ default=None)
+
+ self.parser.add_option(
+ '-f',
+ '--frame',
+ action='store_true',
+ dest='frame',
+ help='Load symbols for current stack frame',
+ default=False)
+
+ self.parser.add_option(
+ '-p',
+ '--pc',
+ action='store_true',
+ dest='pc',
+ help='Load symbols for pc',
+ default=False)
+
+ self.parser.add_option(
+ '--pei',
+ action='store_true',
+ dest='pei',
+ help='Load symbols for PEI (searches every 4 bytes)',
+ default=False)
+
+ self.parser.add_option(
+ '-e',
+ '--extended',
+ action='store_true',
+ dest='extended',
+ help='Try to load all symbols based on config tables.',
+ default=False)
+
+ self.parser.add_option(
+ '-r',
+ '--range',
+ type="long",
+ dest='range',
+ help='How far to search backward for start of PE/COFF Image',
+ default=None)
+
+ self.parser.add_option(
+ '-s',
+ '--stride',
+ type="long",
+ dest='stride',
+ help='Boundary to search for PE/COFF header',
+ default=None)
+
+ self.parser.add_option(
+ '-t',
+ '--thread',
+ action='store_true',
+ dest='thread',
+ help='Load symbols for the frames of all threads',
+ default=False)
+
+ self.parser.add_option(
+ '-h',
+ '--help',
+ action='store_true',
+ dest='help',
+ help='Show help for the command',
+ default=False)
+
+ 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 = 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 like a
+ # shell would
+ command_args = shlex.split(command)
+
+ try:
+ (options, _) = 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 = LldbFileObject(exe_ctx.process)
+ efi_symbols = EfiSymbols(exe_ctx.target)
+ self.result = result
+ self.exe_ctx = exe_ctx
+
+ if options.pei:
+ # XIP code ends up on a 4 byte boundary.
+ options.stride = 4
+ options.range = 0x100000
+ efi_symbols.configure_search(options.stride, options.range)
+
+ if not options.pc and options.address is None:
+ # default to
+ options.frame = True
+
+ if options.frame:
+ if not exe_ctx.frame.IsValid():
+ result.SetError("invalid frame")
+ return
+
+ threads = exe_ctx.process.threads if options.thread else [
+ exe_ctx.thread]
+
+ for thread in threads:
+ for frame in thread:
+ res = efi_symbols.address_to_symbols(frame.pc)
+ self.lldb_print(res)
+
+ else:
+ if options.address is not None:
+ address = options.address
+ elif options.pc:
+ try:
+ address = exe_ctx.thread.GetSelectedFrame().pc
+ except ValueError:
+ result.SetError("invalid pc")
+ return
+ else:
+ address = 0
+
+ res = efi_symbols.address_to_symbols(address.pc)
+ print(res)
+
+ if options.extended:
+
+ gST = exe_ctx.target.FindFirstGlobalVariable('gST')
+ if gST.error.fail:
+ print('Error: This command requires symbols to be loaded')
+ else:
+ table = EfiConfigurationTable(file, gST.unsigned)
+ for address, _ in table.DebugImageInfo():
+ res = 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 = lldb.SBError()
+ Str = ''
+ if valobj.TypeIsPointerType():
+ if valobj.GetValueAsUnsigned() == 0:
+ return "NULL"
+
+ # CHAR16 * max string size 1024
+ for i in range(1024):
+ Char = valobj.GetPointeeData(i, 1).GetUnsignedInt16(SBError, 0)
+ if SBError.fail or Char == 0:
+ break
+ Str += chr(Char)
+ return 'L"' + Str + '"'
+
+ if valobj.num_children == 0:
+ # CHAR16
+ return "L'" + chr(valobj.unsigned) + "'"
+
+ else:
+ # CHAR16 []
+ for i in range(valobj.num_children):
+ Char = valobj.GetChildAtIndex(i).data.GetUnsignedInt16(SBError, 0)
+ if Char == 0:
+ break
+ Str += 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 = lldb.SBError()
+ Str = ''
+ if valobj.TypeIsPointerType():
+ if valobj.GetValueAsUnsigned() == 0:
+ return "NULL"
+
+ # CHAR8 * max string size 1024
+ for i in range(1024):
+ Char = valobj.GetPointeeData(i, 1).GetUnsignedInt8(SBError, 0)
+ if SBError.fail or Char == 0:
+ break
+ Str += chr(Char)
+ Str = '"' + Str + '"'
+ return Str
+
+ if valobj.num_children == 0:
+ # CHAR8
+ return "'" + chr(valobj.unsigned) + "'"
+ else:
+ # CHAR8 []
+ for i in range(valobj.num_children):
+ Char = valobj.GetChildAtIndex(i).data.GetUnsignedInt8(SBError, 0)
+ if SBError.fail or Char == 0:
+ break
+ Str += 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 = debugger.GetDefaultCategory()
+ FormatBool = lldb.SBTypeFormat(lldb.eFormatBoolean)
+ category.AddTypeFormat(lldb.SBTypeNameSpecifier("BOOLEAN"), FormatBool)
+
+ FormatHex = 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 = True
+
+ @classmethod
+ def activate(cls):
+ if cls.needed:
+ lldb.debugger.HandleCommand("process handle SIGALRM -n false")
+ cls.needed = 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 operation
+ #
+ LldbWorkaround().activate()
+
+ symbols = EfiSymbols(frame.thread.process.target)
+ LoadAddress = frame.FindVariable("LoadAddress").unsigned
+ if frame.FindVariable("AddSymbolFlag").unsigned == 1:
+ res = symbols.address_to_symbols(LoadAddress)
+ else:
+ res = 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 interpreter
+ '''
+
+ mod_name = 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_symbols')
+ 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) == sizeof(UINT64)
+ patch_ctypes()
+
+ try:
+ target = debugger.GetSelectedTarget()
+ if target.FindFunctions('SecGdbScriptBreak').symbols:
+ breakpoint = target.BreakpointCreateByName('SecGdbScriptBreak')
+ # Set the emulator breakpoints, if we are in the emulator
+ cmd = 'breakpoint command add -s python -F '
+ cmd += 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__ == '__main__':
+ pass
|