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 through the Rose::BinaryAnalysis::Architecture API.
Definition at line 50 of file Disassembler/Base.h.
#include <Rose/BinaryAnalysis/Disassembler/Base.h>
Public Types | |
| using | Ptr = BasePtr |
Public Member Functions | |
| virtual Ptr | clone () const =0 |
| Creates a new copy of a disassembler. | |
| Architecture::BaseConstPtr | architecture () const |
| Property: Architecture. | |
| virtual const std::string & | name () const |
| Property: Name. | |
| virtual size_t | bytesPerWord () const |
| Property: Bytes per word for the architecture. | |
| virtual ByteOrder::Endianness | byteOrder () const |
| Property: Byte order of memory. | |
| Unparser::BasePtr | unparser () const |
| Unparser. | |
| size_t | instructionAlignment () const |
| Property: Instruction alignment requirement. | |
| virtual SgAsmInstruction * | disassembleOne (const MemoryMap::Ptr &map, Address start_va, AddressSet *successors=NULL)=0 |
| This is the lowest level disassembly function and is implemented in the architecture-specific subclasses. | |
| SgAsmInstruction * | disassembleOne (const unsigned char *buf, Address buf_va, size_t buf_size, Address 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. | |
| virtual SgAsmInstruction * | makeUnknownInstruction (const Exception &)=0 |
| Makes an unknown instruction from an exception. | |
| void | mark_referenced_instructions (SgAsmInterpretation *, const MemoryMap::Ptr &, const InstructionMap &) |
| Marks parts of the file that correspond to instructions as having been referenced. | |
| AddressSet | get_block_successors (const InstructionMap &, bool &complete) |
| Calculates the successor addresses of a basic block and adds them to a successors set. | |
| size_t | wordSizeBytes () const |
| RegisterDictionaryPtr | registerDictionary () const |
| virtual RegisterDescriptor | instructionPointerRegister () const |
| virtual RegisterDescriptor | stackPointerRegister () const |
| virtual RegisterDescriptor | stackFrameRegister () const |
| virtual RegisterDescriptor | stackSegmentRegister () const |
| virtual RegisterDescriptor | callReturnRegister () const |
 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 SgAsmInstruction * | find_instruction_containing (const InstructionMap &insns, Address va) |
| Finds the highest-address instruction that contains the byte at the specified virtual address. | |
Protected Member Functions | |
| Base (const Architecture::BaseConstPtr &) | |
Protected Attributes | |
| RegisterDescriptor | REG_IP |
| RegisterDescriptor | REG_SP |
| RegisterDescriptor | REG_SS |
| RegisterDescriptor | REG_SF |
| RegisterDescriptor | REG_LINK |
| Register descriptors initialized during construction. | |
| size_t | instructionAlignment_ = 1 |
| Positive alignment constraint for instruction addresses. | |
Member Typedef Documentation
◆ Ptr
Definition at line 55 of file Disassembler/Base.h.
Member Function Documentation
◆ clone()
|
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::Powerpc, Rose::BinaryAnalysis::Disassembler::Cil, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Mips, Rose::BinaryAnalysis::Disassembler::Null, and Rose::BinaryAnalysis::Disassembler::X86.
◆ architecture()
| Architecture::BaseConstPtr Rose::BinaryAnalysis::Disassembler::Base::architecture | ( | ) | const |
Property: Architecture.
The architecture is always non-null.
◆ name()
|
virtual |
Property: Name.
The disassembler name is normally the same as the architecture name.
◆ unparser()
| Unparser::BasePtr Rose::BinaryAnalysis::Disassembler::Base::unparser | ( | ) | const |
Returns an unparser suitable for unparsing the same instruction set architecture as recognized and produced by this disassembler.
◆ instructionAlignment()
| 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.
◆ disassembleOne() [1/2]
|
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 Architecture::Base::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::Mips, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Null, Rose::BinaryAnalysis::Disassembler::Cil, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Powerpc, and Rose::BinaryAnalysis::Disassembler::X86.
◆ disassembleOne() [2/2]
| SgAsmInstruction * Rose::BinaryAnalysis::Disassembler::Base::disassembleOne | ( | const unsigned char * | buf, |
| Address | buf_va, | ||
| size_t | buf_size, | ||
| Address | 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.
◆ makeUnknownInstruction()
|
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::Cil, Rose::BinaryAnalysis::Disassembler::Jvm, Rose::BinaryAnalysis::Disassembler::Powerpc, Rose::BinaryAnalysis::Disassembler::M68k, Rose::BinaryAnalysis::Disassembler::Mips, Rose::BinaryAnalysis::Disassembler::Null, and Rose::BinaryAnalysis::Disassembler::X86.
◆ mark_referenced_instructions()
| 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.
◆ get_block_successors()
| 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.
◆ find_instruction_containing()
|
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
◆ REG_IP
|
protected |
Definition at line 64 of file Disassembler/Base.h.
◆ REG_SP
|
protected |
Definition at line 64 of file Disassembler/Base.h.
◆ REG_SS
|
protected |
Definition at line 64 of file Disassembler/Base.h.
◆ REG_SF
|
protected |
Definition at line 64 of file Disassembler/Base.h.
◆ REG_LINK
|
protected |
Register descriptors initialized during construction.
Definition at line 64 of file Disassembler/Base.h.
◆ instructionAlignment_
|
protected |
Positive alignment constraint for instruction addresses.
Definition at line 65 of file Disassembler/Base.h.
The documentation for this class was generated from the following file:
