ROSE  0.9.9.109
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Rose::BinaryAnalysis::InstructionProvider Class Reference

Description

Provides and caches instructions.

This class returns an instruction for a given address, caching the instruction so that the same instruction is returned each time the same address is specified. If an instruction cannot be returned because it doesn't exist then a null pointer should be returned. If an instruction cannot be disassembled at the specified address then an "unknown" instruction should be returned.

An instruction provider normally uses a supplied disassembler to obtain instructions that aren't in its cache. However, the user can initialize the cache explicitly and turn off the ability to call a disassembler. A disassembler is always required regardless of whether its used to obtain new instructions because the disassembler has the canonical information about the machine architecture: what registers are defined, which registers are the program counter and stack pointer, which instruction semantics dispatcher can be used with the instructions, etc.

Definition at line 28 of file InstructionProvider.h.

#include <InstructionProvider.h>

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

Public Types

typedef Sawyer::SharedPointer< InstructionProviderPtr
 Shared-ownership pointer to an InstructionProvider. More...
 
typedef Sawyer::Container::Map< rose_addr_t, SgAsmInstruction * > InsnMap
 Mapping from address to instruction. More...
 

Public Member Functions

SgAsmInstructionoperator[] (rose_addr_t va) const
 Returns the instruction at the specified virtual address, or null. More...
 
void insert (SgAsmInstruction *)
 Insert an instruction into the cache. More...
 
Disassemblerdisassembler () const
 Returns the disassembler. More...
 
size_t nCached () const
 Returns number of cached starting addresses. More...
 
const RegisterDictionaryregisterDictionary () const
 Returns the register dictionary. More...
 
const CallingConvention::DictionarycallingConventions () const
 Returns the calling convention dictionary. More...
 
RegisterDescriptor instructionPointerRegister () const
 Register used as the instruction pointer. More...
 
RegisterDescriptor stackPointerRegister () const
 Register used as a user-mode stack pointer. More...
 
RegisterDescriptor stackSegmentRegister () const
 Register used as a segment to access stack memory. More...
 
ByteOrder::Endianness defaultByteOrder () const
 Default memory byte order. More...
 
InstructionSemantics2::BaseSemantics::DispatcherPtr dispatcher () const
 Instruction dispatcher. More...
 
bool isDisassemblerEnabled () const
 Enable or disable the disassembler. More...
 
void enableDisassembler (bool enable=true)
 Enable or disable the disassembler. More...
 
void disableDisassembler ()
 Enable or disable the disassembler. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 

Static Public Member Functions

static Ptr instance (Disassembler *disassembler, const MemoryMap::Ptr &map)
 Static allocating Constructor. More...
 

Protected Member Functions

 InstructionProvider (Disassembler *disassembler, const MemoryMap::Ptr &map)
 

Member Typedef Documentation

Shared-ownership pointer to an InstructionProvider.

See Shared ownership.

Definition at line 31 of file InstructionProvider.h.

Mapping from address to instruction.

Definition at line 34 of file InstructionProvider.h.

Member Function Documentation

static Ptr Rose::BinaryAnalysis::InstructionProvider::instance ( Disassembler disassembler,
const MemoryMap::Ptr map 
)
inlinestatic

Static allocating Constructor.

The disassembler is required even if the user plans to turn off the ability to obtain instructions from the disassembler. The memory map should be configured so that all segments that potentially contain instructions have execute permission. Any readable/nonwritable segments will be considered to be constant for the life of the specimen. For instance, if a linking step has initialized the dynamic linking tables then those tables can be marked as readable and non-writable so that indirect jumps through the table will result in concrete execution addresses.

The disassembler is owned by the caller and should not be freed until after the instruction provider is destroyed. The memory map is copied into the instruction provider.

Definition at line 99 of file InstructionProvider.h.

bool Rose::BinaryAnalysis::InstructionProvider::isDisassemblerEnabled ( ) const
inline

Enable or disable the disassembler.

When the disassembler is disabled then it is not called when a new instruction is needed, but rather a null instruction pointer is returned (and cached).

Definition at line 109 of file InstructionProvider.h.

void Rose::BinaryAnalysis::InstructionProvider::enableDisassembler ( bool  enable = true)
inline

Enable or disable the disassembler.

When the disassembler is disabled then it is not called when a new instruction is needed, but rather a null instruction pointer is returned (and cached).

Definition at line 112 of file InstructionProvider.h.

void Rose::BinaryAnalysis::InstructionProvider::disableDisassembler ( )
inline

Enable or disable the disassembler.

When the disassembler is disabled then it is not called when a new instruction is needed, but rather a null instruction pointer is returned (and cached).

Definition at line 116 of file InstructionProvider.h.

SgAsmInstruction* Rose::BinaryAnalysis::InstructionProvider::operator[] ( rose_addr_t  va) const

Returns the instruction at the specified virtual address, or null.

If the virtual address is non-executable then a null pointer is returned, otherwise either a valid instruction or an "unknown" instruction is returned. An "unknown" instruction is used for cases where a valid instruction could not be disassembled, including the case when the first byte of a multi-byte instruction is executable but the remaining bytes are not executable.

void Rose::BinaryAnalysis::InstructionProvider::insert ( SgAsmInstruction )

Insert an instruction into the cache.

This instruction provider saves a pointer to the instruction without taking ownership. If an instruction already exists at the new instruction's address then the new instruction replaces the old instruction.

Disassembler* Rose::BinaryAnalysis::InstructionProvider::disassembler ( ) const
inline

Returns the disassembler.

Returns the disassembler pointer provided in the constructor. The disassembler is not owned by this instruction provider, but must not be freed until after the instruction provider is destroyed.

Definition at line 139 of file InstructionProvider.h.

size_t Rose::BinaryAnalysis::InstructionProvider::nCached ( ) const
inline

Returns number of cached starting addresses.

The number of cached starting addresses includes those addresses where an instruction exists, and those addresses where an instruction is known to not exist.

This is a constant-time operation.

Definition at line 147 of file InstructionProvider.h.

References Sawyer::Container::Map< K, T, Cmp, Alloc >::size().

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

Returns the register dictionary.

Definition at line 150 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::registerDictionary().

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

Returns the calling convention dictionary.

Definition at line 153 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::callingConventions().

RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::instructionPointerRegister ( ) const
inline

Register used as the instruction pointer.

Definition at line 156 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::instructionPointerRegister().

RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::stackPointerRegister ( ) const
inline

Register used as a user-mode stack pointer.

Definition at line 159 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::stackPointerRegister().

RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::stackSegmentRegister ( ) const
inline

Register used as a segment to access stack memory.

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

Definition at line 164 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::stackSegmentRegister().

ByteOrder::Endianness Rose::BinaryAnalysis::InstructionProvider::defaultByteOrder ( ) const
inline

Default memory byte order.

Definition at line 167 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::byteOrder().

InstructionSemantics2::BaseSemantics::DispatcherPtr Rose::BinaryAnalysis::InstructionProvider::dispatcher ( ) const
inline

Instruction dispatcher.

Returns a pointer to a dispatcher used for instruction semantics. Not all architectures support instruction semantics, in which case a null pointer is returned. The returned dispatcher is not connected to any semantic domain, so it can only be used to call its virtual constructor to create a valid dispatcher.

Definition at line 174 of file InstructionProvider.h.

References Rose::BinaryAnalysis::Disassembler::dispatcher().


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