bindings/python/llvm/object.py

   1 #===- object.py - Python Object Bindings --------------------*- python -*--===#
   2 #
   3 #                     The LLVM Compiler Infrastructure
   4 #
   5 # This file is distributed under the University of Illinois Open Source
   6 # License. See LICENSE.TXT for details.
   7 #
   8 #===------------------------------------------------------------------------===#
   9
  10 r"""
  11 Object File Interface
  12 =====================
  13
  14 This module provides an interface for reading information from object files
  15 (e.g. binary executables and libraries).
  16
  17 Using this module, you can obtain information about an object file's sections,
  18 symbols, and relocations. These are represented by the classes ObjectFile,
  19 Section, Symbol, and Relocation, respectively.
  20
  21 Usage
  22 -----
  23
  24 The only way to use this module is to start by creating an ObjectFile. You can
  25 create an ObjectFile by loading a file (specified by its path) or by creating a
  26 llvm.core.MemoryBuffer and loading that.
  27
  28 Once you have an object file, you can inspect its sections and symbols directly
  29 by calling get_sections() and get_symbols() respectively. To inspect
  30 relocations, call get_relocations() on a Section instance.
  31
  32 Iterator Interface
  33 ------------------
  34
  35 The LLVM bindings expose iteration over sections, symbols, and relocations in a
  36 way that only allows one instance to be operated on at a single time. This is
  37 slightly annoying from a Python perspective, as it isn't very Pythonic to have
  38 objects that "expire" but are still active from a dynamic language.
  39
  40 To aid working around this limitation, each Section, Symbol, and Relocation
  41 instance caches its properties after first access. So, if the underlying
  42 iterator is advanced, the properties can still be obtained provided they have
  43 already been retrieved.
  44
  45 In addition, we also provide a "cache" method on each class to cache all
  46 available data. You can call this on each obtained instance. Or, you can pass
  47 cache=True to the appropriate get_XXX() method to have this done for you.
  48
  49 Here are some examples on how to perform iteration:
  50
  51     obj = ObjectFile(filename='/bin/ls')
  52
  53     # This is OK. Each Section is only accessed inside its own iteration slot.
  54     section_names = []
  55     for section in obj.get_sections():
  56         section_names.append(section.name)
  57
  58     # This is NOT OK. You perform a lookup after the object has expired.
  59     symbols = list(obj.get_symbols())
  60     for symbol in symbols:
  61         print symbol.name # This raises because the object has expired.
  62
  63     # In this example, we mix a working and failing scenario.
  64     symbols = []
  65     for symbol in obj.get_symbols():
  66         symbols.append(symbol)
  67         print symbol.name
  68
  69     for symbol in symbols:
  70         print symbol.name # OK
  71         print symbol.address # NOT OK. We didn't look up this property before.
  72
  73     # Cache everything up front.
  74     symbols = list(obj.get_symbols(cache=True))
  75     for symbol in symbols:
  76         print symbol.name # OK
  77
  78 """
  79
  80 from ctypes import c_char_p
  81 from ctypes import c_char
  82 from ctypes import POINTER
  83 from ctypes import c_uint64
  84 from ctypes import string_at
  85
  86 from .common import CachedProperty
  87 from .common import LLVMObject
  88 from .common import c_object_p
  89 from .common import get_library
  90 from .core import MemoryBuffer
  91
  92 __all__ = [
  93     "lib",
  94     "ObjectFile",
  95     "Relocation",
  96     "Section",
  97     "Symbol",
  98 ]
  99
 100 class ObjectFile(LLVMObject):
 101     """Represents an object/binary file."""
 102
 103     def __init__(self, filename=None, contents=None):
 104         """Construct an instance from a filename or binary data.
 105
 106         filename must be a path to a file that can be opened with open().
 107         contents can be either a native Python buffer type (like str) or a
 108         llvm.core.MemoryBuffer instance.
 109         """
 110         if contents:
 111             assert isinstance(contents, MemoryBuffer)
 112
 113         if filename is not None:
 114             contents = MemoryBuffer(filename=filename)
 115
 116         if contents is None:
 117             raise Exception('No input found.')
 118
 119         ptr = lib.LLVMCreateObjectFile(contents)
 120         LLVMObject.__init__(self, ptr, disposer=lib.LLVMDisposeObjectFile)
 121         self.take_ownership(contents)
 122
 123     def get_sections(self, cache=False):
 124         """Obtain the sections in this object file.
 125
 126         This is a generator for llvm.object.Section instances.
 127
 128         Sections are exposed as limited-use objects. See the module's
 129         documentation on iterators for more.
 130         """
 131         sections = lib.LLVMGetSections(self)
 132         last = None
 133         while True:
 134             if lib.LLVMIsSectionIteratorAtEnd(self, sections):
 135                 break
 136
 137             last = Section(sections)
 138             if cache:
 139                 last.cache()
 140
 141             yield last
 142
 143             lib.LLVMMoveToNextSection(sections)
 144             last.expire()
 145
 146         if last is not None:
 147             last.expire()
 148
 149         lib.LLVMDisposeSectionIterator(sections)
 150
 151     def get_symbols(self, cache=False):
 152         """Obtain the symbols in this object file.
 153
 154         This is a generator for llvm.object.Symbol instances.
 155
 156         Each Symbol instance is a limited-use object. See this module's
 157         documentation on iterators for more.
 158         """
 159         symbols = lib.LLVMGetSymbols(self)
 160         last = None
 161         while True:
 162             if lib.LLVMIsSymbolIteratorAtEnd(self, symbols):
 163                 break
 164
 165             last = Symbol(symbols, self)
 166             if cache:
 167                 last.cache()
 168
 169             yield last
 170
 171             lib.LLVMMoveToNextSymbol(symbols)
 172             last.expire()
 173
 174         if last is not None:
 175             last.expire()
 176
 177         lib.LLVMDisposeSymbolIterator(symbols)
 178
 179 class Section(LLVMObject):
 180     """Represents a section in an object file."""
 181
 182     def __init__(self, ptr):
 183         """Construct a new section instance.
 184
 185         Section instances can currently only be created from an ObjectFile
 186         instance. Therefore, this constructor should not be used outside of
 187         this module.
 188         """
 189         LLVMObject.__init__(self, ptr)
 190
 191         self.expired = False
 192
 193     @CachedProperty
 194     def name(self):
 195         """Obtain the string name of the section.
 196
 197         This is typically something like '.dynsym' or '.rodata'.
 198         """
 199         if self.expired:
 200             raise Exception('Section instance has expired.')
 201
 202         return lib.LLVMGetSectionName(self)
 203
 204     @CachedProperty
 205     def size(self):
 206         """The size of the section, in long bytes."""
 207         if self.expired:
 208             raise Exception('Section instance has expired.')
 209
 210         return lib.LLVMGetSectionSize(self)
 211
 212     @CachedProperty
 213     def contents(self):
 214         if self.expired:
 215             raise Exception('Section instance has expired.')
 216
 217         siz = self.size
 218
 219         r = lib.LLVMGetSectionContents(self)
 220         if r:
 221             return string_at(r, siz)
 222         return None
 223
 224     @CachedProperty
 225     def address(self):
 226         """The address of this section, in long bytes."""
 227         if self.expired:
 228             raise Exception('Section instance has expired.')
 229
 230         return lib.LLVMGetSectionAddress(self)
 231
 232     def has_symbol(self, symbol):
 233         """Returns whether a Symbol instance is present in this Section."""
 234         if self.expired:
 235             raise Exception('Section instance has expired.')
 236
 237         assert isinstance(symbol, Symbol)
 238         return lib.LLVMGetSectionContainsSymbol(self, symbol)
 239
 240     def get_relocations(self, cache=False):
 241         """Obtain the relocations in this Section.
 242
 243         This is a generator for llvm.object.Relocation instances.
 244
 245         Each instance is a limited used object. See this module's documentation
 246         on iterators for more.
 247         """
 248         if self.expired:
 249             raise Exception('Section instance has expired.')
 250
 251         relocations = lib.LLVMGetRelocations(self)
 252         last = None
 253         while True:
 254             if lib.LLVMIsRelocationIteratorAtEnd(self, relocations):
 255                 break
 256
 257             last = Relocation(relocations)
 258             if cache:
 259                 last.cache()
 260
 261             yield last
 262
 263             lib.LLVMMoveToNextRelocation(relocations)
 264             last.expire()
 265
 266         if last is not None:
 267             last.expire()
 268
 269         lib.LLVMDisposeRelocationIterator(relocations)
 270
 271     def cache(self):
 272         """Cache properties of this Section.
 273
 274         This can be called as a workaround to the single active Section
 275         limitation. When called, the properties of the Section are fetched so
 276         they are still available after the Section has been marked inactive.
 277         """
 278         getattr(self, 'name')
 279         getattr(self, 'size')
 280         getattr(self, 'contents')
 281         getattr(self, 'address')
 282
 283     def expire(self):
 284         """Expire the section.
 285
 286         This is called internally by the section iterator.
 287         """
 288         self.expired = True
 289
 290 class Symbol(LLVMObject):
 291     """Represents a symbol in an object file."""
 292     def __init__(self, ptr, object_file):
 293         assert isinstance(ptr, c_object_p)
 294         assert isinstance(object_file, ObjectFile)
 295
 296         LLVMObject.__init__(self, ptr)
 297
 298         self.expired = False
 299         self._object_file = object_file
 300
 301     @CachedProperty
 302     def name(self):
 303         """The str name of the symbol.
 304
 305         This is often a function or variable name. Keep in mind that name
 306         mangling could be in effect.
 307         """
 308         if self.expired:
 309             raise Exception('Symbol instance has expired.')
 310
 311         return lib.LLVMGetSymbolName(self)
 312
 313     @CachedProperty
 314     def address(self):
 315         """The address of this symbol, in long bytes."""
 316         if self.expired:
 317             raise Exception('Symbol instance has expired.')
 318
 319         return lib.LLVMGetSymbolAddress(self)
 320
 321     @CachedProperty
 322     def size(self):
 323         """The size of the symbol, in long bytes."""
 324         if self.expired:
 325             raise Exception('Symbol instance has expired.')
 326
 327         return lib.LLVMGetSymbolSize(self)
 328
 329     @CachedProperty
 330     def section(self):
 331         """The Section to which this Symbol belongs.
 332
 333         The returned Section instance does not expire, unlike Sections that are
 334         commonly obtained through iteration.
 335
 336         Because this obtains a new section iterator each time it is accessed,
 337         calling this on a number of Symbol instances could be expensive.
 338         """
 339         sections = lib.LLVMGetSections(self._object_file)
 340         lib.LLVMMoveToContainingSection(sections, self)
 341
 342         return Section(sections)
 343
 344     def cache(self):
 345         """Cache all cacheable properties."""
 346         getattr(self, 'name')
 347         getattr(self, 'address')
 348         getattr(self, 'size')
 349
 350     def expire(self):
 351         """Mark the object as expired to prevent future API accesses.
 352
 353         This is called internally by this module and it is unlikely that
 354         external callers have a legitimate reason for using it.
 355         """
 356         self.expired = True
 357
 358 class Relocation(LLVMObject):
 359     """Represents a relocation definition."""
 360     def __init__(self, ptr):
 361         """Create a new relocation instance.
 362
 363         Relocations are created from objects derived from Section instances.
 364         Therefore, this constructor should not be called outside of this
 365         module. See Section.get_relocations() for the proper method to obtain
 366         a Relocation instance.
 367         """
 368         assert isinstance(ptr, c_object_p)
 369
 370         LLVMObject.__init__(self, ptr)
 371
 372         self.expired = False
 373
 374     @CachedProperty
 375     def address(self):
 376         """The address of this relocation, in long bytes."""
 377         if self.expired:
 378             raise Exception('Relocation instance has expired.')
 379
 380         return lib.LLVMGetRelocationAddress(self)
 381
 382     @CachedProperty
 383     def offset(self):
 384         """The offset of this relocation, in long bytes."""
 385         if self.expired:
 386             raise Exception('Relocation instance has expired.')
 387
 388         return lib.LLVMGetRelocationOffset(self)
 389
 390     @CachedProperty
 391     def symbol(self):
 392         """The Symbol corresponding to this Relocation."""
 393         if self.expired:
 394             raise Exception('Relocation instance has expired.')
 395
 396         ptr = lib.LLVMGetRelocationSymbol(self)
 397         return Symbol(ptr)
 398
 399     @CachedProperty
 400     def type_number(self):
 401         """The relocation type, as a long."""
 402         if self.expired:
 403             raise Exception('Relocation instance has expired.')
 404
 405         return lib.LLVMGetRelocationType(self)
 406
 407     @CachedProperty
 408     def type_name(self):
 409         """The relocation type's name, as a str."""
 410         if self.expired:
 411             raise Exception('Relocation instance has expired.')
 412
 413         return lib.LLVMGetRelocationTypeName(self)
 414
 415     @CachedProperty
 416     def value_string(self):
 417         if self.expired:
 418             raise Exception('Relocation instance has expired.')
 419
 420         return lib.LLVMGetRelocationValueString(self)
 421
 422     def expire(self):
 423         """Expire this instance, making future API accesses fail."""
 424         self.expired = True
 425
 426     def cache(self):
 427         """Cache all cacheable properties on this instance."""
 428         getattr(self, 'address')
 429         getattr(self, 'offset')
 430         getattr(self, 'symbol')
 431         getattr(self, 'type')
 432         getattr(self, 'type_name')
 433         getattr(self, 'value_string')
 434
 435 def register_library(library):
 436     """Register function prototypes with LLVM library instance."""
 437
 438     # Object.h functions
 439     library.LLVMCreateObjectFile.argtypes = [MemoryBuffer]
 440     library.LLVMCreateObjectFile.restype = c_object_p
 441
 442     library.LLVMDisposeObjectFile.argtypes = [ObjectFile]
 443
 444     library.LLVMGetSections.argtypes = [ObjectFile]
 445     library.LLVMGetSections.restype = c_object_p
 446
 447     library.LLVMDisposeSectionIterator.argtypes = [c_object_p]
 448
 449     library.LLVMIsSectionIteratorAtEnd.argtypes = [ObjectFile, c_object_p]
 450     library.LLVMIsSectionIteratorAtEnd.restype = bool
 451
 452     library.LLVMMoveToNextSection.argtypes = [c_object_p]
 453
 454     library.LLVMMoveToContainingSection.argtypes = [c_object_p, c_object_p]
 455
 456     library.LLVMGetSymbols.argtypes = [ObjectFile]
 457     library.LLVMGetSymbols.restype = c_object_p
 458
 459     library.LLVMDisposeSymbolIterator.argtypes = [c_object_p]
 460
 461     library.LLVMIsSymbolIteratorAtEnd.argtypes = [ObjectFile, c_object_p]
 462     library.LLVMIsSymbolIteratorAtEnd.restype = bool
 463
 464     library.LLVMMoveToNextSymbol.argtypes = [c_object_p]
 465
 466     library.LLVMGetSectionName.argtypes = [c_object_p]
 467     library.LLVMGetSectionName.restype = c_char_p
 468
 469     library.LLVMGetSectionSize.argtypes = [c_object_p]
 470     library.LLVMGetSectionSize.restype = c_uint64
 471
 472     library.LLVMGetSectionContents.argtypes = [c_object_p]
 473     # Can't use c_char_p here as it isn't a NUL-terminated string.
 474     library.LLVMGetSectionContents.restype = POINTER(c_char)
 475
 476     library.LLVMGetSectionAddress.argtypes = [c_object_p]
 477     library.LLVMGetSectionAddress.restype = c_uint64
 478
 479     library.LLVMGetSectionContainsSymbol.argtypes = [c_object_p, c_object_p]
 480     library.LLVMGetSectionContainsSymbol.restype = bool
 481
 482     library.LLVMGetRelocations.argtypes = [c_object_p]
 483     library.LLVMGetRelocations.restype = c_object_p
 484
 485     library.LLVMDisposeRelocationIterator.argtypes = [c_object_p]
 486
 487     library.LLVMIsRelocationIteratorAtEnd.argtypes = [c_object_p, c_object_p]
 488     library.LLVMIsRelocationIteratorAtEnd.restype = bool
 489
 490     library.LLVMMoveToNextRelocation.argtypes = [c_object_p]
 491
 492     library.LLVMGetSymbolName.argtypes = [Symbol]
 493     library.LLVMGetSymbolName.restype = c_char_p
 494
 495     library.LLVMGetSymbolAddress.argtypes = [Symbol]
 496     library.LLVMGetSymbolAddress.restype = c_uint64
 497
 498     library.LLVMGetSymbolSize.argtypes = [Symbol]
 499     library.LLVMGetSymbolSize.restype = c_uint64
 500
 501     library.LLVMGetRelocationAddress.argtypes = [c_object_p]
 502     library.LLVMGetRelocationAddress.restype = c_uint64
 503
 504     library.LLVMGetRelocationOffset.argtypes = [c_object_p]
 505     library.LLVMGetRelocationOffset.restype = c_uint64
 506
 507     library.LLVMGetRelocationSymbol.argtypes = [c_object_p]
 508     library.LLVMGetRelocationSymbol.restype = c_object_p
 509
 510     library.LLVMGetRelocationType.argtypes = [c_object_p]
 511     library.LLVMGetRelocationType.restype = c_uint64
 512
 513     library.LLVMGetRelocationTypeName.argtypes = [c_object_p]
 514     library.LLVMGetRelocationTypeName.restype = c_char_p
 515
 516     library.LLVMGetRelocationValueString.argtypes = [c_object_p]
 517     library.LLVMGetRelocationValueString.restype = c_char_p
 518
 519 lib = get_library()
 520 register_library(lib)