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. | |
| typedef Sawyer::Container::HashMap< Address, SgAsmInstruction * > | InsnMap |
| Mapping from address to instruction. | |
Public Member Functions | |
| bool | isDisassemblerEnabled () const |
| Enable or disable the disassembler. | |
| SgAsmInstruction * | operator[] (Address 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::Dictionary & | callingConventions () 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. | |
| SharedObject & | operator= (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
| typedef Sawyer::Container::HashMap<Address, SgAsmInstruction*> Rose::BinaryAnalysis::InstructionProvider::InsnMap |
Mapping from address to instruction.
Definition at line 38 of file InstructionProvider.h.
Member Function Documentation
◆ instance()
|
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[] | ( | Address | 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()
|
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:
