ROSE  0.11.96.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Attributes | Static Protected Attributes | List of all members
Rose::BinaryAnalysis::Disassembler Class Referenceabstract

Description

Virtual base class for instruction disassemblers.

The Disassembler class is a virtual class providing all non-architecture-specific functionality for disassembling instructions; architecture-specific components are in subclasses DisassemblerAarch64, DisassemblerPowerpc, DisassemblerX86, and others. In general, there is no need to explicitly instantiate or call functions in any of these subclasses. A Disassembler is responsible for disassembling a single instruction at a time at some specified address, whereas the classes in Rose::BinaryAnalysis::Partitioner2 are responsible for deciding what addresses should be disassembled.

The main interface to a Disassembler is the disassembleOne method. It tries to disassemble one instruction at the specified address from a supplied MemoryMap. A MemoryMap object represents the data in a virtual address space. On success, it returns an instance of a subclass of SgAsmInstruction, which serves as the root of an abstract syntax tree (AST) that containins information about the instruction. The instruction operands are represented by the subclasses of SgAsmExpression. If an error occurs during the disassembly of a single instruction, the disassembler will throw an exception.

New architectures can be added to ROSE without modifying any ROSE source code. One does this by subclassing an existing disassembler, overriding any necessary virtual methods, and registering an instance of the subclass with register_subclass. If the new subclass can handle multiple architectures then a disassembler should be registered for each of those architectures.When ROSE needs to disassemble something, it calls lookup, which in turn calls the can_disassemble method for all registered disassemblers. The first disassembler whose can_disassemble returns true is used for the disassembly.

Definition at line 50 of file Disassembler.h.

#include <Rose/BinaryAnalysis/Disassembler.h>

Inheritance diagram for Rose::BinaryAnalysis::Disassembler:
Inheritance graph
[legend]
Collaboration diagram for Rose::BinaryAnalysis::Disassembler:
Collaboration graph
[legend]

Classes

class  Exception
 Exception thrown by the disassemblers. More...
 

Public Types

typedef Map< rose_addr_t, SgAsmInstruction * > InstructionMap
 The InstructionMap is a mapping from (absolute) virtual address to disassembled instruction. More...
 

Public Member Functions

virtual bool canDisassemble (SgAsmGenericHeader *) const =0
 Predicate determining the suitability of a disassembler for a specific file header. More...
 
virtual Disassemblerclone () const =0
 Creates a new copy of a disassembler. More...
 
virtual Unparser::BasePtr unparser () const =0
 Unparser. More...
 
size_t instructionAlignment () const
 Property: Instruction alignment requirement. More...
 
virtual RegisterDescriptor instructionPointerRegister () const
 Returns the register that points to instructions. More...
 
virtual RegisterDescriptor stackPointerRegister () const
 Returns the register that points to the stack. More...
 
virtual RegisterDescriptor stackFrameRegister () const
 Returns the register that ponts to the stack frame. More...
 
virtual RegisterDescriptor stackSegmentRegister () const
 Returns the segment register for accessing the stack. More...
 
virtual RegisterDescriptor callReturnRegister () const
 Returns the register that holds the return address for a function. More...
 
const Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::DispatcherPtrdispatcher () const
 Return an instruction semantics dispatcher if possible. More...
 
virtual SgAsmInstructiondisassembleOne (const MemoryMap::Ptr &map, rose_addr_t start_va, AddressSet *successors=NULL)=0
 This is the lowest level disassembly function and is implemented in the architecture-specific subclasses. More...
 
SgAsmInstructiondisassembleOne (const unsigned char *buf, rose_addr_t buf_va, size_t buf_size, rose_addr_t start_va, AddressSet *successors=NULL)
 Similar in functionality to the disassembleOne method that takes a MemoryMap argument, except the content buffer is mapped 1:1 to virtual memory beginning at the specified address. More...
 
virtual SgAsmInstructionmakeUnknownInstruction (const Exception &)=0
 Makes an unknown instruction from an exception. More...
 
