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>
Public Types | |
| typedef Sawyer::SharedPointer< InstructionProvider > | Ptr |
| Shared-ownership pointer. More... | |
| typedef Sawyer::Container::HashMap< rose_addr_t, SgAsmInstruction * > | InsnMap |
| Mapping from address to instruction. More... | |
Public Member Functions | |
| SgAsmInstruction * | operator[] (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... | |
| Disassembler::BasePtr | disassembler () const |
| Returns the disassembler. More... | |
| size_t | nCached () const |
| Returns number of cached starting addresses. More... | |
| RegisterDictionaryPtr | registerDictionary () const |
| Returns the register dictionary. More... | |
| const CallingConvention::Dictionary & | callingConventions () 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 | stackFrameRegister () const |
| Register used for function call frames. More... | |
| RegisterDescriptor | callReturnRegister () const |
| Register holding a function call's return address. More... | |
| RegisterDescriptor | stackSegmentRegister () const |
| Register used as a segment to access stack memory. More... | |
| ByteOrder::Endianness | defaultByteOrder () const |
| Default memory byte order. More... | |
| size_t | wordSize () const |
| Word size in bits. More... | |
| size_t | instructionAlignment () const |
| Alignment requirement for instructions. More... | |
| InstructionSemantics::BaseSemantics::DispatcherPtr | dispatcher () const |
| Instruction dispatcher. More... | |
| void | showStatistics () const |
| Print some partitioner performance statistics. 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... | |
| SharedObject & | operator= (const SharedObject &) |
| Assignment. More... | |
Static Public Member Functions | |
| static Ptr | instance (const Disassembler::BasePtr &disassembler, const MemoryMap::Ptr &map) |
| Static allocating Constructor. More... | |
Protected Member Functions | |
| InstructionProvider (const Disassembler::BasePtr &disassembler, const MemoryMap::Ptr &map) | |
Member Typedef Documentation
Shared-ownership pointer.
Definition at line 35 of file InstructionProvider.h.
| typedef Sawyer::Container::HashMap<rose_addr_t, SgAsmInstruction*> Rose::BinaryAnalysis::InstructionProvider::InsnMap |
Mapping from address to instruction.
Definition at line 38 of file InstructionProvider.h.
Member Function Documentation
|
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 115 of file InstructionProvider.h.
|
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 125 of file InstructionProvider.h.
| void Rose::BinaryAnalysis::InstructionProvider::enableDisassembler | ( | bool | enable = true | ) |
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).
|
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 129 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::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.
|
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 160 of file InstructionProvider.h.
References Sawyer::Container::HashMap< K, T, H, C, A >::size().
| RegisterDictionaryPtr Rose::BinaryAnalysis::InstructionProvider::registerDictionary | ( | ) | const |
Returns the register dictionary.
| const CallingConvention::Dictionary& Rose::BinaryAnalysis::InstructionProvider::callingConventions | ( | ) | const |
Returns the calling convention dictionary.
| RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::instructionPointerRegister | ( | ) | const |
Register used as the instruction pointer.
| RegisterDescriptor Rose::BinaryAnalysis::InstructionProvider::stackPointerRegister | ( | ) | const |
Register used as a user-mode stack pointer.
| 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.
| 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).
| 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.
| ByteOrder::Endianness Rose::BinaryAnalysis::InstructionProvider::defaultByteOrder | ( | ) | const |
Default memory byte order.
| size_t Rose::BinaryAnalysis::InstructionProvider::wordSize | ( | ) | const |
Word size in bits.
| size_t Rose::BinaryAnalysis::InstructionProvider::instructionAlignment | ( | ) | const |
Alignment requirement for instructions.
| InstructionSemantics::BaseSemantics::DispatcherPtr Rose::BinaryAnalysis::InstructionProvider::dispatcher | ( | ) | 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 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.
| void Rose::BinaryAnalysis::InstructionProvider::showStatistics | ( | ) | const |
Print some partitioner performance statistics.
The documentation for this class was generated from the following file:
