Description
Virtual base class for instruction disassemblers.
The Disassembler::Base class is a virtual class providing all non-architecture-specific functionality for disassembling instructions; architecture-specific components are in subclasses Aarch64, Powerpc, X86, and others. In general, there is no need to explicitly instantiate or call functions in any of these subclasses. A Disassembler::Base is responsible for disassembling a single instruction at a time at some specified address, whereas the classes in Rose::BinaryAnalysis::Partitioner2 are responsible for deciding what addresses should be disassembled.
The main interface to a Disassembler::Base is the disassembleOne method. It tries to disassemble one instruction at the specified address from a supplied MemoryMap. A MemoryMap object represents the data in a virtual address space. On success, it returns an instance of a subclass of SgAsmInstruction, which serves as the root of an abstract syntax tree (AST) that containins information about the instruction. The instruction operands are represented by the subclasses of SgAsmExpression. If an error occurs during the disassembly of a single instruction, the disassembler will throw an exception.
New architectures can be added to ROSE without modifying any ROSE source code. One does this by subclassing an existing disassembler, overriding any necessary virtual methods, and registering an instance of the subclass with registerFactory. If the new subclass can handle multiple architectures then a disassembler should be registered for each of those architectures. When ROSE needs to disassemble something, it calls lookup, which in turn calls the canDisassemble method for all registered disassemblers. The first disassembler whose canDisassemble returns true is used for the disassembly.
Definition at line 54 of file Disassembler/Base.h.
#include <Rose/BinaryAnalysis/Disassembler/Base.h>
Public Types | |
| using | Ptr = BasePtr |
Public Member Functions | |
| virtual bool | canDisassemble (SgAsmGenericHeader *) const =0 |
| Predicate determining the suitability of a disassembler for a specific file header. More... | |
| virtual Ptr | clone () const =0 |
| Creates a new copy of a disassembler. More... | |
| virtual Unparser::BasePtr | unparser () const =0 |
| Unparser. More... | |
| size_t | instructionAlignment () const |
| Property: Instruction alignment requirement. More... | |
| virtual RegisterDescriptor | instructionPointerRegister () const |
| Returns the register that points to instructions. More... | |
| virtual RegisterDescriptor | stackPointerRegister () const |
| Returns the register that points to the stack. More... | |
| virtual RegisterDescriptor | stackFrameRegister () const |
| Returns the register that ponts to the stack frame. More... | |
| virtual RegisterDescriptor | stackSegmentRegister () const |
| Returns the segment register for accessing the stack. More... | |
| virtual RegisterDescriptor | callReturnRegister () const |
| Returns the register that holds the return address for a function. More... | |
| const Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::DispatcherPtr & | dispatcher () const |
| Return an instruction semantics dispatcher if possible. More... | |
| virtual SgAsmInstruction * | disassembleOne (const MemoryMap::Ptr &map, rose_addr_t start_va, AddressSet *successors=NULL)=0 |
| This is the lowest level disassembly function and is implemented in the architecture-specific subclasses. More... | |
| SgAsmInstruction * | disassembleOne (const unsigned char *buf, rose_addr_t buf_va, size_t buf_size, rose_addr_t start_va, AddressSet *successors=NULL) |
| Similar in functionality to the disassembleOne method that takes a MemoryMap argument, except the content buffer is mapped 1:1 to virtual memory beginning at the specified address. More... | |
| virtual SgAsmInstruction * | makeUnknownInstruction (const Exception &)=0 |
| Makes an unknown instruction from an exception. More... | |
| void | mark_referenced_instructions (SgAsmInterpretation *, const MemoryMap::Ptr &, const InstructionMap &) |
| Marks parts of the file that correspond to instructions as having been referenced. More... | |
| AddressSet | get_block_successors (const InstructionMap &, bool &complete) |
| Calculates the successor addresses of a basic block and adds them to a successors set. More... | |
| const std::string & | name () const |
| Property: Name by which disassembler is registered. | |
| void | name (const std::string &s) |
| Property: Name by which disassembler is registered. | |
| ByteOrder::Endianness | byteOrder () const |
| Property: Byte order of instructions in memory. | |
| void | byteOrder (ByteOrder::Endianness sex) |
| Property: Byte order of instructions in memory. | |
| size_t | wordSizeBytes () const |
| Property: Basic word size in bytes. | |
| void | wordSizeBytes (size_t nbytes) |
| Property: Basic word size in bytes. | |
| void | registerDictionary (const RegisterDictionaryPtr &rdict) |
| Properties: Register dictionary. More... | |
| RegisterDictionaryPtr | registerDictionary () const |
| Properties: Register dictionary. More... | |
| const CallingConvention::Dictionary & | callingConventions () const |
| Property: Calling convention dictionary. More... | |
| CallingConvention::Dictionary & | callingConventions () |
| Properties: Register dictionary. More... | |
| void | callingConventions (const CallingConvention::Dictionary &d) |
| Properties: Register dictionary. 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 SgAsmInstruction * | find_instruction_containing (const InstructionMap &insns, rose_addr_t va) |
| Finds the highest-address instruction that contains the byte at the specified virtual address. More... | |
Protected Attributes | |
| RegisterDictionaryPtr | p_registers |
| Description of registers available for this platform. More... | |
| RegisterDescriptor | REG_IP |
| RegisterDescriptor | REG_SP |
| RegisterDescriptor | REG_SS |
| RegisterDescriptor | REG_SF |
| RegisterDescriptor | REG_LINK |
| Register descriptors initialized during construction. More... | |
| ByteOrder::Endianness | p_byteOrder = ByteOrder::ORDER_LSB |
| Byte order of instructions in memory. More... | |
| size_t | p_wordSizeBytes = 4 |
| Basic word size in bytes. More... | |
| std::string | p_name |
| Name by which this dissassembler is registered. More... | |
| size_t | instructionAlignment_ = 1 |
| Positive alignment constraint for instruction addresses. More... | |
| InstructionSemantics::BaseSemantics::DispatcherPtr | p_proto_dispatcher |
| Prototypical dispatcher for creating real dispatchers. | |
Member Function Documentation
|
pure virtual |
Predicate determining the suitability of a disassembler for a specific file header.
If this disassembler is capable of disassembling machine code described by the specified file header, then this predicate returns true, otherwise it returns false.
Thread safety: The thread safety of this virtual method depends on the implementation in the subclass.
Implemented in Rose::BinaryAnalysis::Disassembler::X86, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Powerpc, Rose::BinaryAnalysis::Disassembler::Cil, and Rose::BinaryAnalysis::Disassembler::Mips.
|
pure virtual |
Creates a new copy of a disassembler.
The new copy has all the same settings as the original.
Thread safety: The thread safety of this virtual method depends on the implementation in the subclass.
Implemented in Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::X86, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Powerpc, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Cil, and Rose::BinaryAnalysis::Disassembler::Mips.
|
pure virtual |
Returns an unparser suitable for unparsing the same instruction set architecture as recognized and produced by this disassembler.
Implemented in Rose::BinaryAnalysis::Disassembler::X86, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Cil, Rose::BinaryAnalysis::Disassembler::Powerpc, and Rose::BinaryAnalysis::Disassembler::Mips.
| size_t Rose::BinaryAnalysis::Disassembler::Base::instructionAlignment | ( | ) | const |
Property: Instruction alignment requirement.
The alignment that's required for instruction addresses. The return value is a positive number of bytes.
|
inline |
Properties: Register dictionary.
Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.
Thread safety: It is not safe to change the register dictionary while another thread is using this same Base object.
Definition at line 182 of file Disassembler/Base.h.
|
inline |
Properties: Register dictionary.
Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.
Thread safety: It is not safe to change the register dictionary while another thread is using this same Base object.
Definition at line 185 of file Disassembler/Base.h.
References p_registers.
|
inline |
Property: Calling convention dictionary.
This is a dictionary of the common calling conventions for this architecture.
Definition at line 194 of file Disassembler/Base.h.
|
inline |
Properties: Register dictionary.
Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.
Thread safety: It is not safe to change the register dictionary while another thread is using this same Base object.
Definition at line 195 of file Disassembler/Base.h.
|
inline |
Properties: Register dictionary.
Specifies the registers available on this architecture. Rather than using hard-coded class, number, and position constants, the disassembler should perform a name lookup in this supplied register dictionary and use the values found therein. There's usually no need for the user to specify a value because either it will be obtained from an SgAsmInterpretation or the subclass will initialize it.
Thread safety: It is not safe to change the register dictionary while another thread is using this same Base object.
Definition at line 196 of file Disassembler/Base.h.
|
inlinevirtual |
Returns the register that points to instructions.
Definition at line 200 of file Disassembler/Base.h.
References Rose::BinaryAnalysis::RegisterDescriptor::isEmpty().
|
inlinevirtual |
Returns the register that points to the stack.
Definition at line 206 of file Disassembler/Base.h.
References Rose::BinaryAnalysis::RegisterDescriptor::isEmpty().
|
inlinevirtual |
Returns the register that ponts to the stack frame.
Definition at line 212 of file Disassembler/Base.h.
|
inlinevirtual |
Returns the segment register for accessing the stack.
Not all architectures have this register, in which case the default-constructed register descriptor is returned.
Definition at line 218 of file Disassembler/Base.h.
|
inlinevirtual |
Returns the register that holds the return address for a function.
If the architecture doesn't have such a register then a default constructed descriptor is returned.
Definition at line 225 of file Disassembler/Base.h.
References REG_LINK.
|
inline |
Return an instruction semantics dispatcher if possible.
If instruction semantics are implemented for this architecure then return a pointer to a dispatcher. The dispatcher will have no attached RISC operators and can only be used to create a new dispatcher via its virtual constructor. If instruction semantics are not implemented then the null pointer is returned.
Definition at line 234 of file Disassembler/Base.h.
References p_proto_dispatcher.
|
pure virtual |
This is the lowest level disassembly function and is implemented in the architecture-specific subclasses.
It disassembles one instruction at the specified virtual address. The map is a mapping from virtual addresses to buffer and enables instructions to span file segments that are mapped contiguously in virtual memory by the loader but which might not be contiguous in the file. The instruction's successor virtual addresses are added to the optional successor set (note that successors of an individual instruction can also be obtained via SgAsmInstruction::getSuccessors). If the instruction cannot be disassembled then an exception is thrown and the successors set is not modified.
Thread safety: The safety of this method depends on its implementation in the subclass. In any case, no other thread can be modifying the MemoryMap or successors set at the same time.
Implemented in Rose::BinaryAnalysis::Disassembler::X86, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Cil, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Powerpc, and Rose::BinaryAnalysis::Disassembler::Mips.
| SgAsmInstruction* Rose::BinaryAnalysis::Disassembler::Base::disassembleOne | ( | const unsigned char * | buf, |
| rose_addr_t | buf_va, | ||
| size_t | buf_size, | ||
| rose_addr_t | start_va, | ||
| AddressSet * | successors = NULL |
||
| ) |
Similar in functionality to the disassembleOne method that takes a MemoryMap argument, except the content buffer is mapped 1:1 to virtual memory beginning at the specified address.
Thread safety: The safety of this method depends on the implementation of the disassembleOne() defined in the subclass. If the subclass is thread safe then this method can be called in multiple threads as long as the supplied buffer and successors set are not being modified by another thread.
|
pure virtual |
Makes an unknown instruction from an exception.
Thread safety: The safety of this method depends on its implementation in the subclass.
Implemented in Rose::BinaryAnalysis::Disassembler::X86, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Cil, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Powerpc, and Rose::BinaryAnalysis::Disassembler::Mips.
| void Rose::BinaryAnalysis::Disassembler::Base::mark_referenced_instructions | ( | SgAsmInterpretation * | , |
| const MemoryMap::Ptr & | , | ||
| const InstructionMap & | |||
| ) |
Marks parts of the file that correspond to instructions as having been referenced.
Thread safety: This method is not thread safe.
| AddressSet Rose::BinaryAnalysis::Disassembler::Base::get_block_successors | ( | const InstructionMap & | , |
| bool & | complete | ||
| ) |
Calculates the successor addresses of a basic block and adds them to a successors set.
The successors is always non-null when called. If the function is able to determine the complete set of successors then it should set complete to true before returning.
Thread safety: Thread safe provided no other thread is modifying the specified instruction map.
|
static |
Finds the highest-address instruction that contains the byte at the specified virtual address.
Returns null if no such instruction exists.
Thread safety: This class method is thread safe provided no other thread is modifying the instruction map nor the instructions to which the map points, particularly the instructions' virtual address and raw bytes.
Member Data Documentation
|
protected |
Description of registers available for this platform.
Definition at line 68 of file Disassembler/Base.h.
Referenced by registerDictionary().
|
protected |
Register descriptors initialized during construction.
Definition at line 69 of file Disassembler/Base.h.
Referenced by callReturnRegister().
|
protected |
Byte order of instructions in memory.
Definition at line 70 of file Disassembler/Base.h.
Referenced by byteOrder().
|
protected |
Basic word size in bytes.
Definition at line 71 of file Disassembler/Base.h.
Referenced by wordSizeBytes().
|
protected |
Name by which this dissassembler is registered.
Definition at line 72 of file Disassembler/Base.h.
Referenced by name().
|
protected |
Positive alignment constraint for instruction addresses.
Definition at line 73 of file Disassembler/Base.h.
The documentation for this class was generated from the following file:
