mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-24 03:33:20 +01:00
ae65e281f3
to reflect the new license. We understand that people may be surprised that we're moving the header entirely to discuss the new license. We checked this carefully with the Foundation's lawyer and we believe this is the correct approach. Essentially, all code in the project is now made available by the LLVM project under our new license, so you will see that the license headers include that license only. Some of our contributors have contributed code under our old license, and accordingly, we have retained a copy of our old license notice in the top-level files in each project and repository. llvm-svn: 351636
509 lines
16 KiB
Python
509 lines
16 KiB
Python
#===- object.py - Python Object Bindings --------------------*- python -*--===#
|
|
#
|
|
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
# See https://llvm.org/LICENSE.txt for license information.
|
|
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
#
|
|
#===------------------------------------------------------------------------===#
|
|
|
|
r"""
|
|
Object File Interface
|
|
=====================
|
|
|
|
This module provides an interface for reading information from object files
|
|
(e.g. binary executables and libraries).
|
|
|
|
Using this module, you can obtain information about an object file's sections,
|
|
symbols, and relocations. These are represented by the classes ObjectFile,
|
|
Section, Symbol, and Relocation, respectively.
|
|
|
|
Usage
|
|
-----
|
|
|
|
The only way to use this module is to start by creating an ObjectFile. You can
|
|
create an ObjectFile by loading a file (specified by its path) or by creating a
|
|
llvm.core.MemoryBuffer and loading that.
|
|
|
|
Once you have an object file, you can inspect its sections and symbols directly
|
|
by calling get_sections() and get_symbols() respectively. To inspect
|
|
relocations, call get_relocations() on a Section instance.
|
|
|
|
Iterator Interface
|
|
------------------
|
|
|
|
The LLVM bindings expose iteration over sections, symbols, and relocations in a
|
|
way that only allows one instance to be operated on at a single time. This is
|
|
slightly annoying from a Python perspective, as it isn't very Pythonic to have
|
|
objects that "expire" but are still active from a dynamic language.
|
|
|
|
To aid working around this limitation, each Section, Symbol, and Relocation
|
|
instance caches its properties after first access. So, if the underlying
|
|
iterator is advanced, the properties can still be obtained provided they have
|
|
already been retrieved.
|
|
|
|
In addition, we also provide a "cache" method on each class to cache all
|
|
available data. You can call this on each obtained instance. Or, you can pass
|
|
cache=True to the appropriate get_XXX() method to have this done for you.
|
|
|
|
Here are some examples on how to perform iteration:
|
|
|
|
obj = ObjectFile(filename='/bin/ls')
|
|
|
|
# This is OK. Each Section is only accessed inside its own iteration slot.
|
|
section_names = []
|
|
for section in obj.get_sections():
|
|
section_names.append(section.name)
|
|
|
|
# This is NOT OK. You perform a lookup after the object has expired.
|
|
symbols = list(obj.get_symbols())
|
|
for symbol in symbols:
|
|
print symbol.name # This raises because the object has expired.
|
|
|
|
# In this example, we mix a working and failing scenario.
|
|
symbols = []
|
|
for symbol in obj.get_symbols():
|
|
symbols.append(symbol)
|
|
print symbol.name
|
|
|
|
for symbol in symbols:
|
|
print symbol.name # OK
|
|
print symbol.address # NOT OK. We didn't look up this property before.
|
|
|
|
# Cache everything up front.
|
|
symbols = list(obj.get_symbols(cache=True))
|
|
for symbol in symbols:
|
|
print symbol.name # OK
|
|
|
|
"""
|
|
|
|
from ctypes import c_char_p
|
|
from ctypes import c_char
|
|
from ctypes import POINTER
|
|
from ctypes import c_uint64
|
|
from ctypes import string_at
|
|
|
|
from .common import CachedProperty
|
|
from .common import LLVMObject
|
|
from .common import c_object_p
|
|
from .common import get_library
|
|
from .core import MemoryBuffer
|
|
|
|
__all__ = [
|
|
"lib",
|
|
"ObjectFile",
|
|
"Relocation",
|
|
"Section",
|
|
"Symbol",
|
|
]
|
|
|
|
class ObjectFile(LLVMObject):
|
|
"""Represents an object/binary file."""
|
|
|
|
def __init__(self, filename=None, contents=None):
|
|
"""Construct an instance from a filename or binary data.
|
|
|
|
filename must be a path to a file that can be opened with open().
|
|
contents can be either a native Python buffer type (like str) or a
|
|
llvm.core.MemoryBuffer instance.
|
|
"""
|
|
if contents:
|
|
assert isinstance(contents, MemoryBuffer)
|
|
|
|
if filename is not None:
|
|
contents = MemoryBuffer(filename=filename)
|
|
|
|
if contents is None:
|
|
raise Exception('No input found.')
|
|
|
|
ptr = lib.LLVMCreateObjectFile(contents)
|
|
LLVMObject.__init__(self, ptr, disposer=lib.LLVMDisposeObjectFile)
|
|
self.take_ownership(contents)
|
|
|
|
def get_sections(self, cache=False):
|
|
"""Obtain the sections in this object file.
|
|
|
|
This is a generator for llvm.object.Section instances.
|
|
|
|
Sections are exposed as limited-use objects. See the module's
|
|
documentation on iterators for more.
|
|
"""
|
|
sections = lib.LLVMGetSections(self)
|
|
last = None
|
|
while True:
|
|
if lib.LLVMIsSectionIteratorAtEnd(self, sections):
|
|
break
|
|
|
|
last = Section(sections)
|
|
if cache:
|
|
last.cache()
|
|
|
|
yield last
|
|
|
|
lib.LLVMMoveToNextSection(sections)
|
|
last.expire()
|
|
|
|
if last is not None:
|
|
last.expire()
|
|
|
|
lib.LLVMDisposeSectionIterator(sections)
|
|
|
|
def get_symbols(self, cache=False):
|
|
"""Obtain the symbols in this object file.
|
|
|
|
This is a generator for llvm.object.Symbol instances.
|
|
|
|
Each Symbol instance is a limited-use object. See this module's
|
|
documentation on iterators for more.
|
|
"""
|
|
symbols = lib.LLVMGetSymbols(self)
|
|
last = None
|
|
while True:
|
|
if lib.LLVMIsSymbolIteratorAtEnd(self, symbols):
|
|
break
|
|
|
|
last = Symbol(symbols, self)
|
|
if cache:
|
|
last.cache()
|
|
|
|
yield last
|
|
|
|
lib.LLVMMoveToNextSymbol(symbols)
|
|
last.expire()
|
|
|
|
if last is not None:
|
|
last.expire()
|
|
|
|
lib.LLVMDisposeSymbolIterator(symbols)
|
|
|
|
class Section(LLVMObject):
|
|
"""Represents a section in an object file."""
|
|
|
|
def __init__(self, ptr):
|
|
"""Construct a new section instance.
|
|
|
|
Section instances can currently only be created from an ObjectFile
|
|
instance. Therefore, this constructor should not be used outside of
|
|
this module.
|
|
"""
|
|
LLVMObject.__init__(self, ptr)
|
|
|
|
self.expired = False
|
|
|
|
@CachedProperty
|
|
def name(self):
|
|
"""Obtain the string name of the section.
|
|
|
|
This is typically something like '.dynsym' or '.rodata'.
|
|
"""
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
return lib.LLVMGetSectionName(self)
|
|
|
|
@CachedProperty
|
|
def size(self):
|
|
"""The size of the section, in long bytes."""
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
return lib.LLVMGetSectionSize(self)
|
|
|
|
@CachedProperty
|
|
def contents(self):
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
siz = self.size
|
|
|
|
r = lib.LLVMGetSectionContents(self)
|
|
if r:
|
|
return string_at(r, siz)
|
|
return None
|
|
|
|
@CachedProperty
|
|
def address(self):
|
|
"""The address of this section, in long bytes."""
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
return lib.LLVMGetSectionAddress(self)
|
|
|
|
def has_symbol(self, symbol):
|
|
"""Returns whether a Symbol instance is present in this Section."""
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
assert isinstance(symbol, Symbol)
|
|
return lib.LLVMGetSectionContainsSymbol(self, symbol)
|
|
|
|
def get_relocations(self, cache=False):
|
|
"""Obtain the relocations in this Section.
|
|
|
|
This is a generator for llvm.object.Relocation instances.
|
|
|
|
Each instance is a limited used object. See this module's documentation
|
|
on iterators for more.
|
|
"""
|
|
if self.expired:
|
|
raise Exception('Section instance has expired.')
|
|
|
|
relocations = lib.LLVMGetRelocations(self)
|
|
last = None
|
|
while True:
|
|
if lib.LLVMIsRelocationIteratorAtEnd(self, relocations):
|
|
break
|
|
|
|
last = Relocation(relocations)
|
|
if cache:
|
|
last.cache()
|
|
|
|
yield last
|
|
|
|
lib.LLVMMoveToNextRelocation(relocations)
|
|
last.expire()
|
|
|
|
if last is not None:
|
|
last.expire()
|
|
|
|
lib.LLVMDisposeRelocationIterator(relocations)
|
|
|
|
def cache(self):
|
|
"""Cache properties of this Section.
|
|
|
|
This can be called as a workaround to the single active Section
|
|
limitation. When called, the properties of the Section are fetched so
|
|
they are still available after the Section has been marked inactive.
|
|
"""
|
|
getattr(self, 'name')
|
|
getattr(self, 'size')
|
|
getattr(self, 'contents')
|
|
getattr(self, 'address')
|
|
|
|
def expire(self):
|
|
"""Expire the section.
|
|
|
|
This is called internally by the section iterator.
|
|
"""
|
|
self.expired = True
|
|
|
|
class Symbol(LLVMObject):
|
|
"""Represents a symbol in an object file."""
|
|
def __init__(self, ptr, object_file):
|
|
assert isinstance(ptr, c_object_p)
|
|
assert isinstance(object_file, ObjectFile)
|
|
|
|
LLVMObject.__init__(self, ptr)
|
|
|
|
self.expired = False
|
|
self._object_file = object_file
|
|
|
|
@CachedProperty
|
|
def name(self):
|
|
"""The str name of the symbol.
|
|
|
|
This is often a function or variable name. Keep in mind that name
|
|
mangling could be in effect.
|
|
"""
|
|
if self.expired:
|
|
raise Exception('Symbol instance has expired.')
|
|
|
|
return lib.LLVMGetSymbolName(self)
|
|
|
|
@CachedProperty
|
|
def address(self):
|
|
"""The address of this symbol, in long bytes."""
|
|
if self.expired:
|
|
raise Exception('Symbol instance has expired.')
|
|
|
|
return lib.LLVMGetSymbolAddress(self)
|
|
|
|
@CachedProperty
|
|
def size(self):
|
|
"""The size of the symbol, in long bytes."""
|
|
if self.expired:
|
|
raise Exception('Symbol instance has expired.')
|
|
|
|
return lib.LLVMGetSymbolSize(self)
|
|
|
|
@CachedProperty
|
|
def section(self):
|
|
"""The Section to which this Symbol belongs.
|
|
|
|
The returned Section instance does not expire, unlike Sections that are
|
|
commonly obtained through iteration.
|
|
|
|
Because this obtains a new section iterator each time it is accessed,
|
|
calling this on a number of Symbol instances could be expensive.
|
|
"""
|
|
sections = lib.LLVMGetSections(self._object_file)
|
|
lib.LLVMMoveToContainingSection(sections, self)
|
|
|
|
return Section(sections)
|
|
|
|
def cache(self):
|
|
"""Cache all cacheable properties."""
|
|
getattr(self, 'name')
|
|
getattr(self, 'address')
|
|
getattr(self, 'size')
|
|
|
|
def expire(self):
|
|
"""Mark the object as expired to prevent future API accesses.
|
|
|
|
This is called internally by this module and it is unlikely that
|
|
external callers have a legitimate reason for using it.
|
|
"""
|
|
self.expired = True
|
|
|
|
class Relocation(LLVMObject):
|
|
"""Represents a relocation definition."""
|
|
def __init__(self, ptr):
|
|
"""Create a new relocation instance.
|
|
|
|
Relocations are created from objects derived from Section instances.
|
|
Therefore, this constructor should not be called outside of this
|
|
module. See Section.get_relocations() for the proper method to obtain
|
|
a Relocation instance.
|
|
"""
|
|
assert isinstance(ptr, c_object_p)
|
|
|
|
LLVMObject.__init__(self, ptr)
|
|
|
|
self.expired = False
|
|
|
|
@CachedProperty
|
|
def offset(self):
|
|
"""The offset of this relocation, in long bytes."""
|
|
if self.expired:
|
|
raise Exception('Relocation instance has expired.')
|
|
|
|
return lib.LLVMGetRelocationOffset(self)
|
|
|
|
@CachedProperty
|
|
def symbol(self):
|
|
"""The Symbol corresponding to this Relocation."""
|
|
if self.expired:
|
|
raise Exception('Relocation instance has expired.')
|
|
|
|
ptr = lib.LLVMGetRelocationSymbol(self)
|
|
return Symbol(ptr)
|
|
|
|
@CachedProperty
|
|
def type_number(self):
|
|
"""The relocation type, as a long."""
|
|
if self.expired:
|
|
raise Exception('Relocation instance has expired.')
|
|
|
|
return lib.LLVMGetRelocationType(self)
|
|
|
|
@CachedProperty
|
|
def type_name(self):
|
|
"""The relocation type's name, as a str."""
|
|
if self.expired:
|
|
raise Exception('Relocation instance has expired.')
|
|
|
|
return lib.LLVMGetRelocationTypeName(self)
|
|
|
|
@CachedProperty
|
|
def value_string(self):
|
|
if self.expired:
|
|
raise Exception('Relocation instance has expired.')
|
|
|
|
return lib.LLVMGetRelocationValueString(self)
|
|
|
|
def expire(self):
|
|
"""Expire this instance, making future API accesses fail."""
|
|
self.expired = True
|
|
|
|
def cache(self):
|
|
"""Cache all cacheable properties on this instance."""
|
|
getattr(self, 'address')
|
|
getattr(self, 'offset')
|
|
getattr(self, 'symbol')
|
|
getattr(self, 'type')
|
|
getattr(self, 'type_name')
|
|
getattr(self, 'value_string')
|
|
|
|
def register_library(library):
|
|
"""Register function prototypes with LLVM library instance."""
|
|
|
|
# Object.h functions
|
|
library.LLVMCreateObjectFile.argtypes = [MemoryBuffer]
|
|
library.LLVMCreateObjectFile.restype = c_object_p
|
|
|
|
library.LLVMDisposeObjectFile.argtypes = [ObjectFile]
|
|
|
|
library.LLVMGetSections.argtypes = [ObjectFile]
|
|
library.LLVMGetSections.restype = c_object_p
|
|
|
|
library.LLVMDisposeSectionIterator.argtypes = [c_object_p]
|
|
|
|
library.LLVMIsSectionIteratorAtEnd.argtypes = [ObjectFile, c_object_p]
|
|
library.LLVMIsSectionIteratorAtEnd.restype = bool
|
|
|
|
library.LLVMMoveToNextSection.argtypes = [c_object_p]
|
|
|
|
library.LLVMMoveToContainingSection.argtypes = [c_object_p, c_object_p]
|
|
|
|
library.LLVMGetSymbols.argtypes = [ObjectFile]
|
|
library.LLVMGetSymbols.restype = c_object_p
|
|
|
|
library.LLVMDisposeSymbolIterator.argtypes = [c_object_p]
|
|
|
|
library.LLVMIsSymbolIteratorAtEnd.argtypes = [ObjectFile, c_object_p]
|
|
library.LLVMIsSymbolIteratorAtEnd.restype = bool
|
|
|
|
library.LLVMMoveToNextSymbol.argtypes = [c_object_p]
|
|
|
|
library.LLVMGetSectionName.argtypes = [c_object_p]
|
|
library.LLVMGetSectionName.restype = c_char_p
|
|
|
|
library.LLVMGetSectionSize.argtypes = [c_object_p]
|
|
library.LLVMGetSectionSize.restype = c_uint64
|
|
|
|
library.LLVMGetSectionContents.argtypes = [c_object_p]
|
|
# Can't use c_char_p here as it isn't a NUL-terminated string.
|
|
library.LLVMGetSectionContents.restype = POINTER(c_char)
|
|
|
|
library.LLVMGetSectionAddress.argtypes = [c_object_p]
|
|
library.LLVMGetSectionAddress.restype = c_uint64
|
|
|
|
library.LLVMGetSectionContainsSymbol.argtypes = [c_object_p, c_object_p]
|
|
library.LLVMGetSectionContainsSymbol.restype = bool
|
|
|
|
library.LLVMGetRelocations.argtypes = [c_object_p]
|
|
library.LLVMGetRelocations.restype = c_object_p
|
|
|
|
library.LLVMDisposeRelocationIterator.argtypes = [c_object_p]
|
|
|
|
library.LLVMIsRelocationIteratorAtEnd.argtypes = [c_object_p, c_object_p]
|
|
library.LLVMIsRelocationIteratorAtEnd.restype = bool
|
|
|
|
library.LLVMMoveToNextRelocation.argtypes = [c_object_p]
|
|
|
|
library.LLVMGetSymbolName.argtypes = [Symbol]
|
|
library.LLVMGetSymbolName.restype = c_char_p
|
|
|
|
library.LLVMGetSymbolAddress.argtypes = [Symbol]
|
|
library.LLVMGetSymbolAddress.restype = c_uint64
|
|
|
|
library.LLVMGetSymbolSize.argtypes = [Symbol]
|
|
library.LLVMGetSymbolSize.restype = c_uint64
|
|
|
|
library.LLVMGetRelocationOffset.argtypes = [c_object_p]
|
|
library.LLVMGetRelocationOffset.restype = c_uint64
|
|
|
|
library.LLVMGetRelocationSymbol.argtypes = [c_object_p]
|
|
library.LLVMGetRelocationSymbol.restype = c_object_p
|
|
|
|
library.LLVMGetRelocationType.argtypes = [c_object_p]
|
|
library.LLVMGetRelocationType.restype = c_uint64
|
|
|
|
library.LLVMGetRelocationTypeName.argtypes = [c_object_p]
|
|
library.LLVMGetRelocationTypeName.restype = c_char_p
|
|
|
|
library.LLVMGetRelocationValueString.argtypes = [c_object_p]
|
|
library.LLVMGetRelocationValueString.restype = c_char_p
|
|
|
|
lib = get_library()
|
|
register_library(lib)
|