ROSE  0.11.145.0
Classes | Typedefs | Functions | Variables
Rose::BinaryAnalysis::Disassembler Namespace Reference

Description

Instruction decoders.

A "disassembler" in ROSE is any class capable of decoding a sequence of bytes to construct a single SgAsmInstruction AST. All decoders derive from the Disassembler::Base decoder whose most important member function is disassembleOne, which decodes one instruction from a byte sequence specified by a MemoryMap and a virtual address (VA) within the map.

A new instruction set architecture (ISA) can be added to ROSE without modifying the ROSE source code. One does this by deriving a new decoder class from the Disassembler::Base class and registering an instance of the class with Disassembler::registerFactory. The new class has a canDisassemble predicate that examines a file header (such as an ELF Header or PE Header) to see if the decoder is appropriate. Decoders can also be looked up by their names. Once the correct decoder is found, its clone method is called to create a copy that's used for the actual decoding.

Classes

class  Base
 Virtual base class for instruction disassemblers. More...
 
class  Cil
 CIL Disassembler. More...
 
class  Exception
 Exception thrown by the disassemblers. More...
 
class  Jvm
 JVM Disassembler. More...
 
class  M68k
 Disassembler for Motorola M68k-based instruction set architectures. More...
 
class  Mips
 
class  Null
 Disassembler for nothing. More...
 
class  Powerpc
 Disassembler for the PowerPC architecture. More...
 
class  X86
 Disassembler for the x86 architecture. More...
 

Typedefs

typedef Map< rose_addr_t, SgAsmInstruction * > InstructionMap
 The InstructionMap is a mapping from (absolute) virtual address to disassembled instruction. More...
 
using BasePtr = Sawyer::SharedPointer< Base >
 Reference counted pointer for disassemblers. More...
 
using Aarch32Ptr = Sawyer::SharedPointer< Aarch32 >
 Reference counted pointer for ARM Aarch32 decoder. More...
 
using Aarch64Ptr = Sawyer::SharedPointer< Aarch64 >
 Reference counted pointer for ARM Aarch64 decoder. More...
 
using M68kPtr = Sawyer::SharedPointer< M68k >
 Reference counted pointer for Motorola M68k decoder. More...
 
using MipsPtr = Sawyer::SharedPointer< Mips >
 Reference counted pointer for Mips decoder. More...
 
using NullPtr = Sawyer::SharedPointer< Null >
 Reference counted pointer for Null decoder. More...
 
using PowerpcPtr = Sawyer::SharedPointer< Powerpc >
 Reference counted pointer for Powerpc decoder. More...
 
using X86Ptr = Sawyer::SharedPointer< X86 >
 Reference counted pointer for Intel X86 decoder. More...
 

Functions

void initDiagnostics ()
 Initializes and registers disassembler diagnostic streams. More...
 
BasePtr lookup (SgAsmGenericHeader *)
 Finds a suitable disassembler for a file header. More...
 
BasePtr lookup (SgAsmInterpretation *)
 Finds a suitable disassembler for a binary interpretation. More...
 
BasePtr lookup (const std::string &)
 Finds a suitable disassembler by name. More...
 
std::vector< std::string > isaNames ()
 List of names recognized by lookup. More...
 
void registerFactory (const BasePtr &)
 Append a disassembler factory to the registry. More...
 
bool deregisterFactory (const BasePtr &)
 Remove a disassembler factory from the registry. More...
 
std::vector< BasePtrregisteredFactories ()
 Returns all registered disassembler factories. More...
 
const std::string & name (const BasePtr &)
 Disassembler name free function. More...
 

Variables

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

Typedef Documentation

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

Definition at line 31 of file Disassembler/Base.h.

Reference counted pointer for disassemblers.

Definition at line 29 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for ARM Aarch32 decoder.

Definition at line 32 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for ARM Aarch64 decoder.

Definition at line 35 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for Motorola M68k decoder.

Definition at line 38 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for Mips decoder.

Definition at line 41 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for Null decoder.

Definition at line 44 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for Powerpc decoder.

Definition at line 47 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Reference counted pointer for Intel X86 decoder.

Definition at line 50 of file BinaryAnalysis/Disassembler/BasicTypes.h.

Function Documentation

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

Initializes and registers disassembler diagnostic streams.

See Diagnostics::initialize().

BasePtr Rose::BinaryAnalysis::Disassembler::lookup ( SgAsmGenericHeader )

Finds a suitable disassembler for a file header.

Looks through the list of registered disassembler factories (from most recently registered to earliest registered) and returns a clone of 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.

BasePtr Rose::BinaryAnalysis::Disassembler::lookup ( SgAsmInterpretation )

Finds a suitable disassembler for a binary interpretation.

Looks through the list of registered disassembler factories (from most recently registered to earliest registered) and returns a clone of 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.

BasePtr Rose::BinaryAnalysis::Disassembler::lookup ( const std::string &  )

Finds a suitable disassembler by name.

Looks through the list of registered disassembler factories (from most recently registered to earliest registered) and returns a clone of the first one whose name matches the specified string. If the specified string is "list" then the list of disassembler names obtained by isaNames is printed to standard output and the program exits. Otherwise if no matching disassembler is found, an Exception is thrown.

Thread safety: This function is thread safe.

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

List of names recognized by lookup.

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

Thread safety: This function is thread safe.

void Rose::BinaryAnalysis::Disassembler::registerFactory ( const BasePtr )

Append a disassembler factory to the registry.

This stores a reference to the specified disassembler factory. A factory is simply a disassembler that will never be used to decode any instructions. It's only purpose is to hold settings, to test whether it matches any of the lookup functions, and to produce by its clone method a new disassembler that's able to decode instructions. The various lookup functions will always call the factory's clone method when returning a disassembler.

More specific disassembler instances should be registered after more general disassemblers since the lookup() method will inspect disassemblers in reverse order of their registration. The ROSE library always initializes the front of the list with its own disassemblers, but they can be deregistered if desired.

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.

bool Rose::BinaryAnalysis::Disassembler::deregisterFactory ( const BasePtr )

Remove a disassembler factory from the registry.

The most recent occurrence of the specified disassembler factory is removed from the registry if it exists.

Returns true if anything was removed; false otherwise.

Thread safety: This function is thread safe.

std::vector<BasePtr> Rose::BinaryAnalysis::Disassembler::registeredFactories ( )

Returns all registered disassembler factories.

The returned value points to the dissemblers that were registered without cloning any of them. These objects are technically disassembler factories that need to be cloned before they can disassemble anything.

Thread safety: This function is thread safe.

const std::string& Rose::BinaryAnalysis::Disassembler::name ( const BasePtr )

Disassembler name free function.

This is a convenient way to obtain a disassembler's name without having to include "Base.h", and is therfore useful in header files that try to include a minimal number of type definitions.

Variable Documentation

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

Disassembler diagnostic streams.