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 | |
| Architecture::BaseConstPtr | architecture () const |
| Property: Architecture. | |
| bool | isDisassemblerEnabled () const |
| Enable or disable the disassembler. | |
| 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. | |
| SgAsmInstruction * | operator[] (Address) const |
| Returns the instruction at the specified virtual address, or null. | |
| SgAsmInstruction * | at (Address) const |
| Returns the instruction at the specified virtual address, or null. | |
 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 not provided then querying an address for which no instruction has been inserted will return a null pointer.
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.
◆ architecture()
| Architecture::BaseConstPtr Rose::BinaryAnalysis::InstructionProvider::architecture | ( | ) | const |
Property: Architecture.
The architecture specified during construction.
◆ 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). The disassembler is enabled if a memory map was provided to the constructor.
◆ operator[]()
| SgAsmInstruction * Rose::BinaryAnalysis::InstructionProvider::operator[] | ( | Address | ) | const |
Returns the instruction at the specified virtual address, or null.
If an instruction has been inserted for the specified address, then that instruction is returned.
Otherwise, if no memory map was provided to the constructor, then a null instruction pointer is returned and the cache is not modified.
Otherwise, if the virtual address does not exist or is not 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.
◆ at()
| SgAsmInstruction * Rose::BinaryAnalysis::InstructionProvider::at | ( | Address | ) | const |
Returns the instruction at the specified virtual address, or null.
If an instruction has been inserted for the specified address, then that instruction is returned.
Otherwise, if no memory map was provided to the constructor, then a null instruction pointer is returned and the cache is not modified.
Otherwise, if the virtual address does not exist or is not 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.
◆ 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 125 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:
