Description

Unparses binary AST into text.

This class operates on part of an AST corresponding to a binary file (executable, library, etc) and generates output. It is intended to be highly customizable and has been used to generate both assembly listings and Graphviz files.

To generate an assembly listing, use the unparse() method, like this:

SgProject *project = ...;

AsmUnparser().unparse(std::cout, project);

Rose::BinaryAnalysis::AsmUnparser::AsmUnparser

AsmUnparser()

Constructor that intializes the "unparser" callback lists with some useful functors.

SgProject

This class represents a source project, with a list of SgFile objects and global information about th...

Definition Cxx_Grammar.h:39187

The unparser can organize the output either by address (like traditional assembly listings) or by the organization found in the AST (by interpretation, then function, then basic block). The AST organization is often more useful and is therefore the default. Some of the callbacks mentioned below apply only to one organizational style or the other.

Instead of passing a SgProject node to the unparse() method, one may also pass lower-level nodes, such as SgAsmInterpretation, SgAsmFunction, SgAsmBlock, or even a single SgAsmInstruction. The unparser operates finding the list of top-level, unparsable nodes (see find_unparsable_nodes()) reachable from the specified node and then unparsing each one. For each node, an appropriate unparse_TYPE() is called, where TYPE is "insn", "basicblock", "staticdata", "datablock", "function", or "interpretation". Each of these unparse functions invokes three lists of callbacks:

The TYPE_pre callback list outputs header information for the TYPE object. E.g., for instructions, it might emit an address or the raw bytes.
The TYPE_unparse callback list outputs the body of the object. E.g., for basic blocks this would be the list of instructions belonging to the block.
The TYPE_post callback list outputs footer information for the object. E.g., for functions this could be a blank line to separate one function from another.

The callback lists are initialized to contain the following functor types. Some callbacks are no-ops for certain organizations of the output, and these are noted.

Instruction callbacks (SgAsmInstruction).
1. InsnBlockSeparation (pre): emits inter-block spacing when output is organized by address.
2. InsnSkipBackStart (pre): prints skip/back info when output is organized by address.
3. InsnFuncEntry (pre): emits function info at entry points when output is organized by address.
4. InsnRawBytes (pre): emits address and raw bytes of instruction in a hexdump-like format.
5. InsnBlockEntry (pre): emits info about first instruction of each block when output is organized by address.
6. InsnStackDelta (pre): emits stack delta constant if known
7. InsnBody (unparse): emits the instruction mnemonic and arguments.
8. InsnNoEffect (post): emits an indication when an instruction is part of a no-effect sequence of instructions. This functor only has an effect if the BasicBlockNoopUpdater functor is run as part of the pre-callbacks for basic blocks.
9. InsnComment (post): emits any comment associated with the instruction.
10. InsnLineTermination (post): emits a line feed at the end of the instruction.
11. InsnSkipBackEnd (post): updates skip/back info at the end of the instruction.
Basic block callbacks (SgAsmBlock objects containing only instruction objects). These callbacks are not invoked when output is organized by address.
1. BasicBlockReasons (pre): emits the reasons why this block is part of the function.
2. BasicBlockPredecessors (pre): emits addresses of basic block control flow predecessors.
3. BasicBlockBody (unparse): unparses each instruction of the basic block.
4. BasicBlockOutgoingStackDelta (post): final stack delta if known.
5. BasicBlockSuccessors (post): emits addresses of basic block control flow successors.
6. BasicBlockLineTermination (post): emits a linefeed at the end of each basic block.
7. BasicBlockCleanup (post): cleans up analysis from BasicBlockNoopUpdater and future built-in functors.
StaticData (SgAsmStaticData):
1. StaticDataBlockSeparation (pre): emits inter-block spacing when output is organized by address.
2. StaticDataSkipBackStart (pre): prints skip/back info when output is organized by address.
3. StaticDataRawBytes (pre): emits a hexdump-like output of the value.
4. StaticDataBlockEntry (pre): emits info about the first data node of each data block when output is organzied by address.
5. StaticDataDetails (unparse): info about starting address, size, type, etc. We will probably split this callback into smaller parts once we have something interesting to denote.
6. StaticDataComment (unparse): emits any comment associated with the data.
7. StaticDataLineTermination (post): emits a linefeed at the end of each data object.
8. StaticDataDisassembler (post): disassembles data as if it were code.
9. StaticDataSkipBackEnd (post): updates skip/back info at the end of a static data block.
Data blocks (SgAsmBlock objects containing only data objects):
1. DataBlockBody (unparse): unparse each data object in the block.
2. DataBlockLineTermination (post): emits a linefeed at the end of each data block.
Functions:
1. FunctionEntryAddress (pre): emits the function's entry virtual address.
2. FunctionSeparator (pre): emits a bunch of "=" characters to make the function stand out.
3. FunctionReasons (pre): emits the reasons why this address is considered the start of a function.
4. FunctionName (pre): emits the name of the function in angle brackets, or "no name".
5. FunctionLineTermination (pre): emits a linefeed for functions.
6. FunctionComment (pre): emits function comments followed by a linefeed if necessary.
7. FunctionPredecessors (pre): emits information about what calls this function
8. FunctionSuccessors (pre): emits information about what functions are called by this function.
9. FunctionAttributes (pre): emits additional information about the function, such as whether it returns to the caller.
10. FunctionLineTermination (pre): blank line before first block.
12. FunctionBody (unparse): unparses the basic blocks of a function.
Interpretations:
1. InterpName (pre): emits the name of the interpratation based on the file headers present.
2. InterpBody (pre): unparses teh functions making up an interpretation.

Additional functors are defined within the AsmUnparser class but are not installed into the callback lists by default. They're only provided because they might be useful to end users.

Static Data Disassembly

Sometimes ROSE mistakenly assumes that certain parts of the address space are static data. This can happen, for example, when code is unreachable. One common place this happens is when a call is made to a function that never returns, but the compiler thought it might return. It's often useful to be able to disassemble these static data areas and present them as instructions (in addition to the usual data presentation). Originally, this had to be done by hand using a derived AsmUnparser class and registering a static data unparser that did the disassembly, but now the AsmUnparser class defines a staticDataDisassembler callback (of type StaticDataDisassembler) for this purpose. In order to disassemble static data, one needs to provide the staticDataDisassembler with a disassembler. One way to do that is to use the default disassembler for the interpretation that's being unparsed. One could also use the same disassembler that was originally used to disassemble the entire specimen. In either case, setting the disassembler's recursion properties is probably wise since static data is often meaningless as instructions.

SgAsmInterpretation *interp = ...;
Disassembler::BasePtr disassembler = Disassembler::lookup(interp);
disassembler->set_search(Disassembler::SEARCH_DEFAULT | Disassembler::SEARCH_DEADEND |
                         Disassembler::SEARCH_UNKNOWN | Disassembler::SEARCH_UNUSED);
AsmUnparser unparser;
unparser.staticDataDisassembler.init(disassembler);
unparser.unparse(std::cout, interp);
delete disassembler; // ok to delete since we won't be using unparser anymore

The output will look something like this:

0x0804828f: 00 ff 35 a0 95 04 08 ff |..5.....|
0x08048297: 25 a4 95 04 08 00 00 00 |%.......|
0x0804829f: 00                      |.       | 17 bytes untyped data beginning at 0x0804828f
0x0804828f: 00 ff                   |..      | (data)   add    bh, bh
0x08048291: 35 a0 95 04 08          |5....   | (data)   xor    eax, 0x080495a0
0x08048296: ff 25 a4 95 04 08       |.%....  | (data)   jmp    DWORD PTR ds:[0x080495a4]
0x0804829c: 00 00                   |..      | (data)   add    BYTE PTR ds:[eax], al
0x0804829e: 00 00                   |..      | (data)   add    BYTE PTR ds:[eax], al

