//tools/binary_size: Add Disassemble() to console.py. Tweak metadata.

tools/binary_size/models.py

 # Copyright 2017 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
-"""Classes that comprise the data model for binary size analysis."""
+"""Classes that comprise the data model for binary size analysis.
+
+The primary classes are Symbol, and SymbolGroup.
+
+Description of common properties:
+  * address: The start address of the symbol.
+        May be 0 (e.g. for .bss or for SymbolGroups).
+  * size: The number of bytes this symbol takes up, including padding that comes
+       before |address|.
+  * padding: The number of bytes of padding before |address| due to this symbol.
+  * name: Symbol names with parameter list removed.
+        Never None, but will be '' for anonymous symbols.
+  * full_name: Symbols names with parameter list left in.
+       Never None, but will be '' for anonymous symbols, and for symbols that do
+       not contain a parameter list.
+  * is_anonymous: True when the symbol exists in an anonymous namespace (which
+       are removed from both full_name and name during normalization).
+  * section_name: E.g. ".text", ".rodata", ".data.rel.local"
+  * section: The second character of |section_name|. E.g. "t", "r", "d".
+"""
 
 import collections
 import copy
 import os
 import re
 
 import match_util
 
 
+METADATA_GIT_REVISION = 'git_revision'
+METADATA_MAP_FILENAME = 'map_file_name'
+METADATA_ELF_FILENAME = 'elf_file_name'
+METADATA_ELF_MTIME = 'elf_mtime'  # int timestamp in utc.
+METADATA_ELF_BUILD_ID = 'elf_build_id'
+
 SECTION_TO_SECTION_NAME = {
     'b': '.bss',
     'd': '.data',
     'r': '.rodata',
     't': '.text',
 }
 
 
 class SizeInfo(object):
   """Represents all size information for a single binary.
 
   Fields:
     section_sizes: A dict of section_name -> size.
     symbols: A SymbolGroup (or SymbolDiff) with all symbols in it.
+    metadata: A dict.
   """
   __slots__ = (
       'section_sizes',
       'symbols',
-      'tag',
-      'timestamp',
+      'metadata',
   )
 
   """Root size information."""
-  def __init__(self, section_sizes, symbols, timestamp=None, tag=''):
+  def __init__(self, section_sizes, symbols, metadata=None):
     self.section_sizes = section_sizes  # E.g. {'.text': 0}
     self.symbols = symbols  # List of symbols sorted by address per-section.
-    self.timestamp = timestamp  # UTC datetime object.
-    self.tag = tag  # E.g. git revision.
-    assert not tag or '\n' not in tag  # Simplifies file format.
+    self.metadata = metadata or {}
 
 
 class BaseSymbol(object):
-  """Base class for Symbol and SymbolGroup."""
+  """Base class for Symbol and SymbolGroup.
+
+  Refer to module docs for field descriptions.
+  """
   __slots__ = ()
 
   @property
   def section(self):
     """Returns the one-letter section.
 
     E.g. If section_name == '.rodata', then section == 'r'.
     """
     return self.section_name[1]
 
@@ skipping 19 matching lines @@
   def _Key(self):
     """Returns a tuple that can be used to see if two Symbol are the same.
 
     Keys are not guaranteed to be unique within a SymbolGroup. For example, it
     is common to have multiple "** merge strings" symbols, which will have a
     common key."""
     return (self.section_name, self.full_name or self.name)
 
 
 class Symbol(BaseSymbol):
-  """Represents a single symbol within a binary."""
+  """Represents a single symbol within a binary.
+
+  Refer to module docs for field descriptions.
+  """
 
   __slots__ = (
       'address',
       'full_name',
       'is_anonymous',
       'object_path',
       'name',
       'padding',
       'section_name',
       'source_path',
@@ skipping 482 matching lines @@
 
 def _ExtractPrefixBeforeSeparator(string, separator, count=1):
   idx = -len(separator)
   prev_idx = None
   for _ in xrange(count):
     idx = string.find(separator, idx + len(separator))
     if idx < 0:
       break
     prev_idx = idx
   return string[:prev_idx]