vendor/lldb/lldb-trunk-r256945

1 files changed, 486 insertions, 0 deletions

diff --git a/scripts/Python/modify-python-lldb.py b/scripts/Python/modify-python-lldb.py
new file mode 100644
index 0000000000000..56323d6679a17
--- /dev/null
+++ b/scripts/Python/modify-python-lldb.py
@@ -0,0 +1,486 @@
+#
+# 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, 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 != 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 != 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 != 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()''')
+