Examples

Changing register names

This example shows how one can replace a register name with something else. Let's say that MIPS32 Release 1 instructions are being unparsed and you'd rather see "lr" (for "link register") rather than "r31" or "ra". This can be accomplished by creating a new register dictionary, adding the definition for "lr", and using that dictionary for unparsing:

RegisterDictionary::Ptr myRegisters = RegisterDictionary::instance("My Mips32 Release 1");
myRegisters->insert(RegisterDictionary::instanceMips32()); // incorporate MIPS32 defns
RegisterDescriptor *r31 = myRegisters->lookup("r31"); // definition for r31
myRegisters->insert("lr", *r31); // new name, same old definition
AsmUnparser unparser;
unparser.set_registers(myRegisters);
SgAsmInterpretation interp = ...; // the stuff to unparse
unparser.unparse(std::cout, interp);

Unparsing to HTML

This next example shows how to escape entire instructions for HTML output, and surround each instruction with an HTML table row. We could have just as easily combined all three parts into a single functor, but doing it this way makes the example a bit more interesting.

class UnparseForHTML: public AsmUnparser {
 
    // Callback to emit the beginning of the table row.
    class BB_Prologue: public UnparserCallback {
    public:
        virtual bool operator()(bool enabled, const BasicBlockArgs &args) {
            if (enabled)
                args.output <<"<tr><td>";
            return enabled;
        }
    } bb_prologue;
 
    // Callback to output the instructions into a string and then escape
    // any characters that are special to HTML.
    class BB_Body: public UnparserCallback {
    public:
        virtual bool operator()(bool enabled, const BasicBlockArgs &args) {
            if (enabled) {
                for (size_t i=0; i<args.insns.size(); i++) {
                    std::ostringstream ss;
                    args.unparser->unparse_insn(ss, args.insns[i], i);
                    args.output <<StringUtility::htmlEscape(ss.str());
                }
            }
            return enabled;
        }
    } bb_body;
 
    // Callback to emit the end of the table row.
    class BB_Epilogue: public UnparserCallback {
    public:
        virtual bool operator()(bool enabled, const BasicBlockArgs &args) {
            if (enabled)
                args.output <<"</tr></td>";
            return enabled;
        }
    } bb_epilogue;
 
    // The constructor makes some adjustments to the callback lists.  The
    // basicBlockBody is the functor that would normally emit the instructions
    // of the basic block.
    UnparseForHTML() {
        basicblock_callbacks.pre.prepend(&bb_prologue);
        basicblock_callbacks.unparse.replace(&basicBlockBody, &bb_body);
        basicblock_callbacks.post.append(&bb_epilogue);
    }
};
 
void
unparse_binary(std::ostream &output, SgNode *ast)
{
    output <<"<table>";
    UnparseForHTML().unparse(output, ast);
    output <<"</table>";
}

Definition at line 257 of file AsmUnparser.h.

#include <backend/asmUnparser/AsmUnparser.h>

Collaboration diagram for Rose::BinaryAnalysis::AsmUnparser:

[legend]

Classes
class	BasicBlockBody
	Functor to emit the instructions that belong to a basic block. More...

class	BasicBlockCleanup
	Functor to clean up after basic block. More...

class	BasicBlockLineTermination
	Functor to emit a blank line after every basic block. More...

class	BasicBlockNoopUpdater
	Functor to update unparser's is_noop array. More...

class	BasicBlockNoopWarning
	Functor to emit a warning if the block contains any no-effect sequences. More...

class	BasicBlockOutgoingStackDelta
	Functor to emit basic block outgoing stack delta. More...

class	BasicBlockPredecessors
	Functor to emit control flow predecessor addresses. More...

class	BasicBlockReasons
	Functor to emit reasons this block is part of a function. More...

class	BasicBlockSuccessors
	Functor to emit block successor list. More...

struct	CallbackLists

class	DataBlockBody
	Functor to emit each data statement of the block. More...

class	DataBlockLineTermination
	Functor to emit a blank line after every data block. More...

class	DataBlockTitle
	Functor to print some information at the beginning of a data block. More...

class	FunctionAttributes
	Functor to emit function attributes. More...

class	FunctionBody
	Functor to unparse the function body. More...

class	FunctionComment
	Functor to print function comments followed by a linefeed if necessary. More...

class	FunctionEntryAddress
	Functor to emit function entry address. More...

class	FunctionLineTermination
	Functor to emit function line termination. More...

class	FunctionName
	Functor to emit function name. More...

class	FunctionPredecessors
	Functor to print caller addresses. More...

class	FunctionReasons
	Functor to emit function reasons. More...

class	FunctionSeparator
	Functor to emit function separator. More...

class	FunctionSuccessors
	Functor to print callee addresses. More...

class	InsnAddress
	Functor to emit instruction address. More...

class	InsnBlockEntry
	Functor to emit info about the first instruction of a block. More...

class	InsnBlockSeparation
	Functor to emit basic block separation in output organized by address. More...

class	InsnBody
	Functor to emit the entire instruction. More...

class	InsnComment
	Functor to emit instruction comment, if any. More...

class	InsnFuncEntry
	Functor to emit function information at entry points. More...

class	InsnLineTermination
	Functor to emit instruction line termination. More...

class	InsnNoEffect
	Functor to emit a note about instructions that have no effect. More...

class	InsnRawBytes
	Functor to emit instruction bytes. More...

class	InsnSkipBackBegin
	Functor to print skip/back information when an instruction is entered. More...

class	InsnSkipBackEnd
	Update instruction end address for skip/back reporting. More...

class	InsnStackDelta
	Functor to emit the numeric stack delta at each instruction. More...

class	InterpBody
	Functor to emit the functions in an interpretation. More...

class	InterpName
	Functor to emit interpretation name. More...

struct	LinePrefix
	Details for line prefixes. More...

struct	SkipBack
	Details for skip/back reporting. More...

class	StaticDataBlockEntry
	Functor to emit info about the first data node of a block. More...

class	StaticDataBlockSeparation
	Functor to emit data block separation in output organized by address. More...

class	StaticDataComment
	Functor to emit optional static data comment. More...

class	StaticDataDetails
	Functor to emit details about static data. More...

class	StaticDataDisassembler
	Disassembles static data as if it were code. More...

class	StaticDataLineTermination
	Functor to emit a blank line after every data block. More...

class	StaticDataRawBytes
	Functor to emit the bytes of the data block. More...

class	StaticDataSkipBackBegin
	Functor to print skip/back information when a static data block is entered. More...

class	StaticDataSkipBackEnd
	Update static data end address for skip/back reporting. More...

class	UnparserCallback

Public Types
enum	Organization { ORGANIZED_BY_AST , ORGANIZED_BY_ADDRESS }

typedef Rose::BinaryAnalysis::ControlFlow::Graph	CFG
	Control Flow Graph type.

typedef boost::graph_traits< CFG >::vertex_descriptor	CFG_Vertex

typedef std::map< SgAsmBlock *, CFG_Vertex >	CFG_BlockMap

typedef Rose::BinaryAnalysis::FunctionCall::Graph	CG

typedef boost::graph_traits< CG >::vertex_descriptor	CG_Vertex

typedef std::map< SgAsmFunction *, CG_Vertex >	CG_FunctionMap

typedef std::map< uint64_t, std::string >	LabelMap
	Maps integers to labels.

Public Member Functions
	AsmUnparser ()
	Constructor that intializes the "unparser" callback lists with some useful functors.

virtual bool	is_unparsable_node (SgNode *node)
	Determines if a node can be unparsed.

virtual SgNode *	find_unparsable_node (SgNode *ast)
	Finds first unparsable node.

virtual std::vector< SgNode * >	find_unparsable_nodes (SgNode *ast)
	Finds top unparsable nodes.

virtual size_t	unparse (std::ostream &, SgNode *ast)
	Unparse part of the AST.

std::string	to_string (SgNode *ast)
	Unparse part of the AST into a string.

virtual bool	unparse_one_node (std::ostream &, SgNode *)
	Unparse a single node if possible.

void	add_function_labels (SgNode *ast)
	Adds function labels to the label map.

void	add_control_flow_graph (const Rose::BinaryAnalysis::ControlFlow::Graph &cfg)
	Associates a control flow graph with this unparser.


virtual Organization	get_organization () const
	Get/set how output is organized.

virtual void	set_organization (Organization organization)
	Get/set how output is organized.


virtual RegisterDictionaryPtr	get_registers () const
	Register dictionaries.

virtual void	set_registers (const RegisterDictionaryPtr &registers)
	Register dictionaries.


virtual bool	unparse_insn (bool enabled, std::ostream &, SgAsmInstruction *, size_t position_in_block=(size_t) -1)
	Unparse an object.

virtual bool	unparse_basicblock (bool enabled, std::ostream &, SgAsmBlock *)
	Unparse an object.

virtual bool	unparse_staticdata (bool enabled, std::ostream &, SgAsmStaticData *, size_t position_in_block=(size_t) -1)
	Unparse an object.

virtual bool	unparse_datablock (bool enabled, std::ostream &, SgAsmBlock *)
	Unparse an object.

virtual bool	unparse_function (bool enabled, std::ostream &, SgAsmFunction *)
	Unparse an object.

virtual bool	unparse_interpretation (bool enabled, std::ostream &, SgAsmInterpretation *)
	Unparse an object.


void	set_skipback_reporting (bool b=true)
	Controls printing of skip/back messages during linear output.

void	clear_skipback_reporting ()
	Controls printing of skip/back messages during linear output.

bool	get_skipback_reporting () const
	Controls printing of skip/back messages during linear output.

void	reset_skipback ()
	Controls printing of skip/back messages during linear output.

void	start_of_object (rose_addr_t, std::ostream &)
	Controls printing of skip/back messages during linear output.

void	end_of_object (rose_addr_t)
	Controls printing of skip/back messages during linear output.


virtual void	set_prefix_format (const std::string &format)
	Controls printing of line prefixes.

virtual const std::string &	get_prefix_format () const
	Controls printing of line prefixes.

virtual void	set_prefix_address (rose_addr_t va)
	Controls printing of line prefixes.

virtual rose_addr_t	get_prefix_address () const
	Controls printing of line prefixes.

virtual std::string	line_prefix () const
	Controls printing of line prefixes.

virtual std::string	blank_prefix () const
	Controls printing of line prefixes.

Static Public Member Functions
static void	initDiagnostics ()
	Initialize diagnostic messages subsystem.

Public Attributes
std::vector< bool >	insn_is_noop
	Optional information about no-op sequences.

Functors
Functors used by the base class. We declare these as public so users can have an address by which to search through the various callback lists. For instance, if the user doesn't want to see instruction raw bytes, they just remove the insnRawBytes callback from the appropriate list(s).
InsnSkipBackBegin	insnSkipBackBegin

InsnBlockSeparation	insnBlockSeparation

InsnFuncEntry	insnFuncEntry

InsnAddress	insnAddress

InsnRawBytes	insnRawBytes

InsnBlockEntry	insnBlockEntry

InsnStackDelta	insnStackDelta

InsnBody	insnBody

InsnNoEffect	insnNoEffect

InsnComment	insnComment

InsnLineTermination	insnLineTermination

InsnSkipBackEnd	insnSkipBackEnd

BasicBlockReasons	basicBlockReasons

BasicBlockPredecessors	basicBlockPredecessors

BasicBlockNoopUpdater	basicBlockNoopUpdater

BasicBlockNoopWarning	basicBlockNoopWarning

BasicBlockBody	basicBlockBody

BasicBlockOutgoingStackDelta	basicBlockOutgoingStackDelta

BasicBlockSuccessors	basicBlockSuccessors

BasicBlockLineTermination	basicBlockLineTermination

BasicBlockCleanup	basicBlockCleanup

StaticDataSkipBackBegin	staticDataSkipBackBegin

StaticDataBlockSeparation	staticDataBlockSeparation

StaticDataRawBytes	staticDataRawBytes

StaticDataBlockEntry	staticDataBlockEntry

StaticDataDetails	staticDataDetails

StaticDataComment	staticDataComment

StaticDataLineTermination	staticDataLineTermination

StaticDataDisassembler	staticDataDisassembler

StaticDataSkipBackEnd	staticDataSkipBackEnd

DataBlockBody	dataBlockBody

DataBlockLineTermination	dataBlockLineTermination

FunctionEntryAddress	functionEntryAddress

FunctionSeparator	functionSeparator

FunctionReasons	functionReasons

FunctionName	functionName

FunctionLineTermination	functionLineTermination

FunctionComment	functionComment

FunctionPredecessors	functionPredecessors

FunctionSuccessors	functionSuccessors

FunctionAttributes	functionAttributes

FunctionBody	functionBody

InterpName	interpName

InterpBody	interpBody

Static Public Attributes
static Sawyer::Message::Facility	mlog
	Diagnostic messages.

Protected Member Functions
virtual void	init ()
	Initializes the callback lists.

Protected Attributes
CallbackLists	insn_callbacks
	Callbacks for instruction unparsing.

CallbackLists	basicblock_callbacks
	Callbacks for basic block unparsing.

CallbackLists	staticdata_callbacks
	Callbacks for static data unparsing.

CallbackLists	datablock_callbacks
	Callbacks for data block unparsing.

CallbackLists	function_callbacks
	Callbacks for function unparsing.

CallbackLists	interp_callbacks
	Callbacks for interpretation unparsing.

LabelMap	labels
	This map is consulted whenever a constant is encountered.

Organization	organization
	How output will be organized.

RegisterDictionaryPtr	user_registers
	Dictionaries used to convert register descriptors to register names.

RegisterDictionaryPtr	interp_registers

CFG	cfg
	Control flow graph.

CFG_BlockMap	cfg_blockmap
	A mapping from SgAsmBlock to control flow graph vertex.

CG	cg
	Function call graph.

CG_FunctionMap	cg_functionmap
	A mapping from SgAsmFunction to call graph vertex.

struct Rose::BinaryAnalysis::AsmUnparser::SkipBack	skipback

struct Rose::BinaryAnalysis::AsmUnparser::LinePrefix	lineprefix

Member Typedef Documentation

◆ CFG

typedef Rose::BinaryAnalysis::ControlFlow::Graph Rose::BinaryAnalysis::AsmUnparser::CFG

Control Flow Graph type.

The unparser supports the standard binary control flow graph data type. This could be templatized, but we're planning to move to a non-template graph type in the near future [RPM 2012-04-18].

Definition at line 273 of file AsmUnparser.h.

◆ CFG_Vertex

typedef boost::graph_traits<CFG>::vertex_descriptor Rose::BinaryAnalysis::AsmUnparser::CFG_Vertex

Definition at line 274 of file AsmUnparser.h.

◆ CFG_BlockMap

typedef std::map<SgAsmBlock*, CFG_Vertex> Rose::BinaryAnalysis::AsmUnparser::CFG_BlockMap

Definition at line 275 of file AsmUnparser.h.

◆ CG

typedef Rose::BinaryAnalysis::FunctionCall::Graph Rose::BinaryAnalysis::AsmUnparser::CG

Definition at line 276 of file AsmUnparser.h.

◆ CG_Vertex

typedef boost::graph_traits<CG>::vertex_descriptor Rose::BinaryAnalysis::AsmUnparser::CG_Vertex

Definition at line 277 of file AsmUnparser.h.

◆ CG_FunctionMap

typedef std::map<SgAsmFunction*, CG_Vertex> Rose::BinaryAnalysis::AsmUnparser::CG_FunctionMap

Definition at line 278 of file AsmUnparser.h.

◆ LabelMap

typedef std::map<uint64_t, std::string> Rose::BinaryAnalysis::AsmUnparser::LabelMap

Maps integers to labels.

Definition at line 902 of file AsmUnparser.h.

Member Enumeration Documentation

◆ Organization

enum Rose::BinaryAnalysis::AsmUnparser::Organization

Enumerator

ORGANIZED_BY_AST

Output follows the AST organization.

In other words, the instructions and data for a block appear consecutively, the blocks of a function appear consecutively, and the functions of an interpretation appear consecutively. This is the default format since it provides the most information about the organization of the binary file.

ORGANIZED_BY_ADDRESS

Output of instructions and data are organized by address.

Specifically, in the case of overlapping instructions and/or data, the starting address is used to sort the output. This organization is typical of more traditional disassemblers.

Definition at line 259 of file AsmUnparser.h.

Member Function Documentation

◆ get_organization()

virtual Organization Rose::BinaryAnalysis::AsmUnparser::get_organization ( ) const

inlinevirtual

Get/set how output is organized.

The unparse() method organizes output by one of the methods described for the Organization enum.

Definition at line 817 of file AsmUnparser.h.

◆ set_organization()

virtual void Rose::BinaryAnalysis::AsmUnparser::set_organization ( Organization organization )

inlinevirtual

Get/set how output is organized.

The unparse() method organizes output by one of the methods described for the Organization enum.

Definition at line 818 of file AsmUnparser.h.

◆ is_unparsable_node()

virtual bool Rose::BinaryAnalysis::AsmUnparser::is_unparsable_node ( SgNode * node )

virtual

Determines if a node can be unparsed.

The AsmUnparser only handles certain node types, namely those that correspond to binary functions, blocks, and instructions. This method should return true if the specified node is one that can be parsed. See also, find_unparsable_node().

◆ find_unparsable_node()

virtual SgNode * Rose::BinaryAnalysis::AsmUnparser::find_unparsable_node ( SgNode * ast )

virtual

Finds first unparsable node.

Traverses the specified AST to find a node that can be unparsed, and returns it. The traversal is a depth-first traversal with pre-order visiting. The traversal terminates as soon as a node is found. Returns false if no suitable node can be found.

◆ find_unparsable_nodes()

virtual std::vector< SgNode * > Rose::BinaryAnalysis::AsmUnparser::find_unparsable_nodes ( SgNode * ast )

virtual

Finds top unparsable nodes.

Traverses the specified AST to find nodes that can be unparsed, and returns a vector of such nodes. Once a node is discovered, the subtree rooted at that node is not searched.

◆ get_registers()

virtual RegisterDictionaryPtr Rose::BinaryAnalysis::AsmUnparser::get_registers ( ) const

virtual

Register dictionaries.

A register dictionary is used to convert register descriptors stored within instructions (via RegisterDescriptor) into names. The unparser keeps two register dictionaries: the user-specified register dictionary, and a dictionary obtained from a SgAsmInterpretation. The user-specified dictionary is used in preference to the SgAsmInterpretation dictionary when both are specified. The SgAsmInterpretation dictionary is set (internally) whenever an SgAsmInterpretation node is encountered during unparsing, and reset after the entire node is unparsed. The user-specified dictionary is set via the set_registers() method. The get_registers() returns either the user-specified or SgAsmInterpretation dictionary.

◆ set_registers()

virtual void Rose::BinaryAnalysis::AsmUnparser::set_registers ( const RegisterDictionaryPtr & registers )

virtual

Register dictionaries.

A register dictionary is used to convert register descriptors stored within instructions (via RegisterDescriptor) into names. The unparser keeps two register dictionaries: the user-specified register dictionary, and a dictionary obtained from a SgAsmInterpretation. The user-specified dictionary is used in preference to the SgAsmInterpretation dictionary when both are specified. The SgAsmInterpretation dictionary is set (internally) whenever an SgAsmInterpretation node is encountered during unparsing, and reset after the entire node is unparsed. The user-specified dictionary is set via the set_registers() method. The get_registers() returns either the user-specified or SgAsmInterpretation dictionary.

◆ unparse()

virtual size_t Rose::BinaryAnalysis::AsmUnparser::unparse	(	std::ostream &	,
		SgNode *	ast
	)

virtual

Unparse part of the AST.

This is the primary method for this class. It traverses the specified ast and prints some kind of assembly language output to the specified output stream. The specifics of what is produced depend on how the AsmUnparser is configured.

The return value is the number of unparsable nodes encountered and has various meanings depending on the output organization. For output organized by AST it is the number of "top-level unparsable nodes", the number of nodes, R, such that is_unparsable_node(R) is true, and there exists no node C such that C is a proper ancestor of R and contained in the specified AST. For output organized by address, it is the number of instructions and data objects unparsed. In any case, a return value of zero means that nothing was unparsed and no output was produced.

◆ to_string()

std::string Rose::BinaryAnalysis::AsmUnparser::to_string ( SgNode * ast )

Unparse part of the AST into a string.

This is a wrapper around unparse() that returns a string rather than producing output on a stream.

◆ unparse_one_node()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_one_node	(	std::ostream &	,
		SgNode *
	)

virtual

Unparse a single node if possible.

Tries to unparse the given AST node directly, without traversing the AST to find a starting point. This is basically a big switch statement that calls one of the unparse_WHATEVER() methods.

Returns true if the node was unparsed, false otherwise.

◆ unparse_insn()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_insn	(	bool	enabled,
		std::ostream &	,
		SgAsmInstruction *	,
		size_t	position_in_block = `(size_t) -1`
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ unparse_basicblock()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_basicblock	(	bool	enabled,
		std::ostream &	,
		SgAsmBlock *
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ unparse_staticdata()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_staticdata	(	bool	enabled,
		std::ostream &	,
		SgAsmStaticData *	,
		size_t	position_in_block = `(size_t) -1`
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ unparse_datablock()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_datablock	(	bool	enabled,
		std::ostream &	,
		SgAsmBlock *
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ unparse_function()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_function	(	bool	enabled,
		std::ostream &	,
		SgAsmFunction *
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ unparse_interpretation()

virtual bool Rose::BinaryAnalysis::AsmUnparser::unparse_interpretation	(	bool	enabled,
		std::ostream &	,
		SgAsmInterpretation *
	)

virtual

Unparse an object.

These are called by unparse_one_node(), but might also be called by callbacks.

◆ add_function_labels()

void Rose::BinaryAnalysis::AsmUnparser::add_function_labels ( SgNode * ast )

Adds function labels to the label map.

This method traverses the specified AST looking for function symbols, and adds their address and name to the label map for the unparser. The map is used by some callbacks to convert numeric values to more human friendly labels. If integer values are relative to other AST nodes, then one doesn't need to populate the LabelMap (see documentation for the AsmUnparser::labels data member.

◆ add_control_flow_graph()

void Rose::BinaryAnalysis::AsmUnparser::add_control_flow_graph ( const Rose::BinaryAnalysis::ControlFlow::Graph & cfg )

Associates a control flow graph with this unparser.

If a control flow graph is present then certain output callbacks will be able to use that information. For instance, the basicBlockPredecessors will emit a list of all the predecessors of a block. Passing an empty graph will remove control flow information.