void mark_referenced_instructions (SgAsmInterpretation *, const MemoryMap::Ptr &, const InstructionMap &)
 Marks parts of the file that correspond to instructions as having been referenced. More...
 
AddressSet get_block_successors (const InstructionMap &, bool &complete)
 Calculates the successor addresses of a basic block and adds them to a successors set. More...
 
const std::string & name () const
 Property: Name by which disassembler is registered.
 
void name (const std::string &s)
 Property: Name by which disassembler is registered.
 
ByteOrder::Endianness byteOrder () const
 Property: Byte order of instructions in memory.
 
void byteOrder (ByteOrder::Endianness sex)
 Property: Byte order of instructions in memory.
 
size_t wordSizeBytes () const
 Property: Basic word size in bytes.
 
void wordSizeBytes (size_t nbytes)
 Property: Basic word size in bytes.
 
void registerDictionary (const RegisterDictionary *rdict)
 Properties: Register dictionary. More...
 
const RegisterDictionaryregisterDictionary () const
 Properties: Register dictionary. More...
 
const CallingConvention::DictionarycallingConventions () const
 Property: Calling convention dictionary. More...
 
CallingConvention::DictionarycallingConventions ()
 Properties: Register dictionary. More...
 
void callingConventions (const CallingConvention::Dictionary &d)
 Properties: Register dictionary. More...
 

Static Public Member Functions

static void registerSubclass (Disassembler *)
 Register a disassembler instance. More...
 
static Disassemblerlookup (SgAsmGenericHeader *)
 Finds a suitable disassembler. More...
 
static std::vector< std::string > isaNames ()
 List of names recognized by lookup. More...
 
static Disassemblerlookup (SgAsmInterpretation *)
 Finds a suitable disassembler. More...
 
static Disassemblerlookup (const std::string &)
 Finds a suitable disassembler. More...
 
static void initDiagnostics ()
 Initializes and registers disassembler diagnostic streams. More...
 

Static Public Attributes

static Sawyer::Message::Facility mlog
 Disassembler diagnostic streams. More...
 

Protected Attributes

const RegisterDictionaryp_registers
 Description of registers available for this platform. More...
 
RegisterDescriptor REG_IP
 
RegisterDescriptor REG_SP
 
RegisterDescriptor REG_SS
 
RegisterDescriptor REG_SF
 
RegisterDescriptor REG_LINK
 Register descriptors initialized during construction. More...
 
ByteOrder::Endianness p_byteOrder
 Byte order of instructions in memory. More...
 
size_t p_wordSizeBytes
 Basic word size in bytes. More...
 
std::string p_name
 Name by which this dissassembler is registered. More...
 
size_t instructionAlignment_
 Positive alignment constraint for instruction addresses. More...
 
InstructionSemantics::BaseSemantics::DispatcherPtr p_proto_dispatcher
 Prototypical dispatcher for creating real dispatchers.
 

Static Protected Attributes

static std::vector< Disassembler * > disassemblers
 List of disassembler subclasses. More...
 

Member Typedef Documentation

The InstructionMap is a mapping from (absolute) virtual address to disassembled instruction.

Definition at line 90 of file Disassembler.h.

Member Function Documentation

static void Rose::BinaryAnalysis::Disassembler::registerSubclass ( Disassembler )
static

Register a disassembler instance.

More specific disassembler instances should be registered after more general disassemblers since the lookup() method will inspect disassemblers in reverse order of their registration.

Thread safety: Multiple threads can register disassemblers simultaneously. However, one seldom does this because the order that disassemblers are registered determines which disassembler is returned by the lookup() class methods.

virtual bool Rose::BinaryAnalysis::Disassembler::canDisassemble ( SgAsmGenericHeader ) const
pure virtual

Predicate determining the suitability of a disassembler for a specific file header.

If this disassembler is capable of disassembling machine code described by the specified file header, then this predicate returns true, otherwise it returns false.

Thread safety: The thread safety of this virtual method depends on the implementation in the subclass.

Implemented in Rose::BinaryAnalysis::DisassemblerCil, Rose::BinaryAnalysis::DisassemblerX86, Rose::BinaryAnalysis::DisassemblerM68k, Rose::BinaryAnalysis::DisassemblerPowerpc, Rose::BinaryAnalysis::DisassemblerJvm, Rose::BinaryAnalysis::DisassemblerNull, and Rose::BinaryAnalysis::DisassemblerMips.

static Disassembler* Rose::BinaryAnalysis::Disassembler::lookup ( SgAsmGenericHeader )
static

Finds a suitable disassembler.

Looks through the list of registered disassembler instances (from most recently registered to earliest registered) and returns the first one whose can_disassemble() predicate returns true. Throws an exception if no suitable disassembler can be found.

Thread safety: Multiple threads can call this class method simultaneously even when other threads are registering additional disassemblers.

static std::vector<std::string> Rose::BinaryAnalysis::Disassembler::isaNames ( )
static

List of names recognized by lookup.

Returns the list of names that the lookup method recognizes. These are the disassemblers that are actually enabled in this configuration of ROSE.

static Disassembler* Rose::BinaryAnalysis::Disassembler::lookup ( SgAsmInterpretation )
static

Finds a suitable disassembler.

Looks through the list of registered disassembler instances (from most recently registered to earliest registered) and returns the first one whose can_disassemble() predicate returns true. This is done for each header contained in the interpretation and the disassembler for each header must match the other headers. An exception is thrown if no suitable disassembler can be found.

Thread safety: Multiple threads can call this class method simultaneously even when other threads are registering additional disassembles. However, no other thread can be changing attributes of the specified interpretation, particularly the list of file headers referenced by the interpretation.

static Disassembler* Rose::BinaryAnalysis::Disassembler::lookup ( const std::string &  )
static

Finds a suitable disassembler.

Looks up a common disassembler by name. If the name is the word "list" then a list of known names is printed to std::cout.

virtual Disassembler* Rose::BinaryAnalysis::Disassembler::clone ( ) const
pure virtual

Creates a new copy of a disassembler.

The new copy has all the same settings as the original.

Thread safety: The thread safety of this virtual method depends on the implementation in the subclass.

Implemented in Rose::BinaryAnalysis::DisassemblerCil, Rose::BinaryAnalysis::DisassemblerM68k, Rose::BinaryAnalysis::DisassemblerX86, Rose::BinaryAnalysis::DisassemblerPowerpc, Rose::BinaryAnalysis::DisassemblerJvm, Rose::BinaryAnalysis::DisassemblerNull, and Rose::BinaryAnalysis::DisassemblerMips.

virtual Unparser::BasePtr Rose::BinaryAnalysis::Disassembler::unparser ( ) const
pure virtual
size_t Rose::BinaryAnalysis::Disassembler::instructionAlignment ( ) const

Property: Instruction alignment requirement.

The alignment that's required for instruction addresses. The return value is a positive number of bytes.

Referenced by Rose::BinaryAnalysis::InstructionProvider::instructionAlignment().

void Rose::BinaryAnalysis::Disassembler::registerDictionary ( const RegisterDictionary rdict)
inline

Properties: Register dictionary.

Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.

Thread safety: It is not safe to change the register dictionary while another thread is using this same Disassembler object.

Definition at line 250 of file Disassembler.h.

Referenced by Rose::BinaryAnalysis::InstructionProvider::registerDictionary().

const RegisterDictionary* Rose::BinaryAnalysis::Disassembler::registerDictionary ( ) const
inline

Properties: Register dictionary.

Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.

Thread safety: It is not safe to change the register dictionary while another thread is using this same Disassembler object.

Definition at line 253 of file Disassembler.h.

References p_registers.

const CallingConvention::Dictionary& Rose::BinaryAnalysis::Disassembler::callingConventions ( ) const
inline

