Description

Virtual base class for instruction assemblers.

The Assembler class is a virtual class providing all non-architecture-specific functionality for the assembly of instructions; architecture-specific components are in subclasses such as AssemblerAarch64, AssemblerPowerpc, and AssemblerX86.

This example shows how to test the disassembler against the assembler by disassembling and then reassembling all instructions. Generate debugging output for instructions that cannot be reassembled into an encoding identical to the original bytes:

// Disassemble the interpretation (normally happens automatically)
SgAsmInterpretation *interp = ....;
Disassembler::BasePtr d = Disassembler::lookup(interp);
d->disassemble(interp);
// Create an assembler that can handle instructions in this interpretation.
Assembler *asm = Assembler::create(interp);
// Cause the assembler to choose encodings that are identical to the
// bytes originally disassebled.  The assembler still goes through all the
// work of assembling, but then checks the result against the original
// bytes.
asm->set_encoding_type(Assembler::ET_MATCHES);
// Attempt to reassemble each instruction. If the assembly fails to produce
// the original bytes then an exception is thrown and we try again for
// debugging side effects.
std::vector<SgNode*> insns = NodeQuery::querySubTree(interp, V_SgAsmInstruction);
for (size_t i=0; i<insns.size(); i++) {
    SgAsmInstruction *insn = isSgAsmInstruction(insns[i]);
    try {
        asm->assembleOne(insn);
    } catch(const Assembler::Exception &e) {
        fprintf(stderr, "assembly failed at 0x%08llx: %s\n",
                insn->get_address(), e.mesg.c_str());
        asm->set_debug(stderr);
        try {
            asm->assembleOne(insn);
        } catch(const Assembler::Exception&) {
        }
        asm->set_debug(NULL);
    }
}

Definition at line 58 of file Assembler.h.

#include <frontend/Disassemblers/Assembler.h>

Inheritance diagram for Rose::BinaryAnalysis::Assembler:

[legend]

Classes
class	Exception
	Exception thrown by the assemblers. More...

Public Types
enum	EncodingType { ET_SHORTEST, ET_LONGEST, ET_MATCHES }
	Assemblers can often assemble a single instruction various ways. More...

Public Member Functions
virtual SgUnsignedCharList	assembleOne (SgAsmInstruction *insn)=0
	This is the lowest level architecture-independent assembly function and is implemented in the architecture-specific subclasses (there may be other architecture-dependent assembly methods also). More...

SgUnsignedCharList	assembleBlock (SgAsmBlock *)
	Assembles a single basic block of instructions, packing them together and adjusting their virtual addresses. More...

SgUnsignedCharList	assembleBlock (const std::vector< SgAsmInstruction * > &insns, rose_addr_t starting_rva)
	Assembles a single basic block of instructions like the version that takes an SgAsmBlock pointer. More...

virtual SgUnsignedCharList	assembleProgram (const std::string &source)=0
	Assembles a program from an assembly listing. More...

void	set_encoding_type (EncodingType et)
	Controls how the assembleOne() method determines which encoding to return. More...

EncodingType	get_encoding_type () const
	Returns the encoding type employed by this assembler. More...

void	set_debug (FILE *f)
	Sends assembler diagnostics to the specified output stream. More...

FILE *	get_debug () const
	Returns the file currently used for debugging; null implies no debugging. More...

Static Public Member Functions
static Assembler *	create (SgAsmInterpretation *interp)
	Creates an assembler that is appropriate for assembling instructions in the specified interpretation. More...

static Assembler *	create (SgAsmGenericHeader *)
	Creates an assembler that is appropriate for assembling instructions in the specified header. More...

Protected Attributes
FILE *	p_debug
	Set to non-null to get debugging info. More...

EncodingType	p_encoding_type
	Which encoding should be returned by assembleOne. More...

Member Enumeration Documentation

enum Rose::BinaryAnalysis::Assembler::EncodingType

Assemblers can often assemble a single instruction various ways.

For instance, on x86 the immediate value -53 can be assembled into a single byte, or sign extended into 2, 4, or 8 bytes. These enumeration constants control how the assembleOne() method determines which encoding to return.

Enumerator

ET_SHORTEST

Returns the shortest possible encoding.

This is the default.

ET_LONGEST

Returns the longest encoding.

ET_MATCHES

Returns an encoding that matches the SgAsmInstruction::p_raw_bytes.

This is used mainly for testing that the assembler can produce the same encoding that was originally used by the disassembler when the instruction was created.

Definition at line 80 of file Assembler.h.

Member Function Documentation

static Assembler* Rose::BinaryAnalysis::Assembler::create ( SgAsmInterpretation * interp )

static

Creates an assembler that is appropriate for assembling instructions in the specified interpretation.

static Assembler* Rose::BinaryAnalysis::Assembler::create ( SgAsmGenericHeader * )

static

Creates an assembler that is appropriate for assembling instructions in the specified header.

virtual SgUnsignedCharList Rose::BinaryAnalysis::Assembler::assembleOne ( SgAsmInstruction * insn )

pure virtual

This is the lowest level architecture-independent assembly function and is implemented in the architecture-specific subclasses (there may be other architecture-dependent assembly methods also).

It assembles one instruction and returns the encoding, throwing an exception if anything goes wrong.

Implemented in Rose::BinaryAnalysis::AssemblerX86.

SgUnsignedCharList Rose::BinaryAnalysis::Assembler::assembleBlock ( SgAsmBlock * )

Assembles a single basic block of instructions, packing them together and adjusting their virtual addresses.

The virtual address of the first instruction of the block determines the starting address. An exception is thrown if any of the instructions cannot be assembled.

SgUnsignedCharList Rose::BinaryAnalysis::Assembler::assembleBlock	(	const std::vector< SgAsmInstruction * > &	insns,
		rose_addr_t	starting_rva
	)

Assembles a single basic block of instructions like the version that takes an SgAsmBlock pointer.

In this case, the instructions are stored in a vector instead. The will be treated like a single basic block: no control flow adjustments will be made. An exception is thrown if any of the instructions cannot be disassembled.

virtual SgUnsignedCharList Rose::BinaryAnalysis::Assembler::assembleProgram ( const std::string & source )

pure virtual

Assembles a program from an assembly listing.

This method may call an external assembler to do its work.

Implemented in Rose::BinaryAnalysis::AssemblerX86.

void Rose::BinaryAnalysis::Assembler::set_encoding_type ( EncodingType et )

inline

Controls how the assembleOne() method determines which encoding to return.

Definition at line 128 of file Assembler.h.

References p_encoding_type.

EncodingType Rose::BinaryAnalysis::Assembler::get_encoding_type ( ) const

inline