diff options
Diffstat (limited to 'scripts/Python/modify-python-lldb.py')
| -rw-r--r-- | scripts/Python/modify-python-lldb.py | 500 |
1 files changed, 0 insertions, 500 deletions
diff --git a/scripts/Python/modify-python-lldb.py b/scripts/Python/modify-python-lldb.py deleted file mode 100644 index cb911eed047f..000000000000 --- a/scripts/Python/modify-python-lldb.py +++ /dev/null @@ -1,500 +0,0 @@ -# -# modify-python-lldb.py -# -# This script modifies the lldb module (which was automatically generated via -# running swig) to support iteration and/or equality operations for certain lldb -# objects, implements truth value testing for certain lldb objects, and adds a -# global variable 'debugger_unique_id' which is initialized to 0. -# -# As a cleanup step, it also removes the 'residues' from the autodoc features of -# swig. For an example, take a look at SBTarget.h header file, where we take -# advantage of the already existing doxygen C++-docblock and make it the Python -# docstring for the same method. The 'residues' in this context include the -# '#endif', the '#ifdef SWIG', the c comment marker, the trailing blank (SPC's) -# line, and the doxygen comment start marker. -# -# In addition to the 'residues' removal during the cleanup step, it also -# transforms the 'char' data type (which was actually 'char *' but the 'autodoc' -# feature of swig removes ' *' from it) into 'str' (as a Python str type). -# -# It also calls SBDebugger.Initialize() to initialize the lldb debugger -# subsystem. -# - -# System modules -import sys -import re -if sys.version_info.major >= 3: - import io as StringIO -else: - import StringIO - -# import use_lldb_suite so we can find third-party and helper modules -import use_lldb_suite - -# Third party modules -import six - -# LLDB modules - -if len(sys.argv) != 2: - output_name = "./lldb.py" -else: - output_name = sys.argv[1] + "/lldb.py" - -# print "output_name is '" + output_name + "'" - -# -# Version string -# -version_line = "swig_version = %s" - -# -# Residues to be removed. -# -c_endif_swig = "#endif" -c_ifdef_swig = "#ifdef SWIG" -c_comment_marker = "//------------" -# The pattern for recognizing the doxygen comment block line. -doxygen_comment_start = re.compile("^\s*(/// ?)") -# The demarcation point for turning on/off residue removal state. -# When bracketed by the lines, the CLEANUP_DOCSTRING state (see below) is ON. -toggle_docstring_cleanup_line = ' """' - - -def char_to_str_xform(line): - """This transforms the 'char', i.e, 'char *' to 'str', Python string.""" - line = line.replace(' char', ' str') - line = line.replace('char ', 'str ') - # Special case handling of 'char **argv' and 'char **envp'. - line = line.replace('str argv', 'list argv') - line = line.replace('str envp', 'list envp') - return line - -# -# The one-liner docstring also needs char_to_str transformation, btw. -# -TWO_SPACES = ' ' * 2 -EIGHT_SPACES = ' ' * 8 -one_liner_docstring_pattern = re.compile( - '^(%s|%s)""".*"""$' % - (TWO_SPACES, EIGHT_SPACES)) - -# -# lldb_helpers and lldb_iter() should appear before our first SB* class definition. -# -lldb_helpers = ''' -# ================================== -# Helper function for SBModule class -# ================================== -def in_range(symbol, section): - """Test whether a symbol is within the range of a section.""" - symSA = symbol.GetStartAddress().GetFileAddress() - symEA = symbol.GetEndAddress().GetFileAddress() - secSA = section.GetFileAddress() - secEA = secSA + section.GetByteSize() - - if symEA != LLDB_INVALID_ADDRESS: - if secSA <= symSA and symEA <= secEA: - return True - else: - return False - else: - if secSA <= symSA and symSA < secEA: - return True - else: - return False -''' - -lldb_iter_def = ''' -# =================================== -# Iterator for lldb container objects -# =================================== -def lldb_iter(obj, getsize, getelem): - """A generator adaptor to support iteration for lldb container objects.""" - size = getattr(obj, getsize) - elem = getattr(obj, getelem) - for i in range(size()): - yield elem(i) - -# ============================================================================== -# The modify-python-lldb.py script is responsible for post-processing this SWIG- -# generated lldb.py module. It is responsible for adding the above lldb_iter() -# function definition as well as the supports, in the following, for iteration -# protocol: __iter__, rich comparison methods: __eq__ and __ne__, truth value -# testing (and built-in operation bool()): __nonzero__, and built-in function -# len(): __len__. -# ============================================================================== -''' - -# -# linked_list_iter() is a special purpose iterator to treat the SBValue as the -# head of a list data structure, where you specify the child member name which -# points to the next item on the list and you specify the end-of-list function -# which takes an SBValue and returns True if EOL is reached and False if not. -# -linked_list_iter_def = ''' - def __eol_test__(val): - """Default function for end of list test takes an SBValue object. - - Return True if val is invalid or it corresponds to a null pointer. - Otherwise, return False. - """ - if not val or val.GetValueAsUnsigned() == 0: - return True - else: - return False - - # ================================================== - # Iterator for lldb.SBValue treated as a linked list - # ================================================== - def linked_list_iter(self, next_item_name, end_of_list_test=__eol_test__): - """Generator adaptor to support iteration for SBValue as a linked list. - - linked_list_iter() is a special purpose iterator to treat the SBValue as - the head of a list data structure, where you specify the child member - name which points to the next item on the list and you specify the - end-of-list test function which takes an SBValue for an item and returns - True if EOL is reached and False if not. - - linked_list_iter() also detects infinite loop and bails out early. - - The end_of_list_test arg, if omitted, defaults to the __eol_test__ - function above. - - For example, - - # Get Frame #0. - ... - - # Get variable 'task_head'. - task_head = frame0.FindVariable('task_head') - ... - - for t in task_head.linked_list_iter('next'): - print t - """ - if end_of_list_test(self): - return - item = self - visited = set() - try: - while not end_of_list_test(item) and not item.GetValueAsUnsigned() in visited: - visited.add(item.GetValueAsUnsigned()) - yield item - # Prepare for the next iteration. - item = item.GetChildMemberWithName(next_item_name) - except: - # Exception occurred. Stop the generator. - pass - - return -''' - -# This supports the iteration protocol. -iter_def = " def __iter__(self): return lldb_iter(self, '%s', '%s')" -module_iter = " def module_iter(self): return lldb_iter(self, '%s', '%s')" -breakpoint_iter = " def breakpoint_iter(self): return lldb_iter(self, '%s', '%s')" -watchpoint_iter = " def watchpoint_iter(self): return lldb_iter(self, '%s', '%s')" -section_iter = " def section_iter(self): return lldb_iter(self, '%s', '%s')" -compile_unit_iter = " def compile_unit_iter(self): return lldb_iter(self, '%s', '%s')" - -# Called to implement the built-in function len(). -# Eligible objects are those containers with unambiguous iteration support. -len_def = " def __len__(self): return self.%s()" - -# This supports the rich comparison methods of __eq__ and __ne__. -eq_def = " def __eq__(self, other): return isinstance(other, %s) and %s" -ne_def = " def __ne__(self, other): return not self.__eq__(other)" - -# Called to implement truth value testing and the built-in operation bool(); -# Note that Python 2 uses __nonzero__(), whereas Python 3 uses __bool__() -# should return False or True, or their integer equivalents 0 or 1. -# Delegate to self.IsValid() if it is defined for the current lldb object. - -if six.PY2: - nonzero_def = " def __nonzero__(self): return self.IsValid()" -else: - nonzero_def = " def __bool__(self): return self.IsValid()" - -# A convenience iterator for SBSymbol! -symbol_in_section_iter_def = ''' - def symbol_in_section_iter(self, section): - """Given a module and its contained section, returns an iterator on the - symbols within the section.""" - for sym in self: - if in_range(sym, section): - yield sym -''' - -# -# This dictionary defines a mapping from classname to (getsize, getelem) tuple. -# -d = {'SBBreakpoint': ('GetNumLocations', 'GetLocationAtIndex'), - 'SBCompileUnit': ('GetNumLineEntries', 'GetLineEntryAtIndex'), - 'SBDebugger': ('GetNumTargets', 'GetTargetAtIndex'), - 'SBModule': ('GetNumSymbols', 'GetSymbolAtIndex'), - 'SBProcess': ('GetNumThreads', 'GetThreadAtIndex'), - 'SBSection': ('GetNumSubSections', 'GetSubSectionAtIndex'), - 'SBThread': ('GetNumFrames', 'GetFrameAtIndex'), - - 'SBInstructionList': ('GetSize', 'GetInstructionAtIndex'), - 'SBStringList': ('GetSize', 'GetStringAtIndex',), - 'SBSymbolContextList': ('GetSize', 'GetContextAtIndex'), - 'SBTypeList': ('GetSize', 'GetTypeAtIndex'), - 'SBValueList': ('GetSize', 'GetValueAtIndex'), - - 'SBType': ('GetNumberChildren', 'GetChildAtIndex'), - 'SBValue': ('GetNumChildren', 'GetChildAtIndex'), - - # SBTarget needs special processing, see below. - 'SBTarget': {'module': ('GetNumModules', 'GetModuleAtIndex'), - 'breakpoint': ('GetNumBreakpoints', 'GetBreakpointAtIndex'), - 'watchpoint': ('GetNumWatchpoints', 'GetWatchpointAtIndex') - }, - - # SBModule has an additional section_iter(), see below. - 'SBModule-section': ('GetNumSections', 'GetSectionAtIndex'), - # And compile_unit_iter(). - 'SBModule-compile-unit': ('GetNumCompileUnits', 'GetCompileUnitAtIndex'), - # As well as symbol_in_section_iter(). - 'SBModule-symbol-in-section': symbol_in_section_iter_def - } - -# -# This dictionary defines a mapping from classname to equality method name(s). -# -e = {'SBAddress': ['GetFileAddress', 'GetModule'], - 'SBBreakpoint': ['GetID'], - 'SBWatchpoint': ['GetID'], - 'SBFileSpec': ['GetFilename', 'GetDirectory'], - 'SBModule': ['GetFileSpec', 'GetUUIDString'], - 'SBType': ['GetByteSize', 'GetName'] - } - - -def list_to_frag(list): - """Transform a list to equality program fragment. - - For example, ['GetID'] is transformed to 'self.GetID() == other.GetID()', - and ['GetFilename', 'GetDirectory'] to 'self.GetFilename() == other.GetFilename() - and self.GetDirectory() == other.GetDirectory()'. - """ - if not list: - raise Exception("list should be non-empty") - frag = StringIO.StringIO() - for i in range(len(list)): - if i > 0: - frag.write(" and ") - frag.write("self.{0}() == other.{0}()".format(list[i])) - return frag.getvalue() - - -class NewContent(StringIO.StringIO): - """Simple facade to keep track of the previous line to be committed.""" - - def __init__(self): - StringIO.StringIO.__init__(self) - self.prev_line = None - - def add_line(self, a_line): - """Add a line to the content, if there is a previous line, commit it.""" - if self.prev_line is not None: - self.write(self.prev_line + "\n") - self.prev_line = a_line - - def del_line(self): - """Forget about the previous line, do not commit it.""" - self.prev_line = None - - def del_blank_line(self): - """Forget about the previous line if it is a blank line.""" - if self.prev_line is not None and not self.prev_line.strip(): - self.prev_line = None - - def finish(self): - """Call this when you're finished with populating content.""" - if self.prev_line is not None: - self.write(self.prev_line + "\n") - self.prev_line = None - -# The new content will have the iteration protocol defined for our lldb -# objects. -new_content = NewContent() - -with open(output_name, 'r') as f_in: - content = f_in.read() - -# The pattern for recognizing the SWIG Version string -version_pattern = re.compile("^# Version:? (.*)$") - -# The pattern for recognizing the beginning of an SB class definition. -class_pattern = re.compile("^class (SB.*)\(_object\):$") - -# The pattern for recognizing the beginning of the __init__ method definition. -init_pattern = re.compile("^ def __init__\(self.*\):") - -# The pattern for recognizing the beginning of the IsValid method definition. -isvalid_pattern = re.compile("^ def IsValid\(") - -# These define the states of our finite state machine. -EXPECTING_VERSION = 0 -NORMAL = 1 -DEFINING_ITERATOR = 2 -DEFINING_EQUALITY = 4 -CLEANUP_DOCSTRING = 8 - -# The lldb_iter_def only needs to be inserted once. -lldb_iter_defined = False - -# Our FSM begins its life in the NORMAL state, and transitions to the -# DEFINING_ITERATOR and/or DEFINING_EQUALITY state whenever it encounters the -# beginning of certain class definitions, see dictionaries 'd' and 'e' above. -# -# Note that the two states DEFINING_ITERATOR and DEFINING_EQUALITY are -# orthogonal in that our FSM can be in one, the other, or both states at the -# same time. During such time, the FSM is eagerly searching for the __init__ -# method definition in order to insert the appropriate method(s) into the lldb -# module. -# -# The state CLEANUP_DOCSTRING can be entered from either the NORMAL or the -# DEFINING_ITERATOR/EQUALITY states. While in this state, the FSM is fixing/ -# cleaning the Python docstrings generated by the swig docstring features. -# -# The FSM, in all possible states, also checks the current input for IsValid() -# definition, and inserts a __nonzero__() method definition to implement truth -# value testing and the built-in operation bool(). -state = EXPECTING_VERSION - -swig_version_tuple = None -for line in content.splitlines(): - # Handle the state transition into CLEANUP_DOCSTRING state as it is possible - # to enter this state from either NORMAL or DEFINING_ITERATOR/EQUALITY. - # - # If ' """' is the sole line, prepare to transition to the - # CLEANUP_DOCSTRING state or out of it. - - if line == toggle_docstring_cleanup_line: - if state & CLEANUP_DOCSTRING: - # Special handling of the trailing blank line right before the '"""' - # end docstring marker. - new_content.del_blank_line() - state ^= CLEANUP_DOCSTRING - else: - state |= CLEANUP_DOCSTRING - - if state == EXPECTING_VERSION: - # We haven't read the version yet, read it now. - if swig_version_tuple is None: - match = version_pattern.search(line) - if match: - v = match.group(1) - swig_version_tuple = tuple(map(int, (v.split(".")))) - elif not line.startswith('#'): - # This is the first non-comment line after the header. Inject the - # version - new_line = version_line % str(swig_version_tuple) - new_content.add_line(new_line) - state = NORMAL - - if state == NORMAL: - match = class_pattern.search(line) - # Inserts lldb_helpers and the lldb_iter() definition before the first - # class definition. - if not lldb_iter_defined and match: - new_content.add_line(lldb_helpers) - new_content.add_line(lldb_iter_def) - lldb_iter_defined = True - - # If we are at the beginning of the class definitions, prepare to - # transition to the DEFINING_ITERATOR/DEFINING_EQUALITY state for the - # right class names. - if match: - cls = match.group(1) - if cls in d: - # Adding support for iteration for the matched SB class. - state |= DEFINING_ITERATOR - if cls in e: - # Adding support for eq and ne for the matched SB class. - state |= DEFINING_EQUALITY - - if (state & DEFINING_ITERATOR) or (state & DEFINING_EQUALITY): - match = init_pattern.search(line) - if match: - # We found the beginning of the __init__ method definition. - # This is a good spot to insert the iter and/or eq-ne support. - # - # But note that SBTarget has three types of iterations. - if cls == "SBTarget": - new_content.add_line(module_iter % (d[cls]['module'])) - new_content.add_line(breakpoint_iter % (d[cls]['breakpoint'])) - new_content.add_line(watchpoint_iter % (d[cls]['watchpoint'])) - else: - if (state & DEFINING_ITERATOR): - new_content.add_line(iter_def % d[cls]) - new_content.add_line(len_def % d[cls][0]) - if (state & DEFINING_EQUALITY): - new_content.add_line(eq_def % (cls, list_to_frag(e[cls]))) - new_content.add_line(ne_def) - - # SBModule has extra SBSection, SBCompileUnit iterators and - # symbol_in_section_iter()! - if cls == "SBModule": - new_content.add_line(section_iter % d[cls + '-section']) - new_content.add_line(compile_unit_iter % - d[cls + '-compile-unit']) - new_content.add_line(d[cls + '-symbol-in-section']) - - # This special purpose iterator is for SBValue only!!! - if cls == "SBValue": - new_content.add_line(linked_list_iter_def) - - # Next state will be NORMAL. - state = NORMAL - - if (state & CLEANUP_DOCSTRING): - # Cleanse the lldb.py of the autodoc'ed residues. - if c_ifdef_swig in line or c_endif_swig in line: - continue - # As well as the comment marker line. - if c_comment_marker in line: - continue - - # Also remove the '\a ' and '\b 'substrings. - line = line.replace('\a ', '') - line = line.replace('\b ', '') - # And the leading '///' substring. - doxygen_comment_match = doxygen_comment_start.match(line) - if doxygen_comment_match: - line = line.replace(doxygen_comment_match.group(1), '', 1) - - line = char_to_str_xform(line) - - # Note that the transition out of CLEANUP_DOCSTRING is handled at the - # beginning of this function already. - - # This deals with one-liner docstring, for example, SBThread.GetName: - # """GetName(self) -> char""". - if one_liner_docstring_pattern.match(line): - line = char_to_str_xform(line) - - # Look for 'def IsValid(*args):', and once located, add implementation - # of truth value testing for this object by delegation. - if isvalid_pattern.search(line): - new_content.add_line(nonzero_def) - - # Pass the original line of content to new_content. - new_content.add_line(line) - -# We are finished with recording new content. -new_content.finish() - -with open(output_name, 'w') as f_out: - f_out.write(new_content.getvalue()) - f_out.write('''debugger_unique_id = 0 -SBDebugger.Initialize() -debugger = None -target = SBTarget() -process = SBProcess() -thread = SBThread() -frame = SBFrame()''') |