Property: Calling convention dictionary.

This is a dictionary of the common calling conventions for this architecture.

Definition at line 262 of file Disassembler.h.

Referenced by Rose::BinaryAnalysis::InstructionProvider::callingConventions().

CallingConvention::Dictionary& Rose::BinaryAnalysis::Disassembler::callingConventions ( )
inline

Properties: Register dictionary.

Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.

Thread safety: It is not safe to change the register dictionary while another thread is using this same Disassembler object.

Definition at line 263 of file Disassembler.h.

void Rose::BinaryAnalysis::Disassembler::callingConventions ( const CallingConvention::Dictionary d)
inline

Properties: Register dictionary.

Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.

Thread safety: It is not safe to change the register dictionary while another thread is using this same Disassembler object.

Definition at line 264 of file Disassembler.h.

virtual RegisterDescriptor Rose::BinaryAnalysis::Disassembler::instructionPointerRegister ( ) const
inlinevirtual

Returns the register that points to instructions.

Definition at line 268 of file Disassembler.h.

References Rose::BinaryAnalysis::RegisterDescriptor::isEmpty().

Referenced by Rose::BinaryAnalysis::InstructionProvider::instructionPointerRegister().

virtual RegisterDescriptor Rose::BinaryAnalysis::Disassembler::stackPointerRegister ( ) const
inlinevirtual

Returns the register that points to the stack.

Definition at line 274 of file Disassembler.h.

References Rose::BinaryAnalysis::RegisterDescriptor::isEmpty().

Referenced by Rose::BinaryAnalysis::InstructionProvider::stackPointerRegister().

virtual RegisterDescriptor Rose::BinaryAnalysis::Disassembler::stackFrameRegister ( ) const
inlinevirtual

Returns the register that ponts to the stack frame.

Definition at line 280 of file Disassembler.h.

Referenced by Rose::BinaryAnalysis::InstructionProvider::stackFrameRegister().

virtual RegisterDescriptor Rose::BinaryAnalysis::Disassembler::stackSegmentRegister ( ) const
inlinevirtual

Returns the segment register for accessing the stack.

Not all architectures have this register, in which case the default-constructed register descriptor is returned.

Definition at line 286 of file Disassembler.h.

Referenced by Rose::BinaryAnalysis::InstructionProvider::stackSegmentRegister().

virtual RegisterDescriptor Rose::BinaryAnalysis::Disassembler::callReturnRegister ( ) const
inlinevirtual

Returns the register that holds the return address for a function.

If the architecture doesn't have such a register then a default constructed descriptor is returned.

Definition at line 293 of file Disassembler.h.

References REG_LINK.

Referenced by Rose::BinaryAnalysis::InstructionProvider::callReturnRegister().

const Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::DispatcherPtr& Rose::BinaryAnalysis::Disassembler::dispatcher ( ) const
inline

Return an instruction semantics dispatcher if possible.

If instruction semantics are implemented for this architecure then return a pointer to a dispatcher. The dispatcher will have no attached RISC operators and can only be used to create a new dispatcher via its virtual constructor. If instruction semantics are not implemented then the null pointer is returned.

Definition at line 302 of file Disassembler.h.

References p_proto_dispatcher.

Referenced by Rose::BinaryAnalysis::InstructionProvider::dispatcher().

static void Rose::BinaryAnalysis::Disassembler::initDiagnostics ( )
static

Initializes and registers disassembler diagnostic streams.

See Diagnostics::initialize().

virtual SgAsmInstruction* Rose::BinaryAnalysis::Disassembler::disassembleOne ( const MemoryMap::Ptr map,
rose_addr_t  start_va,
AddressSet successors = NULL 
)
pure virtual

This is the lowest level disassembly function and is implemented in the architecture-specific subclasses.

It disassembles one instruction at the specified virtual address. The map is a mapping from virtual addresses to buffer and enables instructions to span file segments that are mapped contiguously in virtual memory by the loader but which might not be contiguous in the file. The instruction's successor virtual addresses are added to the optional successor set (note that successors of an individual instruction can also be obtained via SgAsmInstruction::getSuccessors). If the instruction cannot be disassembled then an exception is thrown and the successors set is not modified.

Thread safety: The safety of this method depends on its implementation in the subclass. In any case, no other thread can be modifying the MemoryMap or successors set at the same time.

Implemented in Rose::BinaryAnalysis::DisassemblerCil, Rose::BinaryAnalysis::DisassemblerX86, Rose::BinaryAnalysis::DisassemblerM68k, Rose::BinaryAnalysis::DisassemblerPowerpc, Rose::BinaryAnalysis::DisassemblerJvm, Rose::BinaryAnalysis::DisassemblerNull, and Rose::BinaryAnalysis::DisassemblerMips.

SgAsmInstruction* Rose::BinaryAnalysis::Disassembler::disassembleOne ( const unsigned char *  buf,
rose_addr_t  buf_va,
size_t  buf_size,
rose_addr_t  start_va,
AddressSet successors = NULL 
)

Similar in functionality to the disassembleOne method that takes a MemoryMap argument, except the content buffer is mapped 1:1 to virtual memory beginning at the specified address.

Thread safety: The safety of this method depends on the implementation of the disassembleOne() defined in the subclass. If the subclass is thread safe then this method can be called in multiple threads as long as the supplied buffer and successors set are not being modified by another thread.

virtual SgAsmInstruction* Rose::BinaryAnalysis::Disassembler::makeUnknownInstruction ( const Exception )
pure virtual
void Rose::BinaryAnalysis::Disassembler::mark_referenced_instructions ( SgAsmInterpretation ,
const MemoryMap::Ptr ,
const InstructionMap  
)

Marks parts of the file that correspond to instructions as having been referenced.

Thread safety: This method is not thread safe.

AddressSet Rose::BinaryAnalysis::Disassembler::get_block_successors ( const InstructionMap ,
bool &  complete 
)

Calculates the successor addresses of a basic block and adds them to a successors set.

The successors is always non-null when called. If the function is able to determine the complete set of successors then it should set complete to true before returning.

Thread safety: Thread safe provided no other thread is modifying the specified instruction map.

Member Data Documentation

const RegisterDictionary* Rose::BinaryAnalysis::Disassembler::p_registers
protected

Description of registers available for this platform.

Definition at line 100 of file Disassembler.h.

Referenced by registerDictionary().

RegisterDescriptor Rose::BinaryAnalysis::Disassembler::REG_LINK
protected

Register descriptors initialized during construction.

Definition at line 101 of file Disassembler.h.

Referenced by callReturnRegister().

std::vector<Disassembler*> Rose::BinaryAnalysis::Disassembler::disassemblers
staticprotected

List of disassembler subclasses.

Definition at line 102 of file Disassembler.h.

ByteOrder::Endianness Rose::BinaryAnalysis::Disassembler::p_byteOrder
protected

Byte order of instructions in memory.

Definition at line 103 of file Disassembler.h.

Referenced by byteOrder().

size_t Rose::BinaryAnalysis::Disassembler::p_wordSizeBytes
protected

Basic word size in bytes.

Definition at line 104 of file Disassembler.h.

Referenced by wordSizeBytes().

std::string Rose::BinaryAnalysis::Disassembler::p_name
protected

Name by which this dissassembler is registered.

Definition at line 105 of file Disassembler.h.

Referenced by name().

size_t Rose::BinaryAnalysis::Disassembler::instructionAlignment_
protected

Positive alignment constraint for instruction addresses.

Definition at line 106 of file Disassembler.h.

Sawyer::Message::Facility Rose::BinaryAnalysis::Disassembler::mlog
static

Disassembler diagnostic streams.

Definition at line 112 of file Disassembler.h.


The documentation for this class was generated from the following file: