ROSE  0.11.145.0
Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | List of all members
Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher Class Referenceabstract

Description

Dispatches instructions through the RISC layer.

The dispatcher is the instruction semantics entity that translates a high-level architecture-dependent instruction into a sequence of RISC operators whose interface is defined by ROSE. These classes are the key in ROSE's ability to connect a variety of instruction set architectures to a variety of semantic domains.

Each dispatcher contains a table indexed by the machine instruction "kind" (e.g., SgAsmMipsInstruction::get_kind()). The table stores functors derived from the abstract InsnProcessor class. (FIXME: The functors are not currently reference counted; they are owned by the dispatcher and deleted when the dispatcher is destroyed. [Robb Matzke 2013-03-04])

Dispatcher objects are allocated on the heap and reference counted. The BaseSemantics::Dispatcher is an abstract class that defines the interface. See the Rose::BinaryAnalysis::InstructionSemantics namespace for an overview of how the parts fit together.

Definition at line 43 of file Dispatcher.h.

#include <Rose/BinaryAnalysis/InstructionSemantics/BaseSemantics/Dispatcher.h>

Inheritance diagram for Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher:
Inheritance graph
[legend]
Collaboration diagram for Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher:
Collaboration graph
[legend]

Public Types

using Ptr = DispatcherPtr
 Shared-ownership pointer. More...
 

Public Member Functions

virtual DispatcherPtr create (const RiscOperatorsPtr &ops, size_t addrWidth, const RegisterDictionaryPtr &) const =0
 Virtual constructor. More...
 
virtual void processInstruction (SgAsmInstruction *insn)
 Process a single instruction. More...
 
virtual InsnProcessoriprocLookup (SgAsmInstruction *insn)
 Lookup the processor for an instruction. More...
 
virtual void iprocReplace (SgAsmInstruction *insn, InsnProcessor *iproc)
 Replace an instruction processor with another. More...
 
virtual int iprocKey (SgAsmInstruction *) const =0
 Given an instruction, return the InsnProcessor key that can be used as an index into the iproc_table. More...
 
virtual void iprocSet (int key, InsnProcessor *iproc)
 Set an iproc table entry to the specified value. More...
 
virtual InsnProcessoriprocGet (int key)
 Obtain an iproc table entry for the specified key. More...
 
virtual RiscOperatorsPtr get_operators () const ROSE_DEPRECATED("use \"operators\" instead")
 
virtual StatePtr currentState () const
 Get a pointer to the state object. More...
 
virtual SValuePtr protoval () const
 Return the prototypical value. More...
 
virtual SgAsmInstructioncurrentInstruction () const
 Returns the instruction that is being processed. More...
 
virtual SValuePtr number_ (size_t nbits, uint64_t number) const
 Return a semantic value representing a number. More...
 
virtual RegisterDictionaryPtr get_register_dictionary () const
 
virtual void set_register_dictionary (const RegisterDictionaryPtr &regdict)
 
virtual RegisterDescriptor findRegister (const std::string &regname, size_t nbits=0, bool allowMissing=false) const
 Lookup a register by name. More...
 
virtual RegisterDescriptor instructionPointerRegister () const =0
 Returns the instruction pointer register. More...
 
virtual RegisterDescriptor stackPointerRegister () const =0
 Returns the stack pointer register. More...
 
virtual RegisterDescriptor stackFrameRegister () const =0
 Returns the stack call frame register. More...
 
virtual RegisterDescriptor callReturnRegister () const =0
 Returns the function call return address register. More...
 
virtual void initializeState (const StatePtr &)
 Initialize the state. More...
 
virtual void advanceInstructionPointer (SgAsmInstruction *)
 Update the instruction pointer register. More...
 
virtual RegisterDescriptor segmentRegister (SgAsmMemoryReferenceExpression *)
 Returns a register descriptor for the segment part of a memory reference expression. More...
 
virtual void incrementRegisters (SgAsmExpression *)
 Increment all auto-increment registers in the expression. More...
 
virtual void decrementRegisters (SgAsmExpression *)
 Decrement all auto-decrement registers in the expression. More...
 
virtual void preUpdate (SgAsmExpression *, const BaseSemantics::SValuePtr &enabled)
 Update registers for pre-add expressions. More...
 
virtual void postUpdate (SgAsmExpression *, const BaseSemantics::SValuePtr &enabled)
 Update registers for post-add expressions. More...
 
virtual SValuePtr effectiveAddress (SgAsmExpression *, size_t nbits=0)
 Returns a memory address by evaluating the address expression. More...
 
virtual SValuePtr read (SgAsmExpression *, size_t value_nbits=0, size_t addr_nbits=0)
 Reads an R-value expression. More...
 
virtual void write (SgAsmExpression *, const SValuePtr &value, size_t addr_nbits=0)
 Writes to an L-value expression. More...
 
virtual RiscOperatorsPtr operators () const
 Property: RISC operators. More...
 
virtual void operators (const RiscOperatorsPtr &ops)
 Property: RISC operators. More...
 
virtual SValuePtr undefined_ (size_t nbits) const
 Return a new undefined semantic value.
 
virtual SValuePtr unspecified_ (size_t nbits) const
 Return a new undefined semantic value.
 
RegisterDictionaryPtr registerDictionary () const
 Property: Register dictionary. More...
 
void registerDictionary (const RegisterDictionaryPtr &rd)
 Property: Register dictionary. More...
 
size_t addressWidth () const
 Property: Width of memory addresses. More...
 
void addressWidth (size_t nbits)
 Property: Width of memory addresses. More...
 
bool autoResetInstructionPointer () const
 Property: Reset instruction pointer register for each instruction. More...
 
void autoResetInstructionPointer (bool b)
 Property: Reset instruction pointer register for each instruction. More...
 

Protected Types

typedef std::vector< InsnProcessor * > InsnProcessors
 

Protected Member Functions

 Dispatcher (size_t addrWidth, const RegisterDictionaryPtr &)
 
 Dispatcher (const RiscOperatorsPtr &, size_t addrWidth, const RegisterDictionaryPtr &)
 

Protected Attributes

RegisterDictionaryPtr regdict
 See registerDictionary property. More...
 
size_t addrWidth_
 Width of memory addresses in bits. More...
 
bool autoResetInstructionPointer_
 Reset instruction pointer register for each instruction. More...
 
InsnProcessors iproc_table
 

Member Typedef Documentation

Shared-ownership pointer.

Definition at line 46 of file Dispatcher.h.

Member Function Documentation

virtual DispatcherPtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::create ( const RiscOperatorsPtr ops,
size_t  addrWidth,
const RegisterDictionaryPtr  
) const
pure virtual
virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::processInstruction ( SgAsmInstruction insn)
virtual

Process a single instruction.

virtual InsnProcessor* Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::iprocLookup ( SgAsmInstruction insn)
virtual

Lookup the processor for an instruction.

Looks up the functor that has been registered to process the given instruction. Returns the null pointer if the instruction cannot be processed. Instruction processor objects are managed by the caller; the instruction itself is only used for the duration of this call.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::iprocReplace ( SgAsmInstruction insn,
InsnProcessor iproc 
)
virtual

Replace an instruction processor with another.

The processor for the specified instruction is replaced with the specified processor, which may be the null pointer. Instruction processor objects are managed by the caller; the instruction itself is only used for the duration of this call.

virtual int Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::iprocKey ( SgAsmInstruction ) const
pure virtual
virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::iprocSet ( int  key,
InsnProcessor iproc 
)
virtual

Set an iproc table entry to the specified value.

The iproc object will become owned by this dispatcher and deleted when this dispatcher is destroyed.

virtual InsnProcessor* Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::iprocGet ( int  key)
virtual

Obtain an iproc table entry for the specified key.

virtual RiscOperatorsPtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::operators ( ) const
inlinevirtual

Property: RISC operators.

The RISC operators also contain the current and initial state on which they operate.

Definition at line 140 of file Dispatcher.h.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::operators ( const RiscOperatorsPtr ops)
virtual

Property: RISC operators.

The RISC operators also contain the current and initial state on which they operate.

virtual StatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::currentState ( ) const
virtual

Get a pointer to the state object.

The state is stored in the RISC operators object, so this is just here for convenience.

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::protoval ( ) const
virtual

Return the prototypical value.

The prototypical value comes from the RISC operators object.

virtual SgAsmInstruction* Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::currentInstruction ( ) const
virtual

Returns the instruction that is being processed.

The instruction comes from the currentInstruction method of the RiscOperators object.

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::number_ ( size_t  nbits,
uint64_t  number 
) const
virtual

Return a semantic value representing a number.

RegisterDictionaryPtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::registerDictionary ( ) const

Property: Register dictionary.

The register dictionary defines the set of registers over which the RISC operators may operate. This should be same registers (or superset thereof) whose values are stored in the machine state(s). This dictionary is used by the Dispatcher class to translate register names to register descriptors. For instance, to read from the "eax" register, the dispatcher will look up "eax" in its register dictionary and then pass that descriptor to the RiscOperators::readRegister operation. Register descriptors are also stored in instructions when the instruction is disassembled, so the dispatcher should probably be using the same registers as the disassembler, or a superset thereof.

The register dictionary should not be changed after a dispatcher is instantiated because the dispatcher's constructor may query the dictionary and cache the resultant register descriptors.

This function should not be redefined in subclasses. Instead, override get_register_dictionary or set_register_dictionary.

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::registerDictionary ( const RegisterDictionaryPtr rd)

Property: Register dictionary.

The register dictionary defines the set of registers over which the RISC operators may operate. This should be same registers (or superset thereof) whose values are stored in the machine state(s). This dictionary is used by the Dispatcher class to translate register names to register descriptors. For instance, to read from the "eax" register, the dispatcher will look up "eax" in its register dictionary and then pass that descriptor to the RiscOperators::readRegister operation. Register descriptors are also stored in instructions when the instruction is disassembled, so the dispatcher should probably be using the same registers as the disassembler, or a superset thereof.

The register dictionary should not be changed after a dispatcher is instantiated because the dispatcher's constructor may query the dictionary and cache the resultant register descriptors.

This function should not be redefined in subclasses. Instead, override get_register_dictionary or set_register_dictionary.

virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::findRegister ( const std::string &  regname,
size_t  nbits = 0,
bool  allowMissing = false 
) const
virtual

Lookup a register by name.

This dispatcher's register dictionary is consulted and the specified register is located by name. If a bit width is specified (nbits) then it must match the size of register that was found. If a valid register cannot be found then either an exception is thrown or an invalid register is returned depending on whether allowMissing is false or true, respectively.

size_t Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::addressWidth ( ) const
inline

Property: Width of memory addresses.

This property defines the width of memory addresses. All memory reads and writes (and any other defined memory operations) should pass address expressions that are this width. The address width cannot be changed once it's set.

Definition at line 207 of file Dispatcher.h.

References addrWidth_.

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::addressWidth ( size_t  nbits)

Property: Width of memory addresses.

This property defines the width of memory addresses. All memory reads and writes (and any other defined memory operations) should pass address expressions that are this width. The address width cannot be changed once it's set.

virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::instructionPointerRegister ( ) const
pure virtual
virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::stackPointerRegister ( ) const
pure virtual
virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::stackFrameRegister ( ) const
pure virtual
virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::callReturnRegister ( ) const
pure virtual
bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::autoResetInstructionPointer ( ) const
inline

Property: Reset instruction pointer register for each instruction.

If this property is set, then each time an instruction is processed, the first thing that happens is that the instruction pointer register is reset to the concrete address of the instruction.

Definition at line 229 of file Dispatcher.h.

References autoResetInstructionPointer_.

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::autoResetInstructionPointer ( bool  b)
inline

Property: Reset instruction pointer register for each instruction.

If this property is set, then each time an instruction is processed, the first thing that happens is that the instruction pointer register is reset to the concrete address of the instruction.

Definition at line 230 of file Dispatcher.h.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::initializeState ( const StatePtr )
virtual

Initialize the state.

Some architectures benefit from having their initial state initialized in a certain way. For instance, on x86/amd64 the segment registers CS, DS, and SS typically refer to the entire machine memory and can be initialized to have a zero base address.

Reimplemented in Rose::BinaryAnalysis::InstructionSemantics::DispatcherX86.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::advanceInstructionPointer ( SgAsmInstruction )
virtual

Update the instruction pointer register.

Causes the instruction pointer register to point to the address following the specified instruction. Since every instruction has a concrete address, we could simply set the instruction pointer to that concrete address. However, some analyses depend on having an instruction pointer value that's built up by processing one instruction after another. Therefore, if we can recognize the register state implementation and determine that the instruction pointer registers' value is already stored, we'll increment that value, which might result in a concrete value depending on the semantic domain. Otherwise we just explicitly assign a new concrete value to that register.

virtual RegisterDescriptor Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::segmentRegister ( SgAsmMemoryReferenceExpression )
virtual

Returns a register descriptor for the segment part of a memory reference expression.

Many architectures don't use segment registers (they have a flat virtual address space), in which case the returned register descriptor's is_valid() method returns false.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::incrementRegisters ( SgAsmExpression )
virtual

Increment all auto-increment registers in the expression.

This method traverses the expression and increments each the register of each register reference expression that has a positive adjustment value. If the same register is encountered multiple times then it is incremented multiple times.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::decrementRegisters ( SgAsmExpression )
virtual

Decrement all auto-decrement registers in the expression.

This method traverses the expression and increments each the register of each register reference expression that has a negative adjustment value. If the same register is encountered multiple times then it is decremented multiple times.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::preUpdate ( SgAsmExpression ,
const BaseSemantics::SValuePtr enabled 
)
virtual

Update registers for pre-add expressions.

For each SgAsmBinaryAddPreupdate, add the lhs and rhs operands and assign the sum to the lhs, which must be a register reference expression.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::postUpdate ( SgAsmExpression ,
const BaseSemantics::SValuePtr enabled 
)
virtual

Update registers for post-add expressions.

For each SgAsmBinaryAddPostupdate, add the lhs and rhs operands and assign the sum to the lhs, which must be a register reference expression.

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::effectiveAddress ( SgAsmExpression ,
size_t  nbits = 0 
)
virtual

Returns a memory address by evaluating the address expression.

The address expression can be either a constant or an expression containing operators and constants. If nbits is non-zero then the result is sign extended or truncated to the specified width, otherwise the returned SValue is the natural width of the expression.

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::read ( SgAsmExpression ,
size_t  value_nbits = 0,
size_t  addr_nbits = 0 
)
virtual

Reads an R-value expression.

The expression can be a constant, register reference, or memory reference. The width of the returned value is specified by the value_nbits argument, and if this argument is zero then the width of the expression type is used. The width of the address passed to lower-level memory access functions is specified by addr_nbits. If addr_nbits is zero then the natural width of the effective address is passed to lower level functions.

Reimplemented in Rose::BinaryAnalysis::InstructionSemantics::DispatcherCil, and Rose::BinaryAnalysis::InstructionSemantics::DispatcherM68k.

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::write ( SgAsmExpression ,
const SValuePtr value,
size_t  addr_nbits = 0 
)
virtual

Writes to an L-value expression.

The expression can be a register or memory reference. The width of the address passed to lower-level memory access functions is specified by addr_nbits. If addr_nbits is zero then the natural width of the effective address is passed to lower level functions.

Reimplemented in Rose::BinaryAnalysis::InstructionSemantics::DispatcherX86.

Member Data Documentation

RegisterDictionaryPtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::regdict
protected

See registerDictionary property.

Definition at line 52 of file Dispatcher.h.

size_t Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::addrWidth_
protected

Width of memory addresses in bits.

Definition at line 53 of file Dispatcher.h.

Referenced by addressWidth().

bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::Dispatcher::autoResetInstructionPointer_
protected

Reset instruction pointer register for each instruction.

Definition at line 54 of file Dispatcher.h.

Referenced by autoResetInstructionPointer().


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