ROSE 0.11.145.147
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 32 of file InstructionProvider.h.

#include <Rose/BinaryAnalysis/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.
 
typedef Sawyer::Container::HashMap< rose_addr_t, SgAsmInstruction * > InsnMap
 Mapping from address to instruction.
 

Public Member Functions

bool isDisassemblerEnabled () const
 Enable or disable the disassembler.
 
SgAsmInstructionoperator[] (rose_addr_t va) const
 Returns the instruction at the specified virtual address, or null.
 
void insert (SgAsmInstruction *)
 Insert an instruction into the cache.
 
Disassembler::BasePtr disassembler () const
 Returns the disassembler.
 
size_t nCached () const
 Returns number of cached starting addresses.
 
RegisterDictionaryPtr registerDictionary () const
 Returns the register dictionary.
 
const CallingConvention::DictionarycallingConventions () const
 Returns the calling convention dictionary.
 
RegisterDescriptor instructionPointerRegister () const
 Register used as the instruction pointer.
 
RegisterDescriptor stackPointerRegister () const
 Register used as a user-mode stack pointer.
 
RegisterDescriptor stackFrameRegister () const
 Register used for function call frames.
 
RegisterDescriptor callReturnRegister () const
 Register holding a function call's return address.
 
RegisterDescriptor stackSegmentRegister () const
 Register used as a segment to access stack memory.
 
ByteOrder::Endianness defaultByteOrder () const
 Default memory byte order.
 
size_t wordSize () const
 Word size in bits.
 
size_t instructionAlignment () const
 Alignment requirement for instructions.
 
InstructionSemantics::BaseSemantics::DispatcherPtr dispatcher (const InstructionSemantics::BaseSemantics::RiscOperatorsPtr &) const
 Instruction dispatcher.
 
void showStatistics () const
 Print some partitioner performance statistics.
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor.
 
 SharedObject (const SharedObject &)
 Copy constructor.
 
virtual ~SharedObject ()
 Virtual destructor.
 
SharedObjectoperator= (const SharedObject &)
 Assignment.
 

Static Public Member Functions

static Ptr instance (const Architecture::BaseConstPtr &, const MemoryMapPtr &)
 Allocating Constructor.
 

Protected Member Functions

 InstructionProvider (const Architecture::BaseConstPtr &, const MemoryMapPtr &map)
 

Member Typedef Documentation

◆ Ptr

Shared-ownership pointer.

Definition at line 35 of file InstructionProvider.h.

◆ InsnMap

Mapping from address to instruction.

Definition at line 38 of file InstructionProvider.h.

Member Function Documentation

◆ instance()

static Ptr Rose::BinaryAnalysis::InstructionProvider::instance ( const Architecture::BaseConstPtr ,
const MemoryMapPtr  
)
static

Allocating Constructor.

Caches instructions for the specified architecture. If a memory map is provided then it will also decode instructions and add them to the cache if a query is made for an instruction that doesn't exist.

If a memory map is provided, the 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.

◆ isDisassemblerEnabled()

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

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).

◆ operator[]()

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.

◆ insert()

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()

Disassembler::BasePtr Rose::BinaryAnalysis::InstructionProvider::disassembler ( ) const

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.

◆ nCached()

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 110 of file InstructionProvider.h.

References Sawyer::Container::HashMap< K, T, H, C, A >::size().

◆ stackFrameRegister()

RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::stackFrameRegister ( ) const

Register used for function call frames.

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

◆ callReturnRegister()

RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::callReturnRegister ( ) const

Register holding a function call's return address.

Not all architectures have such a register, in which case a default-constructed register descriptor is returned. Some architectures call this a "link" register (e.g., PowerPC).

◆ stackSegmentRegister()

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

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.

◆ dispatcher()

InstructionSemantics::BaseSemantics::DispatcherPtr Rose::BinaryAnalysis::InstructionProvider::dispatcher ( const InstructionSemantics::BaseSemantics::RiscOperatorsPtr ) const

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 documentation for this class was generated from the following file: