ROSE  0.9.9.109
Classes | Public Member Functions | Static Public Member Functions | List of all members
Rose::BinaryAnalysis::Partitioner2::Engine Class Reference

Description

Base class for engines driving the partitioner.

An engine serves these main purposes:

Use of an engine is entirely optional. All of the engine's actions are implemented in terms of public APIs on other objects such as Disassembler and Partitioner. In fact, this particular engine base class is disigned so that users can pick and choose to use only those steps they need, or perhaps to call the main actions one step at a time with the user making adjustments between steps.

Custimization

The actions taken by an engine can be customized in a number of ways:

Basic usage

The most basic use case for the engine is to pass it the command-line arguments and have it do everything, eventually returning an abstract syntax tree.

#include <rose.h>
#include <Partitioner2/Engine.h>
using namespace Rose;
int main(int argc, char *argv[]) {
std::string purpose = "disassembles a binary specimen";
std::string description =
"This tool disassembles the specified specimen and presents the "
"results as a pseudo assembly listing, that is, a listing intended "
"for human consumption rather than assembly.";
SgAsmBlock *gblock = P2::Engine().frontend(argc, argv, purpose, description);

High level operations

While frontend does everything, it's often useful to break it down to individual steps so that adjustments can be made along the way. This next level of steps are:

Definition at line 100 of file Engine.h.

#include <Engine.h>

Classes

struct  Settings
 Settings for the engine. More...
 

Public Member Functions

 Engine ()
 Default constructor. More...
 
 Engine (const Settings &settings)
 Construct engine with settings. More...
 
void reset ()
 Reset the engine to its initial state. More...
 
virtual Sawyer::CommandLine::SwitchGroup loaderSwitches ()
 Command-line switches related to the loader. More...
 
virtual Sawyer::CommandLine::SwitchGroup disassemblerSwitches ()
 Command-line switches related to the disassembler. More...
 
virtual Sawyer::CommandLine::SwitchGroup partitionerSwitches ()
 Command-line switches related to the partitioner. More...
 
virtual Sawyer::CommandLine::SwitchGroup engineSwitches ()
 Command-line switches related to engine behavior. More...
 
virtual Sawyer::CommandLine::SwitchGroup astConstructionSwitches ()
 Command-line switches related to AST construction. More...
 
virtual Sawyer::CommandLine::Parser commandLineParser (const std::string &purpose, const std::string &description)
 Creates a command-line parser. More...
 
virtual void checkSettings ()
 Check settings after command-line is processed. More...
 
virtual bool isNonContainer (const std::string &)
 Determine whether a specimen name is a non-container. More...
 
virtual bool areContainersParsed () const
 Returns true if containers are parsed. More...
 
virtual bool areSpecimensLoaded () const
 Returns true if specimens are loaded. More...
 
virtual BinaryLoaderobtainLoader (BinaryLoader *hint=NULL)
 Obtain a binary loader. More...
 
virtual void loadContainers (const std::vector< std::string > &fileNames)
 Loads memory from binary containers. More...
 
virtual void loadNonContainers (const std::vector< std::string > &names)
 Loads memory from non-containers. More...
 
virtual void adjustMemoryMap ()
 Adjust memory map post-loading. More...
 
virtual DisassemblerobtainDisassembler (Disassembler *hint=NULL)
 Obtain a disassembler. More...
 
virtual void checkCreatePartitionerPrerequisites () const
 Check that we have everything necessary to create a partitioner. More...
 
virtual Partitioner createBarePartitioner ()
 Create a bare partitioner. More...
 
virtual Partitioner createGenericPartitioner ()
 Create a generic partitioner. More...
 
virtual Partitioner createTunedPartitioner ()
 Create a tuned partitioner. More...
 
virtual Partitioner createPartitionerFromAst (SgAsmInterpretation *)
 Create a partitioner from an AST. More...
 
virtual Partitioner createPartitioner ()
 Create partitioner. More...
 
virtual void runPartitionerInit (Partitioner &)
 Finds interesting things to work on initially. More...
 
virtual void runPartitionerRecursive (Partitioner &)
 Runs the recursive part of partioning. More...
 
virtual void runPartitionerFinal (Partitioner &)
 Runs the final parts of partitioning. More...
 
virtual void runPartitioner (Partitioner &)
 Partitions instructions into basic blocks and functions. More...
 
virtual void labelAddresses (Partitioner &)
 Label addresses. More...
 
virtual std::vector< DataBlock::PtrmakeConfiguredDataBlocks (Partitioner &, const Configuration &)
 Make data blocks based on configuration. More...
 
virtual std::vector< Function::PtrmakeConfiguredFunctions (Partitioner &, const Configuration &)
 Make functions based on configuration information. More...
 
virtual std::vector< Function::PtrmakeEntryFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions at specimen entry addresses. More...
 
virtual std::vector< Function::PtrmakeErrorHandlingFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions at error handling addresses. More...
 
virtual std::vector< Function::PtrmakeImportFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions at import trampolines. More...
 
virtual std::vector< Function::PtrmakeExportFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions at export addresses. More...
 
virtual std::vector< Function::PtrmakeSymbolFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions for symbols. More...
 
virtual std::vector< Function::PtrmakeContainerFunctions (Partitioner &, SgAsmInterpretation *)
 Make functions based on specimen container. More...
 
virtual std::vector< Function::PtrmakeInterruptVectorFunctions (Partitioner &, const AddressInterval &vector)
 Make functions from an interrupt vector. More...
 
virtual std::vector< Function::PtrmakeUserFunctions (Partitioner &, const std::vector< rose_addr_t > &)
 Make a function at each specified address. More...
 
virtual void discoverBasicBlocks (Partitioner &)
 Discover as many basic blocks as possible. More...
 
virtual Function::Ptr makeNextDataReferencedFunction (const Partitioner &, rose_addr_t &startVa)
 Scan read-only data to find function pointers. More...
 
virtual Function::Ptr makeNextCodeReferencedFunction (const Partitioner &)
 Scan instruction ASTs to function pointers. More...
 
virtual std::vector< Function::PtrmakeCalledFunctions (Partitioner &)
 Make functions for function call edges. More...
 
virtual std::vector< Function::PtrmakeNextPrologueFunction (Partitioner &, rose_addr_t startVa)
 Make function at prologue pattern. More...
 
virtual std::vector< Function::PtrmakeFunctionFromInterFunctionCalls (Partitioner &partitioner, rose_addr_t &startVa)
 Make functions from inter-function calls. More...
 
virtual void discoverFunctions (Partitioner &)
 Discover as many functions as possible. More...
 
virtual std::set< rose_addr_t > attachDeadCodeToFunction (Partitioner &, const Function::Ptr &, size_t maxIterations=size_t(-1))
 Attach dead code to function. More...
 
virtual DataBlock::Ptr attachPaddingToFunction (Partitioner &, const Function::Ptr &)
 Attach function padding to function. More...
 
virtual std::vector< DataBlock::PtrattachPaddingToFunctions (Partitioner &)
 Attach padding to all functions. More...
 
virtual size_t attachAllSurroundedCodeToFunctions (Partitioner &)
 Attach all possible intra-function basic blocks to functions. More...
 
virtual size_t attachSurroundedCodeToFunctions (Partitioner &)
 Attach intra-function basic blocks to functions. More...
 
virtual void attachBlocksToFunctions (Partitioner &)
 Attach basic blocks to functions. More...
 
virtual std::set< rose_addr_t > attachDeadCodeToFunctions (Partitioner &, size_t maxIterations=size_t(-1))
 Attach dead code to functions. More...
 
virtual std::vector< DataBlock::PtrattachSurroundedDataToFunctions (Partitioner &)
 Attach intra-function data to functions. More...
 
virtual void updateAnalysisResults (Partitioner &)
 Runs various analysis passes. More...
 
virtual bool makeNextCallReturnEdge (Partitioner &, boost::logic::tribool assumeCallReturns)
 Insert a call-return edge and discover its basic block. More...
 
virtual BasicBlock::Ptr makeNextBasicBlockFromPlaceholder (Partitioner &)
 Discover basic block at next placeholder. More...
 
virtual BasicBlock::Ptr makeNextBasicBlock (Partitioner &)
 Discover a basic block. More...
 
SgAsmBlockfrontend (int argc, char *argv[], const std::string &purpose, const std::string &description)
 Most basic usage of the partitioner. More...
 
virtual SgAsmBlockfrontend (const std::vector< std::string > &args, const std::string &purpose, const std::string &description)
 Most basic usage of the partitioner. More...
 
Sawyer::CommandLine::ParserResult parseCommandLine (int argc, char *argv[], const std::string &purpose, const std::string &description)
 Parse the command-line. More...
 
virtual Sawyer::CommandLine::ParserResult parseCommandLine (const std::vector< std::string > &args, const std::string &purpose, const std::string &description)
 Parse the command-line. More...
 
virtual SgAsmInterpretationparseContainers (const std::vector< std::string > &fileNames)
 Parse specimen binary containers. More...
 
SgAsmInterpretationparseContainers (const std::string &fileName)
 Parse specimen binary containers. More...
 
virtual MemoryMap::Ptr loadSpecimens (const std::vector< std::string > &fileNames=std::vector< std::string >())
 Load and/or link interpretation. More...
 
MemoryMap::Ptr loadSpecimens (const std::string &fileName)
 Load and/or link interpretation. More...
 
virtual Partitioner partition (const std::vector< std::string > &fileNames=std::vector< std::string >())
 Partition instructions into basic blocks and functions. More...
 
Partitioner partition (const std::string &fileName)
 Partition instructions into basic blocks and functions. More...
 
SgAsmBlockbuildAst (const std::vector< std::string > &fileNames=std::vector< std::string >())
 Obtain an abstract syntax tree. More...
 
SgAsmBlockbuildAst (const std::string &fileName)
 Obtain an abstract syntax tree. More...
 
MemoryMap::Ptr memoryMap () const
 Property: memory map. More...
 
virtual void memoryMap (const MemoryMap::Ptr &m)
 Property: memory map. More...
 
const Settingssettings () const
 Property: All settings. More...
 
Settingssettings ()
 Property: All settings. More...
 
bool exitOnError () const
 Property: Error handling. More...
 
virtual void exitOnError (bool b)
 Property: Error handling. More...
 
Progress::Ptr progress () const
 Property: progress reporting. More...
 
virtual void progress (const Progress::Ptr &progress)
 Property: progress reporting. More...
 
SgAsmInterpretationinterpretation () const
 Property: interpretation. More...
 
virtual void interpretation (SgAsmInterpretation *interp)
 Property: interpretation. More...
 
BinaryLoaderbinaryLoader () const
 Property: binary loader. More...
 
virtual void binaryLoader (BinaryLoader *loader)
 Property: binary loader. More...
 
size_t deExecuteZerosThreshold () const
 Property: when to remove execute permission from zero bytes. More...
 
virtual void deExecuteZerosThreshold (size_t n)
 Property: when to remove execute permission from zero bytes. More...
 
size_t deExecuteZerosLeaveAtFront () const
 Property: when to remove execute permission from zero bytes. More...
 
virtual void deExecuteZerosLeaveAtFront (size_t n)
 Property: when to remove execute permission from zero bytes. More...
 
size_t deExecuteZerosLeaveAtBack () const
 Property: when to remove execute permission from zero bytes. More...
 
virtual void deExecuteZerosLeaveAtBack (size_t n)
 Property: when to remove execute permission from zero bytes. More...
 
MemoryDataAdjustment memoryDataAdjustment () const
 Property: Global adjustments to memory map data access bits. More...
 
virtual void memoryDataAdjustment (MemoryDataAdjustment x)
 Property: Global adjustments to memory map data access bits. More...
 
bool memoryIsExecutable () const
 Property: Global adjustment to executability. More...
 
virtual void memoryIsExecutable (bool b)
 Property: Global adjustment to executability. More...
 
Disassemblerdisassembler () const
 Property: Disassembler. More...
 
virtual void disassembler (Disassembler *d)
 Property: Disassembler. More...
 
const std::string & isaName () const
 Property: Instruction set architecture name. More...
 
virtual void isaName (const std::string &s)
 Property: Instruction set architecture name. More...
 
const std::vector< rose_addr_t > & startingVas () const
 Property: Starting addresses for disassembly. More...
 
std::vector< rose_addr_t > & startingVas ()
 Property: Starting addresses for disassembly. More...
 
bool usingSemantics () const
 Property: Whether to use instruction semantics. More...
 
virtual void usingSemantics (bool b)
 Property: Whether to use instruction semantics. More...
 
SemanticMemoryParadigm semanticMemoryParadigm () const
 Property: Type of container for semantic memory. More...
 
virtual void semanticMemoryParadigm (SemanticMemoryParadigm p)
 Property: Type of container for semantic memory. More...
 
bool followingGhostEdges () const
 Property: Whether to follow ghost edges. More...
 
virtual void followingGhostEdges (bool b)
 Property: Whether to follow ghost edges. More...
 
bool discontiguousBlocks () const
 Property: Whether to allow discontiguous basic blocks. More...
 
virtual void discontiguousBlocks (bool b)
 Property: Whether to allow discontiguous basic blocks. More...
 
bool findingFunctionPadding () const
 Property: Whether to find function padding. More...
 
virtual void findingFunctionPadding (bool b)
 Property: Whether to find function padding. More...
 
bool findingThunks () const
 Property: Whether to find thunk patterns. More...
 
virtual void findingThunks (bool b)
 Property: Whether to find thunk patterns. More...
 
bool splittingThunks () const
 Property: Whether to split thunk instructions into mini functions. More...
 
virtual void splittingThunks (bool b)
 Property: Whether to split thunk instructions into mini functions. More...
 
bool findingDeadCode () const
 Property: Whether to find dead code. More...
 
virtual void findingDeadCode (bool b)
 Property: Whether to find dead code. More...
 
rose_addr_t peScramblerDispatcherVa () const
 Property: PE-Scrambler dispatcher address. More...
 
virtual void peScramblerDispatcherVa (rose_addr_t va)
 Property: PE-Scrambler dispatcher address. More...
 
bool findingIntraFunctionCode () const
 Property: Whether to find intra-function code. More...
 
virtual void findingIntraFunctionCode (bool b)
 Property: Whether to find intra-function code. More...
 
bool findingIntraFunctionData () const
 Property: Whether to find intra-function data. More...
 
virtual void findingIntraFunctionData (bool b)
 Property: Whether to find intra-function data. More...
 
const AddressIntervalinterruptVector () const
 Property: Location of machine interrupt vector. More...
 
virtual void interruptVector (const AddressInterval &i)
 Property: Location of machine interrupt vector. More...
 
bool doingPostAnalysis () const
 Property: Whether to perform post-partitioning analysis steps. More...
 
virtual void doingPostAnalysis (bool b)
 Property: Whether to perform post-partitioning analysis steps. More...
 
bool doingPostFunctionMayReturn () const
 Property: Whether to run the function may-return analysis. More...
 
virtual void doingPostFunctionMayReturn (bool b)
 Property: Whether to run the function may-return analysis. More...
 
bool doingPostFunctionStackDelta () const
 Property: Whether to run the function stack delta analysis. More...
 
virtual void doingPostFunctionStackDelta (bool b)
 Property: Whether to run the function stack delta analysis. More...
 
bool doingPostCallingConvention () const
 Property: Whether to run calling-convention analysis. More...
 
virtual void doingPostCallingConvention (bool b)
 Property: Whether to run calling-convention analysis. More...
 
bool doingPostFunctionNoop () const
 Property: Whether to run no-op function analysis. More...
 
virtual void doingPostFunctionNoop (bool b)
 Property: Whether to run no-op function analysis. More...
 
FunctionReturnAnalysis functionReturnAnalysis () const
 Property: Whether to run the function may-return analysis. More...
 
virtual void functionReturnAnalysis (FunctionReturnAnalysis x)
 Property: Whether to run the function may-return analysis. More...
 
bool findingInterFunctionCalls () const
 Property: Whether to search for function calls between exiting functions. More...
 
virtual void findingInterFunctionCalls (bool b)
 Property: Whether to search for function calls between exiting functions. More...
 
bool findingDataFunctionPointers () const
 Property: Whether to search static data for function pointers. More...
 
virtual void findingDataFunctionPointers (bool b)
 Property: Whether to search static data for function pointers. More...
 
bool findingCodeFunctionPointers () const
 Property: Whether to search existing instructions for function pointers. More...
 
virtual void findingCodeFunctionPointers (bool b)
 Property: Whether to search existing instructions for function pointers. More...
 
bool checkingCallBranch () const
 Property: Whether to look for function calls used as branches. More...
 
virtual void checkingCallBranch (bool b)
 Property: Whether to look for function calls used as branches. More...
 
bool basicBlockSemanticsAutoDrop () const
 Property: Automatically drop semantics for attached basic blocks. More...
 
void basicBlockSemanticsAutoDrop (bool b)
 Property: Automatically drop semantics for attached basic blocks. More...
 
const std::vector< std::string > & configurationNames () const
 Property: Configuration files. More...
 
std::vector< std::string > & configurationNames ()
 Property: Configuration files. More...
 
bool namingConstants () const
 Property: Give names to constants. More...
 
virtual void namingConstants (bool b)
 Property: Give names to constants. More...
 
bool namingStrings () const
 Property: Give names to string literal addresses. More...
 
virtual void namingStrings (bool b)
 Property: Give names to string literal addresses. More...
 
bool demangleNames () const
 Property: Demangle names. More...
 
virtual void demangleNames (bool b)
 Property: Demangle names. More...
 
bool astAllowEmptyGlobalBlock () const
 Property: Whether to allow empty global block in the AST. More...
 
virtual void astAllowEmptyGlobalBlock (bool b)
 Property: Whether to allow empty global block in the AST. More...
 
bool astAllowFunctionWithNoBasicBlocks () const
 Property: Whether to allow empty functions in the AST. More...
 
virtual void astAllowFunctionWithNoBasicBlocks (bool b)
 Property: Whether to allow empty functions in the AST. More...
 
bool astAllowEmptyBasicBlock () const
 Property: Whether to allow empty basic blocks in the AST. More...
 
virtual void astAllowEmptyBasicBlock (bool b)
 Property: Whether to allow empty basic blocks in the AST. More...
 
bool astCopyAllInstructions () const
 Property: Whether to copy instructions when building the AST. More...
 
virtual void astCopyAllInstructions (bool b)
 Property: Whether to copy instructions when building the AST. More...
 

Static Public Member Functions

static std::string specimenNameDocumentation ()
 Documentation for specimen names. More...
 
static void disassembleForRoseFrontend (SgAsmInterpretation *)
 

Constructor & Destructor Documentation

Rose::BinaryAnalysis::Partitioner2::Engine::Engine ( )
inline

Default constructor.

Definition at line 202 of file Engine.h.

Rose::BinaryAnalysis::Partitioner2::Engine::Engine ( const Settings settings)
inlineexplicit

Construct engine with settings.

Definition at line 209 of file Engine.h.

Member Function Documentation

SgAsmBlock* Rose::BinaryAnalysis::Partitioner2::Engine::frontend ( int  argc,
char *  argv[],
const std::string &  purpose,
const std::string &  description 
)

Most basic usage of the partitioner.

This method does everything from parsing the command-line to generating an abstract syntax tree. If all is successful, then an abstract syntax tree is returned. The return value is a SgAsmBlock node that contains all the detected functions. If the specimen consisted of an ELF or PE container then the parent nodes of the returned AST will lead eventually to an SgProject node.

The command-line can be provided as a typical argc and argv pair, or as a vector of arguments. In the latter case, the vector should not include argv[0] or argv[argc] (which is always a null pointer).

The command-line supports a "--help" (or "-h") switch to describe all other switches and arguments, essentially generating output like a Unix man(1) page.

The purpose should be a single line string that will be shown in the title of the man page and should not start with an upper-case letter, a hyphen, white space, or the name of the command. E.g., a disassembler tool might specify the purpose as "disassembles a binary specimen".

The description is a full, multi-line description written in the Sawyer markup language where "@" characters have special meaning.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual SgAsmBlock* Rose::BinaryAnalysis::Partitioner2::Engine::frontend ( const std::vector< std::string > &  args,
const std::string &  purpose,
const std::string &  description 
)
virtual

Most basic usage of the partitioner.

This method does everything from parsing the command-line to generating an abstract syntax tree. If all is successful, then an abstract syntax tree is returned. The return value is a SgAsmBlock node that contains all the detected functions. If the specimen consisted of an ELF or PE container then the parent nodes of the returned AST will lead eventually to an SgProject node.

The command-line can be provided as a typical argc and argv pair, or as a vector of arguments. In the latter case, the vector should not include argv[0] or argv[argc] (which is always a null pointer).

The command-line supports a "--help" (or "-h") switch to describe all other switches and arguments, essentially generating output like a Unix man(1) page.

The purpose should be a single line string that will be shown in the title of the man page and should not start with an upper-case letter, a hyphen, white space, or the name of the command. E.g., a disassembler tool might specify the purpose as "disassembles a binary specimen".

The description is a full, multi-line description written in the Sawyer markup language where "@" characters have special meaning.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

void Rose::BinaryAnalysis::Partitioner2::Engine::reset ( )

Reset the engine to its initial state.

This does not reset the settings properties since that can be done easily by constructing a new engine. It only resets the interpretation, binary loader, disassembler, and memory map so all the top-level steps get executed again. This is a useful way to re-use the same partitioner to process multiple specimens.

Sawyer::CommandLine::ParserResult Rose::BinaryAnalysis::Partitioner2::Engine::parseCommandLine ( int  argc,
char *  argv[],
const std::string &  purpose,
const std::string &  description 
)

Parse the command-line.

This method parses the command-line and uses it to update this engine's settings. Since a command line is usually more than just engine-related switches, the more usual approach is for the user to obtain engine-related command-line switch declarations and parse the command-line in user code.

This function automatically applies the command-line when it's successfully parsed, thereby updating this engine's settings. If something goes wrong with the command-line then an std::runtime_error is thrown.

The command-line can be provided as a typical argc and argv pair, or as a vector of arguments. In the latter case, the vector should not include argv[0] or argv[argc] (which is always a null pointer).

The purpose should be a single line string that will be shown in the title of the man page and should not start with an upper-case letter, a hyphen, white space, or the name of the command. E.g., a disassembler tool might specify the purpose as "disassembles a binary specimen".

The description is a full, multi-line description written in the Sawyer markup language where "@" characters have special meaning.

If the tool requires additional switches, an opportunity to adjust the parser, or other special handling, it can call commandLineParser to obtain a parser and then call its parse and apply methods explicitly.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual Sawyer::CommandLine::ParserResult Rose::BinaryAnalysis::Partitioner2::Engine::parseCommandLine ( const std::vector< std::string > &  args,
const std::string &  purpose,
const std::string &  description 
)
virtual

Parse the command-line.

This method parses the command-line and uses it to update this engine's settings. Since a command line is usually more than just engine-related switches, the more usual approach is for the user to obtain engine-related command-line switch declarations and parse the command-line in user code.

This function automatically applies the command-line when it's successfully parsed, thereby updating this engine's settings. If something goes wrong with the command-line then an std::runtime_error is thrown.

The command-line can be provided as a typical argc and argv pair, or as a vector of arguments. In the latter case, the vector should not include argv[0] or argv[argc] (which is always a null pointer).

The purpose should be a single line string that will be shown in the title of the man page and should not start with an upper-case letter, a hyphen, white space, or the name of the command. E.g., a disassembler tool might specify the purpose as "disassembles a binary specimen".

The description is a full, multi-line description written in the Sawyer markup language where "@" characters have special meaning.

If the tool requires additional switches, an opportunity to adjust the parser, or other special handling, it can call commandLineParser to obtain a parser and then call its parse and apply methods explicitly.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual SgAsmInterpretation* Rose::BinaryAnalysis::Partitioner2::Engine::parseContainers ( const std::vector< std::string > &  fileNames)
virtual

Parse specimen binary containers.

Parses the ELF and PE binary containers to create an abstract syntax tree (AST). If fileNames contains names that are recognized as raw data or other non-containers then they are skipped over at this stage but processed during the load stage.

This method tries to allocate a disassember if none is set and an ISA name is specified in the settings, otherwise the disassembler is chosen later. It also resets the interpretation to be the return value (see below), and clears the memory map.

Returns a binary interpretation (perhaps one of many). ELF files have only one interpretation; PE files have a DOS and a PE interpretation and this method will return the PE interpretation. The user may, at this point, select a different interpretation. If the list of names has nothing suitable for ROSE's frontend function (the thing that does the container parsing) then the null pointer is returned.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

SgAsmInterpretation* Rose::BinaryAnalysis::Partitioner2::Engine::parseContainers ( const std::string &  fileName)

Parse specimen binary containers.

Parses the ELF and PE binary containers to create an abstract syntax tree (AST). If fileNames contains names that are recognized as raw data or other non-containers then they are skipped over at this stage but processed during the load stage.

This method tries to allocate a disassember if none is set and an ISA name is specified in the settings, otherwise the disassembler is chosen later. It also resets the interpretation to be the return value (see below), and clears the memory map.

Returns a binary interpretation (perhaps one of many). ELF files have only one interpretation; PE files have a DOS and a PE interpretation and this method will return the PE interpretation. The user may, at this point, select a different interpretation. If the list of names has nothing suitable for ROSE's frontend function (the thing that does the container parsing) then the null pointer is returned.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual MemoryMap::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::loadSpecimens ( const std::vector< std::string > &  fileNames = std::vector< std::string >())
virtual

Load and/or link interpretation.

Loads and/or links the engine's interpretation according to the engine's binary loader with these steps:

  • Clears any existing memory map in the engine.
  • If the binary containers have not been parsed (areContainersParsed returns false, i.e., engine has a null binary interpretation) then parseContainers is called with the same arguments.
  • If binary containers are present but the chosen binary interpretation's memory map is null or empty, then initialize the memory map by calling loadContainers with the same arguments.
  • Continue initializing the memory map by processing all non-container arguments via loadNonContainers.

Returns a reference to the engine's memory map.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

MemoryMap::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::loadSpecimens ( const std::string &  fileName)

Load and/or link interpretation.

Loads and/or links the engine's interpretation according to the engine's binary loader with these steps:

  • Clears any existing memory map in the engine.
  • If the binary containers have not been parsed (areContainersParsed returns false, i.e., engine has a null binary interpretation) then parseContainers is called with the same arguments.
  • If binary containers are present but the chosen binary interpretation's memory map is null or empty, then initialize the memory map by calling loadContainers with the same arguments.
  • Continue initializing the memory map by processing all non-container arguments via loadNonContainers.

Returns a reference to the engine's memory map.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::partition ( const std::vector< std::string > &  fileNames = std::vector< std::string >())
virtual

Partition instructions into basic blocks and functions.

Disassembles and organizes instructions into basic blocks and functions with these steps:

  • If the specimen is not loaded (areSpecimensLoaded) then call loadSpecimens. The no-argument version of this function requires that specimens have already been loaded.

Returns the partitioner that was used and which contains the results.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::partition ( const std::string &  fileName)

Partition instructions into basic blocks and functions.

Disassembles and organizes instructions into basic blocks and functions with these steps:

  • If the specimen is not loaded (areSpecimensLoaded) then call loadSpecimens. The no-argument version of this function requires that specimens have already been loaded.

Returns the partitioner that was used and which contains the results.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

SgAsmBlock* Rose::BinaryAnalysis::Partitioner2::Engine::buildAst ( const std::vector< std::string > &  fileNames = std::vector< std::string >())

Obtain an abstract syntax tree.

Constructs a new abstract syntax tree (AST) from partitioner information with these steps:

  • If the partitioner has not been run yet (according to isPartitioned), then do that now with the same arguments. The zero-argument version invokes the zero-argument partition, which requires that the specimen has already been loaded by loadSpecimens.
  • Call Modules::buildAst to build the AST.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

SgAsmBlock* Rose::BinaryAnalysis::Partitioner2::Engine::buildAst ( const std::string &  fileName)

Obtain an abstract syntax tree.

Constructs a new abstract syntax tree (AST) from partitioner information with these steps:

  • If the partitioner has not been run yet (according to isPartitioned), then do that now with the same arguments. The zero-argument version invokes the zero-argument partition, which requires that the specimen has already been loaded by loadSpecimens.
  • Call Modules::buildAst to build the AST.

If an std::runtime_exception occurs and the exitOnError property is set, then the exception is caught, its text is emitted to the partitioner's fatal error stream, and exit(1) is invoked.

virtual Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Partitioner2::Engine::loaderSwitches ( )
virtual

Command-line switches related to the loader.

virtual Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Partitioner2::Engine::disassemblerSwitches ( )
virtual

Command-line switches related to the disassembler.

virtual Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Partitioner2::Engine::partitionerSwitches ( )
virtual

Command-line switches related to the partitioner.

virtual Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Partitioner2::Engine::engineSwitches ( )
virtual

Command-line switches related to engine behavior.

virtual Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Partitioner2::Engine::astConstructionSwitches ( )
virtual

Command-line switches related to AST construction.

static std::string Rose::BinaryAnalysis::Partitioner2::Engine::specimenNameDocumentation ( )
static

Documentation for specimen names.

virtual Sawyer::CommandLine::Parser Rose::BinaryAnalysis::Partitioner2::Engine::commandLineParser ( const std::string &  purpose,
const std::string &  description 
)
virtual

Creates a command-line parser.

Creates and returns a command-line parser suitable for parsing command-line switches and arguments needed by the disassembler.

The purpose should be a single line string that will be shown in the title of the man page and should not start with an upper-case letter, a hyphen, white space, or the name of the command. E.g., a disassembler tool might specify the purpose as "disassembles a binary specimen".

The description is a full, multi-line description written in the Sawyer markup language where "@" characters have special meaning.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::checkSettings ( )
virtual

Check settings after command-line is processed.

This does some checks and further configuration immediately after processing the command line. It's also called by most of the top-level operations.

If an ISA name is specified in the settings and no disassembler has been set yet, then a disassembler is allocated.

virtual bool Rose::BinaryAnalysis::Partitioner2::Engine::isNonContainer ( const std::string &  )
virtual

Determine whether a specimen name is a non-container.

Certain strings are recognized as special instructions for how to adjust a memory map and are not intended to be passed to ROSE's frontend function. This predicate returns true for such strings.

virtual bool Rose::BinaryAnalysis::Partitioner2::Engine::areContainersParsed ( ) const
virtual

Returns true if containers are parsed.

Specifically, returns true if the engine has a non-null interpretation. If it has a null interpretation then parseContainers might have already been called but no binary containers specified, in which case calling it again with the same file names will have no effect.

virtual bool Rose::BinaryAnalysis::Partitioner2::Engine::areSpecimensLoaded ( ) const
virtual

Returns true if specimens are loaded.

Specifically, returns true if the memory map is non-empty.

virtual BinaryLoader* Rose::BinaryAnalysis::Partitioner2::Engine::obtainLoader ( BinaryLoader hint = NULL)
virtual

Obtain a binary loader.

Find a suitable binary loader by one of the following methods (in this order):

  • If this engine's binaryLoader property is non-null, then return that loader.
  • If a binary container was parsed (areContainersParsed returns true and interpretation is non-null) then a loader is chosen based on the interpretation, and configured to map container sections into memory but not perform any linking or relocation fixups.
  • If a hint is supplied, use it.
  • Fail by throwing an std::runtime_error.

In any case, the binaryLoader property is set to this method's return value.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::loadContainers ( const std::vector< std::string > &  fileNames)
virtual

Loads memory from binary containers.

If the engine has an interpretation whose memory map is missing or empty, then the engine obtains a binary loader via obtainLoader and invokes its load method on the interpretation. It then copies the interpretation's memory map into the engine (if present, or leaves it as is).

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::loadNonContainers ( const std::vector< std::string > &  names)
virtual

Loads memory from non-containers.

Processes each non-container string (as determined by isNonContainer) and modifies the memory map according to the string.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::adjustMemoryMap ( )
virtual

Adjust memory map post-loading.

Make adjustments to the memory map after the specimen is loaded.

MemoryMap::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::memoryMap ( ) const
inline

Property: memory map.

Returns the memory map resulting from the loadSpecimens step. This is a combination of the memory map created by the BinaryLoader (via loadContainers) and stored in the interpretation, and the application of any memory map resources (via loadNonContainers). During partitioning operations the memory map comes from the partitioner itself. See loadSpecimens.

Definition at line 500 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::memoryMap ( const MemoryMap::Ptr m)
inlinevirtual

Property: memory map.

Returns the memory map resulting from the loadSpecimens step. This is a combination of the memory map created by the BinaryLoader (via loadContainers) and stored in the interpretation, and the application of any memory map resources (via loadNonContainers). During partitioning operations the memory map comes from the partitioner itself. See loadSpecimens.

Definition at line 501 of file Engine.h.

virtual Disassembler* Rose::BinaryAnalysis::Partitioner2::Engine::obtainDisassembler ( Disassembler hint = NULL)
virtual

Obtain a disassembler.

Chooses a disassembler based on one of the following (in this order):

  • If this engine's disassembler property is non-null, then return that disassembler.
  • If this engine's ISA name setting is non-empty, then use it to obtain a disassembler.
  • If a hint is supplied, then use it.
  • Fail by throwing an std::runtime_error.

In any case, the disassembler property is set to this method's return value.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::checkCreatePartitionerPrerequisites ( ) const
virtual

Check that we have everything necessary to create a partitioner.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::createBarePartitioner ( )
virtual

Create a bare partitioner.

A bare partitioner, as far as the engine is concerned, is one that has characteristics that are common across all architectures but which is missing all architecture-specific functionality. Using the partitioner's own constructor is not quite the same–that would produce an even more bare partitioner! The engine must have disassembler and memoryMap properties already either assigned explicitly or as the result of earlier steps.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::createGenericPartitioner ( )
virtual

Create a generic partitioner.

A generic partitioner should work for any architecture but is not fine-tuned for any particular architecture. The engine must have disassembler and memoryMap properties assigned already, either explicitly or as the result of earlier steps.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::createTunedPartitioner ( )
virtual

Create a tuned partitioner.

Returns a partitioner that is tuned to operate on a specific instruction set architecture. The engine must have disassembler and memoryMap properties assigned already, either explicitly or as the result of earlier steps.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::createPartitionerFromAst ( SgAsmInterpretation )
virtual

Create a partitioner from an AST.

Partitioner data structures are often more useful and more efficient for analysis than an AST. This method initializes the engine and a new partitioner with information from the AST.

virtual Partitioner Rose::BinaryAnalysis::Partitioner2::Engine::createPartitioner ( )
virtual

Create partitioner.

This is the method usually called to create a new partitioner. The base class just calls createTunedPartitioner.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerInit ( Partitioner )
virtual

Finds interesting things to work on initially.

Seeds the partitioner with addresses and functions where recursive disassembly should begin.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerRecursive ( Partitioner )
virtual

Runs the recursive part of partioning.

This is the long-running guts of the partitioner.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerFinal ( Partitioner )
virtual

Runs the final parts of partitioning.

This does anything necessary after the main part of partitioning is finished. For instance, it might give names to some functions that don't have names yet.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitioner ( Partitioner )
virtual

Partitions instructions into basic blocks and functions.

This method is a wrapper around a number of lower-level partitioning steps that uses the specified interpretation to instantiate functions and then uses the specified partitioner to discover basic blocks and use the CFG to assign basic blocks to functions. It is often overridden by subclasses.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::labelAddresses ( Partitioner )
virtual

Label addresses.

Labels addresses according to symbols, etc. Address labels are used for things like giving an unnamed function a name when it's attached to the partitioner's CFG/AUM.

virtual std::vector<DataBlock::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeConfiguredDataBlocks ( Partitioner ,
const Configuration  
)
virtual

Make data blocks based on configuration.

NOTE: for now, all this does is label the datablock addresses. FIXME[Robb P. Matzke 2015-05-12]

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeConfiguredFunctions ( Partitioner ,
const Configuration  
)
virtual

Make functions based on configuration information.

Uses the supplied function configuration information to make functions.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeEntryFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions at specimen entry addresses.

A function is created at each specimen entry address for all headers in the specified interpretation and adds them to the specified partitioner's CFG/AUM.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeErrorHandlingFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions at error handling addresses.

Makes a function at each error handling address in the specified interpratation and inserts the function into the specified partitioner's CFG/AUM.

Returns the list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeImportFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions at import trampolines.

Makes a function at each import trampoline and inserts them into the specified partitioner's CFG/AUM. An import trampoline is a thunk that branches to a dynamically loaded/linked function. Since ROSE does not necessarily load/link dynamic functions, they often don't appear in the executable. Therefore, this function can be called to create functions from the trampolines and give them the same name as the function they would have called had the link step been performed.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeExportFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions at export addresses.

Makes a function at each address that is indicated as being an exported function, and inserts them into the specified partitioner's CFG/AUM.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeSymbolFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions for symbols.

Makes a function for each function symbol in the various symbol tables under the specified interpretation and inserts them into the specified partitioner's CFG/AUM.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeContainerFunctions ( Partitioner ,
SgAsmInterpretation  
)
virtual

Make functions based on specimen container.

Traverses the specified interpretation parsed from, for example, related ELF or PE containers, and make functions at certain addresses that correspond to specimen entry points, imports and exports, symbol tables, etc. This method only calls many of the other "make*Functions" methods and accumulates their results.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeInterruptVectorFunctions ( Partitioner ,
const AddressInterval vector 
)
virtual

Make functions from an interrupt vector.

Reads the interrupt vector and builds functions for its entries. The functions are inserted into the partitioner's CFG/AUM.

Returns the list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeUserFunctions ( Partitioner ,
const std::vector< rose_addr_t > &   
)
virtual

Make a function at each specified address.

A function is created at each address and is attached to the partitioner's CFG/AUM. Returns a list of such functions, some of which may have existed prior to this call.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::discoverBasicBlocks ( Partitioner )
virtual

Discover as many basic blocks as possible.

Processes the "undiscovered" work list until the list becomes empty. This list is the list of basic block placeholders for which no attempt has been made to discover instructions. This method implements a recursive descent disassembler, although it does not process the control flow edges in any particular order. Subclasses are expected to override this to implement a more directed approach to discovering basic blocks.

virtual Function::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::makeNextDataReferencedFunction ( const Partitioner ,
rose_addr_t &  startVa 
)
virtual

Scan read-only data to find function pointers.

Scans read-only data beginning at the specified address in order to find pointers to code, and makes a new function at when found. The pointer must be word aligned and located in memory that's mapped read-only (not writable and not executable), and it must not point to an unknown instruction or an instruction that overlaps with any instruction that's already in the CFG/AUM.

Returns a pointer to a newly-allocated function that has not yet been attached to the CFG/AUM, or a null pointer if no function was found. In any case, the startVa is updated so it points to the next read-only address to check.

virtual Function::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::makeNextCodeReferencedFunction ( const Partitioner )
virtual

Scan instruction ASTs to function pointers.

Scans each instruction to find pointers to code and makes a new function when found. The pointer must be word aligned and located in memory that's mapped read-only (not writable and not executable), and it most not point to an unknown instruction of an instruction that overlaps with any instruction that's already in the CFG/AUM.

This function requires that the partitioner has been initialized to track instruction ASTs as they are added to and removed from the CFG/AUM.

Returns a pointer to a newly-allocated function that has not yet been attached to the CFG/AUM, or a null pointer if no function was found.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeCalledFunctions ( Partitioner )
virtual

Make functions for function call edges.

Scans the partitioner's CFG to find edges that are marked as function calls and makes a function at each target address that is concrete. The function is added to the specified partitioner's CFG/AUM.

Returns a list of such functions, some of which may have existed prior to this call.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeNextPrologueFunction ( Partitioner ,
rose_addr_t  startVa 
)
virtual

Make function at prologue pattern.

Scans executable memory starting at the specified address and which is not represented in the CFG/AUM and looks for byte patterns and/or instruction patterns that indicate the start of a function. When a pattern is found a function (or multiple functions, depending on the type of matcher) is created and inserted into the specified partitioner's CFG/AUM.

Patterns are found by calling the Partitioner::nextFunctionPrologue method, which most likely invokes a variety of predefined and user-defined callbacks to search for the next pattern.

Returns a vector of non-null function pointers pointer for the newly inserted functions, otherwise returns an empty vector.

virtual std::vector<Function::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::makeFunctionFromInterFunctionCalls ( Partitioner partitioner,
rose_addr_t &  startVa 
)
virtual

Make functions from inter-function calls.

This method scans the unused executable areas between existing functions to look for additional function calls and creates new functions for those calls. It starts the scan at startVa which is updated upon return to be the next address that needs to be scanned. The startVa is never incremented past the end of the address space (i.e., it never wraps back around to zero), so care should be taken to not call this in an infinite loop when the end of the address space is reached.

The scanner tries to discover new basic blocks in the unused portion of the address space. These basic blocks are not allowed to overlap with existing, attached basic blocks, data blocks, or functions since that is an indication that we accidentally disassembled non-code. If the basic block looks like a function call and the target address(es) is not pointing into the middle of an existing basic block, data-block, or function then a new function is created at the target address. The basic blocks which were scanned are not explicitly attached to the partitioner's CFG since we cannot be sure we found their starting address, but they might be later attached by following the control flow from the functions we did discover.

Returns the new function(s) for the first basic block that satisfied the requirements outlined above, and updates startVa to be a greater address which is not part of the basic block that was scanned.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::discoverFunctions ( Partitioner )
virtual

Discover as many functions as possible.

Discover as many functions as possible by discovering as many basic blocks as possible (discoverBasicBlocks), Each time we run out of basic blocks to try, we look for another function prologue pattern at the lowest possible address and then recursively discover more basic blocks. When this procedure is exhausted a call to attachBlocksToFunctions tries to attach each basic block to a function.

virtual std::set<rose_addr_t> Rose::BinaryAnalysis::Partitioner2::Engine::attachDeadCodeToFunction ( Partitioner ,
const Function::Ptr ,
size_t  maxIterations = size_t(-1) 
)
virtual

Attach dead code to function.

Examines the ghost edges for the basic blocks that belong to the specified function in order to discover basic blocks that are not reachable according the CFG, adds placeholders for those basic blocks, and causes the function to own those blocks.

If maxIterations is larger than one then multiple iterations are performed. Between each iteration makeNextBasicBlock is called repeatedly to recursively discover instructions for all pending basic blocks, and then the CFG is traversed to add function-reachable basic blocks to the function. The loop terminates when the maximum number of iterations is reached, or when no more dead code can be found within this function.

Returns the set of newly discovered addresses for unreachable code. These are the ghost edge target addresses discovered at each iteration of the loop and do not include addresses of basic blocks that are reachable from the ghost target blocks.

virtual DataBlock::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::attachPaddingToFunction ( Partitioner ,
const Function::Ptr  
)
virtual

Attach function padding to function.

Examines the memory immediately prior to the specified function's entry address to determine if it is alignment padding. If so, it creates a data block for the padding and adds it to the function.

Returns the padding data block, which might have existed prior to this call. Returns null if the function apparently has no padding.

virtual std::vector<DataBlock::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::attachPaddingToFunctions ( Partitioner )
virtual

Attach padding to all functions.

Invokes attachPaddingToFunction for each known function and returns the set of data blocks that were returned by the individual calls.

virtual size_t Rose::BinaryAnalysis::Partitioner2::Engine::attachAllSurroundedCodeToFunctions ( Partitioner )
virtual

Attach all possible intra-function basic blocks to functions.

This is similar to attachSurroundedCodeToFunctions except it calls that method repeatedly until it cannot do anything more. Between each call it also follows the CFG for the newly discovered blocks to discover as many blocks as possible, creates more functions by looking for function calls, and attaches additional basic blocks to functions by following the CFG for each function.

This method is called automatically by runPartitioner if the intraFunctionCodeSearch property is set.

Returns the sum from all the calls to attachSurroundedCodeToFunctions.

virtual size_t Rose::BinaryAnalysis::Partitioner2::Engine::attachSurroundedCodeToFunctions ( Partitioner )
virtual

Attach intra-function basic blocks to functions.

This method scans the unused address intervals (those addresses that are not represented by the CFG/AUM). For each unused interval, if the interval is immediately surrounded by a single function then a basic block placeholder is created at the beginning of the interval and added to the function.

Returns the number of new placeholders created.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::attachBlocksToFunctions ( Partitioner )
virtual

Attach basic blocks to functions.

Calls Partitioner::discoverFunctionBasicBlocks once for each known function the partitioner's CFG/AUM in a sophomoric attempt to assign existing basic blocks to functions.

virtual std::set<rose_addr_t> Rose::BinaryAnalysis::Partitioner2::Engine::attachDeadCodeToFunctions ( Partitioner ,
size_t  maxIterations = size_t(-1) 
)
virtual

Attach dead code to functions.

Calls attachDeadCodeToFunction once for each function that exists in the specified partitioner's CFG/AUM, passing along maxIterations each time.

Returns the union of the dead code addresses discovered for each function.

virtual std::vector<DataBlock::Ptr> Rose::BinaryAnalysis::Partitioner2::Engine::attachSurroundedDataToFunctions ( Partitioner )
virtual

Attach intra-function data to functions.

Looks for addresses that are not part of the partitioner's CFG/AUM and which are surrounded immediately below and above by the same function and add that address interval as a data block to the surrounding function. Returns the list of such data blocks added.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::updateAnalysisResults ( Partitioner )
virtual

Runs various analysis passes.

Runs each analysis over all functions to ensure that results are cached. This should typically be done after functions are discovered and before the final AST is generated, otherwise the AST will not contain cached results for functions and blocks for which an analysis was not performed.

virtual bool Rose::BinaryAnalysis::Partitioner2::Engine::makeNextCallReturnEdge ( Partitioner ,
boost::logic::tribool  assumeCallReturns 
)
virtual

Insert a call-return edge and discover its basic block.

Inserts a call-return (E_CALL_RETURN) edge for some function call that lacks such an edge and for which the callee may return. The assumeCallReturns parameter determines whether a call-return edge should be added or not for callees whose may-return analysis is indeterminate. If assumeCallReturns is true then an indeterminate callee will have a call-return edge added; if false then no call-return edge is added; if indeterminate then no call-return edge is added at this time but the vertex is saved so it can be reprocessed later.

Returns true if a new call-return edge was added to some call, or false if no such edge could be added. A post condition for a false return is that the pendingCallReturn list is empty.

virtual BasicBlock::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::makeNextBasicBlockFromPlaceholder ( Partitioner )
virtual

Discover basic block at next placeholder.

Discovers a basic block at some arbitrary placeholder. Returns a pointer to the new basic block if a block was discovered, or null if no block is discovered. A postcondition for a null return is that the CFG has no edges coming into the "undiscovered" vertex.

virtual BasicBlock::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::makeNextBasicBlock ( Partitioner )
virtual

Discover a basic block.

Discovers another basic block if possible. A variety of methods will be used to determine where to discover the next basic block:

  • Discover a block at a placeholder by calling makeNextBasicBlockAtPlaceholder
  • Insert a new call-return (E_CALL_RETURN) edge for a function call that may return. Insertion of such an edge may result in a new placeholder for which this method then discovers a basic block. The call-return insertion happens in two passes: the first pass only adds an edge for a callee whose may-return analysis is positive; the second pass relaxes that requirement and inserts an edge for any callee whose may-return is indeterminate (i.e., if ROSE can't prove that a callee never returns then assume it may return).

Returns the basic block that was discovered, or the null pointer if there are no pending undiscovered blocks.

const Settings& Rose::BinaryAnalysis::Partitioner2::Engine::settings ( ) const
inline

Property: All settings.

Returns a reference to the engine settings structures. Alternatively, each setting also has a corresponding engine member function to query or adjust the setting directly.

Definition at line 913 of file Engine.h.

Settings& Rose::BinaryAnalysis::Partitioner2::Engine::settings ( )
inline

Property: All settings.

Returns a reference to the engine settings structures. Alternatively, each setting also has a corresponding engine member function to query or adjust the setting directly.

Definition at line 914 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::exitOnError ( ) const
inline

Property: Error handling.

If an exception occurs during certain high-level functions and this property is set, then the exception is caught, its text is written to a fatal error stream, and exit is called with a non-zero value. Since the error message is more user-friendly and professional looking than the uncaught exception message produced by the C++ runtime, the default is that exceptions are caught. If a tool needs to perform its own error handling, then it should clear this property.

Definition at line 925 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::exitOnError ( bool  b)
inlinevirtual

Property: Error handling.

If an exception occurs during certain high-level functions and this property is set, then the exception is caught, its text is written to a fatal error stream, and exit is called with a non-zero value. Since the error message is more user-friendly and professional looking than the uncaught exception message produced by the C++ runtime, the default is that exceptions are caught. If a tool needs to perform its own error handling, then it should clear this property.

Definition at line 926 of file Engine.h.

Progress::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::progress ( ) const
inline

Property: progress reporting.

The optional object to receive progress reports.

Definition at line 934 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::progress ( const Progress::Ptr progress)
inlinevirtual

Property: progress reporting.

The optional object to receive progress reports.

Definition at line 935 of file Engine.h.

References progress().

Referenced by progress().

SgAsmInterpretation* Rose::BinaryAnalysis::Partitioner2::Engine::interpretation ( ) const
inline

Property: interpretation.

The interpretation which is being analyzed. The interpretation is chosen when an ELF or PE container is parsed, and the user can set it to something else if desired. For instance, parsing a PE file will set the interpretation to PE, but the user can reset it to DOS to disassemble the DOS part of the executable.

Definition at line 945 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::interpretation ( SgAsmInterpretation interp)
inlinevirtual

Property: interpretation.

The interpretation which is being analyzed. The interpretation is chosen when an ELF or PE container is parsed, and the user can set it to something else if desired. For instance, parsing a PE file will set the interpretation to PE, but the user can reset it to DOS to disassemble the DOS part of the executable.

Definition at line 946 of file Engine.h.

BinaryLoader* Rose::BinaryAnalysis::Partitioner2::Engine::binaryLoader ( ) const
inline

Property: binary loader.

The binary loader that maps a binary container's sections into simulated memory and optionally performs dynamic linking and relocation fixups. If none is specified then the engine will choose one based on the container.

Definition at line 955 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::binaryLoader ( BinaryLoader loader)
inlinevirtual

Property: binary loader.

The binary loader that maps a binary container's sections into simulated memory and optionally performs dynamic linking and relocation fixups. If none is specified then the engine will choose one based on the container.

Definition at line 956 of file Engine.h.

size_t Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosThreshold ( ) const
inline

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 969 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosThreshold ( size_t  n)
inlinevirtual

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 970 of file Engine.h.

size_t Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosLeaveAtFront ( ) const
inline

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 971 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosLeaveAtFront ( size_t  n)
inlinevirtual

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 972 of file Engine.h.

size_t Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosLeaveAtBack ( ) const
inline

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 973 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::deExecuteZerosLeaveAtBack ( size_t  n)
inlinevirtual

Property: when to remove execute permission from zero bytes.

This is the number of consecutive zero bytes that must be present before execute permission is removed from this part of the memory map. A value of zero disables this feature. The deExecuteZerosThreshold is the number of consecutive zero bytes that must be found to trigger this alteration, while the deExecuteZerosLeaveAtFront and deExecuteZerosLeaveAtBack narrow each region slightly before removing execute permission.

This action happens after the memoryIsExecutable property is processed.

Definition at line 974 of file Engine.h.

MemoryDataAdjustment Rose::BinaryAnalysis::Partitioner2::Engine::memoryDataAdjustment ( ) const
inline

Property: Global adjustments to memory map data access bits.

This property controls whether the partitioner makes any global adjustments to the memory map. The readable, writable, and initialized bits (see MemoryMap) determine how the partitioner treats memory read operations. Reading from memory that is non-writable is treated as if the memory location holds a constant value; reading from memory that is writable and initialized is treated as if the memory contains a valid initial value that can change during program execution, and reading from memory that is writable and not initialized is treated as if it has no current value.

The default is to use the memory map supplied by the executable or the user without making any changes to these access bits.

Definition at line 989 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::memoryDataAdjustment ( MemoryDataAdjustment  x)
inlinevirtual

Property: Global adjustments to memory map data access bits.

This property controls whether the partitioner makes any global adjustments to the memory map. The readable, writable, and initialized bits (see MemoryMap) determine how the partitioner treats memory read operations. Reading from memory that is non-writable is treated as if the memory location holds a constant value; reading from memory that is writable and initialized is treated as if the memory contains a valid initial value that can change during program execution, and reading from memory that is writable and not initialized is treated as if it has no current value.

The default is to use the memory map supplied by the executable or the user without making any changes to these access bits.

Definition at line 990 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::memoryIsExecutable ( ) const
inline

Property: Global adjustment to executability.

If this property is set, then the engine will remap all memory to be executable. Executability determines whether the partitioner is able to make instructions at that address. The default, false, means that the engine will not globally modify the execute bits in the memory map. This action happens before the deExecuteZeros is processed.

Definition at line 1000 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::memoryIsExecutable ( bool  b)
inlinevirtual

Property: Global adjustment to executability.

If this property is set, then the engine will remap all memory to be executable. Executability determines whether the partitioner is able to make instructions at that address. The default, false, means that the engine will not globally modify the execute bits in the memory map. This action happens before the deExecuteZeros is processed.

Definition at line 1001 of file Engine.h.

Disassembler* Rose::BinaryAnalysis::Partitioner2::Engine::disassembler ( ) const
inline

Property: Disassembler.

This property holds the disassembler to use whenever a new partitioner is created. If null, then the engine will choose a disassembler based on the binary container.

Definition at line 1010 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::disassembler ( Disassembler d)
inlinevirtual

Property: Disassembler.

This property holds the disassembler to use whenever a new partitioner is created. If null, then the engine will choose a disassembler based on the binary container.

Definition at line 1011 of file Engine.h.

const std::string& Rose::BinaryAnalysis::Partitioner2::Engine::isaName ( ) const
inline

Property: Instruction set architecture name.

The instruction set architecture name is used to obtain a disassembler and overrides the disassembler that would otherwise be found by examining the binary container.

Definition at line 1020 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::isaName ( const std::string &  s)
inlinevirtual

Property: Instruction set architecture name.

The instruction set architecture name is used to obtain a disassembler and overrides the disassembler that would otherwise be found by examining the binary container.

Definition at line 1021 of file Engine.h.

const std::vector<rose_addr_t>& Rose::BinaryAnalysis::Partitioner2::Engine::startingVas ( ) const
inline

Property: Starting addresses for disassembly.

This is a list of addresses where functions will be created in addition to those functions discovered by examining the binary container.

Definition at line 1030 of file Engine.h.

std::vector<rose_addr_t>& Rose::BinaryAnalysis::Partitioner2::Engine::startingVas ( )
inline

Property: Starting addresses for disassembly.

This is a list of addresses where functions will be created in addition to those functions discovered by examining the binary container.

Definition at line 1031 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::usingSemantics ( ) const
inline

Property: Whether to use instruction semantics.

If set, then instruction semantics are used to fine tune certain analyses that happen during partitioning, such as determining whether branch conditions are opaque.

Definition at line 1040 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::usingSemantics ( bool  b)
inlinevirtual

Property: Whether to use instruction semantics.

If set, then instruction semantics are used to fine tune certain analyses that happen during partitioning, such as determining whether branch conditions are opaque.

Definition at line 1041 of file Engine.h.

SemanticMemoryParadigm Rose::BinaryAnalysis::Partitioner2::Engine::semanticMemoryParadigm ( ) const
inline

Property: Type of container for semantic memory.

Determines whether Partitioner objects created by this engine will be configured to use list-based or map-based semantic memory states. The list-based states are more precise, but they're also slower.

Definition at line 1050 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::semanticMemoryParadigm ( SemanticMemoryParadigm  p)
inlinevirtual

Property: Type of container for semantic memory.

Determines whether Partitioner objects created by this engine will be configured to use list-based or map-based semantic memory states. The list-based states are more precise, but they're also slower.

Definition at line 1051 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::followingGhostEdges ( ) const
inline

Property: Whether to follow ghost edges.

If set, then "ghost" edges are followed during disassembly. A ghost edge is a control flow edge from a branch instruction where the partitioner has decided according to instruction semantics that the branch cannot be taken at run time. If semantics are disabled then ghost edges are always followed since its not possible to determine whether an edge is a ghost edge.

Definition at line 1062 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::followingGhostEdges ( bool  b)
inlinevirtual

Property: Whether to follow ghost edges.

If set, then "ghost" edges are followed during disassembly. A ghost edge is a control flow edge from a branch instruction where the partitioner has decided according to instruction semantics that the branch cannot be taken at run time. If semantics are disabled then ghost edges are always followed since its not possible to determine whether an edge is a ghost edge.

Definition at line 1063 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::discontiguousBlocks ( ) const
inline

Property: Whether to allow discontiguous basic blocks.

ROSE's definition of a basic block allows two consecutive instructions, A and B, to be arranged in memory such that B does not immediately follow A. Setting this property prevents this and would force A and B to belong to separate basic blocks.

Definition at line 1073 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::discontiguousBlocks ( bool  b)
inlinevirtual

Property: Whether to allow discontiguous basic blocks.

ROSE's definition of a basic block allows two consecutive instructions, A and B, to be arranged in memory such that B does not immediately follow A. Setting this property prevents this and would force A and B to belong to separate basic blocks.

Definition at line 1074 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingFunctionPadding ( ) const
inline

Property: Whether to find function padding.

If set, then the partitioner will look for certain padding bytes appearing before the lowest address of a function and add those bytes to the function as static data.

Definition at line 1083 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingFunctionPadding ( bool  b)
inlinevirtual

Property: Whether to find function padding.

If set, then the partitioner will look for certain padding bytes appearing before the lowest address of a function and add those bytes to the function as static data.

Definition at line 1084 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingThunks ( ) const
inline

Property: Whether to find thunk patterns.

If set, then the partitioner expands the list of function prologue patterns to include common thunk patterns. This setting does not control whether thunk instructions are split into their own functions (see splittingThunks).

Definition at line 1093 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingThunks ( bool  b)
inlinevirtual

Property: Whether to find thunk patterns.

If set, then the partitioner expands the list of function prologue patterns to include common thunk patterns. This setting does not control whether thunk instructions are split into their own functions (see splittingThunks).

Definition at line 1094 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::splittingThunks ( ) const
inline

Property: Whether to split thunk instructions into mini functions.

If set, then functions whose entry instructions match a thunk pattern are split so that those thunk instructions are in their own function.

Definition at line 1103 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::splittingThunks ( bool  b)
inlinevirtual

Property: Whether to split thunk instructions into mini functions.

If set, then functions whose entry instructions match a thunk pattern are split so that those thunk instructions are in their own function.

Definition at line 1104 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingDeadCode ( ) const
inline

Property: Whether to find dead code.

If set, then the partitioner looks for code that is reachable by ghost edges after all other code has been found. This is different than followingGhostEdges in that the former follows those edges immediately.

Definition at line 1113 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingDeadCode ( bool  b)
inlinevirtual

Property: Whether to find dead code.

If set, then the partitioner looks for code that is reachable by ghost edges after all other code has been found. This is different than followingGhostEdges in that the former follows those edges immediately.

Definition at line 1114 of file Engine.h.

rose_addr_t Rose::BinaryAnalysis::Partitioner2::Engine::peScramblerDispatcherVa ( ) const
inline

Property: PE-Scrambler dispatcher address.

If non-zero then the partitioner defeats PE-scrambled binary obfuscation by replacing control flow edges that go through this function with the de-scrambled control flow edge.

Definition at line 1123 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::peScramblerDispatcherVa ( rose_addr_t  va)
inlinevirtual

Property: PE-Scrambler dispatcher address.

If non-zero then the partitioner defeats PE-scrambled binary obfuscation by replacing control flow edges that go through this function with the de-scrambled control flow edge.

Definition at line 1124 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingIntraFunctionCode ( ) const
inline

Property: Whether to find intra-function code.

If set, the partitioner will look for parts of memory that were not disassembled and occur between other parts of the same function, and will attempt to disassemble that missing part and link it into the surrounding function.

Definition at line 1133 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingIntraFunctionCode ( bool  b)
inlinevirtual

Property: Whether to find intra-function code.

If set, the partitioner will look for parts of memory that were not disassembled and occur between other parts of the same function, and will attempt to disassemble that missing part and link it into the surrounding function.

Definition at line 1134 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingIntraFunctionData ( ) const
inline

Property: Whether to find intra-function data.

If set, the partitioner will look for parts of memory that were not disassembled and occur between other parts of the same function, and will treat the missing part as static data belonging to that function.

Definition at line 1143 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingIntraFunctionData ( bool  b)
inlinevirtual

Property: Whether to find intra-function data.

If set, the partitioner will look for parts of memory that were not disassembled and occur between other parts of the same function, and will treat the missing part as static data belonging to that function.

Definition at line 1144 of file Engine.h.

const AddressInterval& Rose::BinaryAnalysis::Partitioner2::Engine::interruptVector ( ) const
inline

Property: Location of machine interrupt vector.

If non-empty, the partitioner will treat the specified area as a machine interrupt vector. The effect of the vector varies by architecture.

Definition at line 1153 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::interruptVector ( const AddressInterval i)
inlinevirtual

Property: Location of machine interrupt vector.

If non-empty, the partitioner will treat the specified area as a machine interrupt vector. The effect of the vector varies by architecture.

Definition at line 1154 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::doingPostAnalysis ( ) const
inline

Property: Whether to perform post-partitioning analysis steps.

If set, then each of the enabled post-partitioning analysis steps are executed. Some of these can be quite expensive, but they can be enabled and disabled individually. Those that are enabled are only run if this property also is set.

Definition at line 1163 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::doingPostAnalysis ( bool  b)
inlinevirtual

Property: Whether to perform post-partitioning analysis steps.

If set, then each of the enabled post-partitioning analysis steps are executed. Some of these can be quite expensive, but they can be enabled and disabled individually. Those that are enabled are only run if this property also is set.

Definition at line 1164 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionMayReturn ( ) const
inline

Property: Whether to run the function may-return analysis.

Determines whether the may-return analysis is run when doingPostAnalysis is true.

Definition at line 1172 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionMayReturn ( bool  b)
inlinevirtual

Property: Whether to run the function may-return analysis.

Determines whether the may-return analysis is run when doingPostAnalysis is true.

Definition at line 1173 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionStackDelta ( ) const
inline

Property: Whether to run the function stack delta analysis.

Determines whether the stack delta analysis is run when doingPostAnalysis is true.

Definition at line 1181 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionStackDelta ( bool  b)
inlinevirtual

Property: Whether to run the function stack delta analysis.

Determines whether the stack delta analysis is run when doingPostAnalysis is true.

Definition at line 1182 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::doingPostCallingConvention ( ) const
inline

Property: Whether to run calling-convention analysis.

Determines whether calling convention analysis is run on each function when doingPostAnalysis is true.

Definition at line 1190 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::doingPostCallingConvention ( bool  b)
inlinevirtual

Property: Whether to run calling-convention analysis.

Determines whether calling convention analysis is run on each function when doingPostAnalysis is true.

Definition at line 1191 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionNoop ( ) const
inline

Property: Whether to run no-op function analysis.

Determines whether function no-op analysis is run on each function when doingPostAnalysis is true. This analysis determines whether a function is effectively a no-op and gives it a name indicative of a no-op if it is one.

Definition at line 1200 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::doingPostFunctionNoop ( bool  b)
inlinevirtual

Property: Whether to run no-op function analysis.

Determines whether function no-op analysis is run on each function when doingPostAnalysis is true. This analysis determines whether a function is effectively a no-op and gives it a name indicative of a no-op if it is one.

Definition at line 1201 of file Engine.h.

FunctionReturnAnalysis Rose::BinaryAnalysis::Partitioner2::Engine::functionReturnAnalysis ( ) const
inline

Property: Whether to run the function may-return analysis.

The caller can decide whether may-return analysis runs, or if it runs whether an indeterminate result should be considered true or false.

Definition at line 1210 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::functionReturnAnalysis ( FunctionReturnAnalysis  x)
inlinevirtual

Property: Whether to run the function may-return analysis.

The caller can decide whether may-return analysis runs, or if it runs whether an indeterminate result should be considered true or false.

Definition at line 1211 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingInterFunctionCalls ( ) const
inline

Property: Whether to search for function calls between exiting functions.

If set, then Engine::makeFunctionFromInterFunctionCalls is invoked, which looks for call-like code between existing functions in order to create new functions at the call target addresses.

Definition at line 1220 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingInterFunctionCalls ( bool  b)
inlinevirtual

Property: Whether to search for function calls between exiting functions.

If set, then Engine::makeFunctionFromInterFunctionCalls is invoked, which looks for call-like code between existing functions in order to create new functions at the call target addresses.

Definition at line 1221 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingDataFunctionPointers ( ) const
inline

Property: Whether to search static data for function pointers.

If this property is set, then the partitioner will scan static data to look for things that might be pointers to functions.

Definition at line 1230 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingDataFunctionPointers ( bool  b)
inlinevirtual

Property: Whether to search static data for function pointers.

If this property is set, then the partitioner will scan static data to look for things that might be pointers to functions.

Definition at line 1231 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::findingCodeFunctionPointers ( ) const
inline

Property: Whether to search existing instructions for function pointers.

If this property is set, then the partitioner scans existing instructions to look for constants that seem to be pointers to functions that haven't been discovered yet.

Definition at line 1240 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::findingCodeFunctionPointers ( bool  b)
inlinevirtual

Property: Whether to search existing instructions for function pointers.

If this property is set, then the partitioner scans existing instructions to look for constants that seem to be pointers to functions that haven't been discovered yet.

Definition at line 1241 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::checkingCallBranch ( ) const
inline

Property: Whether to look for function calls used as branches.

If this property is set, then function call instructions are not automatically assumed to be actual function calls.

Definition at line 1249 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::checkingCallBranch ( bool  b)
inlinevirtual

Property: Whether to look for function calls used as branches.

If this property is set, then function call instructions are not automatically assumed to be actual function calls.

Definition at line 1250 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::basicBlockSemanticsAutoDrop ( ) const
inline

Property: Automatically drop semantics for attached basic blocks.

Basic blocks normally cache their semantic state as they're being discovered so that the state does not need to be recomputed from the beginning of the block each time a new instruction is appended. However, caching this information can consume a large number of symbolic expression nodes which are seldom needed once the basic block is fully discovered. Therefore, setting this property to true will cause a basic block's semantic information to be forgotten as soon as the basic block is attached to the CFG.

See also
Partitioner::basicBlockDropSemantics

Definition at line 1264 of file Engine.h.

void Rose::BinaryAnalysis::Partitioner2::Engine::basicBlockSemanticsAutoDrop ( bool  b)
inline

Property: Automatically drop semantics for attached basic blocks.

Basic blocks normally cache their semantic state as they're being discovered so that the state does not need to be recomputed from the beginning of the block each time a new instruction is appended. However, caching this information can consume a large number of symbolic expression nodes which are seldom needed once the basic block is fully discovered. Therefore, setting this property to true will cause a basic block's semantic information to be forgotten as soon as the basic block is attached to the CFG.

See also
Partitioner::basicBlockDropSemantics

Definition at line 1265 of file Engine.h.

const std::vector<std::string>& Rose::BinaryAnalysis::Partitioner2::Engine::configurationNames ( ) const
inline

Property: Configuration files.

This property holds a list of configuration files or directories.

Definition at line 1273 of file Engine.h.

std::vector<std::string>& Rose::BinaryAnalysis::Partitioner2::Engine::configurationNames ( )
inline

Property: Configuration files.

This property holds a list of configuration files or directories.

Definition at line 1274 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::namingConstants ( ) const
inline

Property: Give names to constants.

If this property is set, then the partitioner calls Modules::nameConstants as part of its final steps.

Definition at line 1282 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::namingConstants ( bool  b)
inlinevirtual

Property: Give names to constants.

If this property is set, then the partitioner calls Modules::nameConstants as part of its final steps.

Definition at line 1283 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::namingStrings ( ) const
inline

Property: Give names to string literal addresses.

If this property is set, then the partitioner calls Modules::nameStrings as part of its final steps.

Definition at line 1291 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::namingStrings ( bool  b)
inlinevirtual

Property: Give names to string literal addresses.

If this property is set, then the partitioner calls Modules::nameStrings as part of its final steps.

Definition at line 1292 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::demangleNames ( ) const
inline

Property: Demangle names.

If this property is set, then names are passed through a demangle step, which generally converts them from a low-level format to a source language format.

Definition at line 1301 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::demangleNames ( bool  b)
inlinevirtual

Property: Demangle names.

If this property is set, then names are passed through a demangle step, which generally converts them from a low-level format to a source language format.

Definition at line 1302 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::astAllowEmptyGlobalBlock ( ) const
inline

Property: Whether to allow empty global block in the AST.

If partitioner has not detected any functions, then it will create an AST containing either a single global block with no children (true) or no global block at all (false).

Definition at line 1311 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::astAllowEmptyGlobalBlock ( bool  b)
inlinevirtual

Property: Whether to allow empty global block in the AST.

If partitioner has not detected any functions, then it will create an AST containing either a single global block with no children (true) or no global block at all (false).

Definition at line 1312 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::astAllowFunctionWithNoBasicBlocks ( ) const
inline

Property: Whether to allow empty functions in the AST.

If a function has no basic blocks then the partitioner will create an AST containing either a function node (SgAsmFunction) with no basic block children (true) or no function node at all (false).

Definition at line 1321 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::astAllowFunctionWithNoBasicBlocks ( bool  b)
inlinevirtual

Property: Whether to allow empty functions in the AST.

If a function has no basic blocks then the partitioner will create an AST containing either a function node (SgAsmFunction) with no basic block children (true) or no function node at all (false).

Definition at line 1324 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::astAllowEmptyBasicBlock ( ) const
inline

Property: Whether to allow empty basic blocks in the AST.

If a basic block has no instructions then the partitioner will create an AST containing either a basic block node (SgAsmNode) with no instruction children (true) or no basic block node at all (false).

Definition at line 1335 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::astAllowEmptyBasicBlock ( bool  b)
inlinevirtual

Property: Whether to allow empty basic blocks in the AST.

If a basic block has no instructions then the partitioner will create an AST containing either a basic block node (SgAsmNode) with no instruction children (true) or no basic block node at all (false).

Definition at line 1336 of file Engine.h.

bool Rose::BinaryAnalysis::Partitioner2::Engine::astCopyAllInstructions ( ) const
inline

Property: Whether to copy instructions when building the AST.

Determines whether each instruction is deep-copied into the AST from the instruction provider (true) or simply referenced (false). Note that because the partitioner allows the same instruction to appear in more than one function, referencing instructions directly in the AST will violate the basic property of a tree: the instruction will be reachable in an AST depth-first traversal more than once although the instruction will have only one arbitrarily chosen basic block as its parent. Turning off the copying makes AST construction faster.

Definition at line 1348 of file Engine.h.

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::astCopyAllInstructions ( bool  b)
inlinevirtual

Property: Whether to copy instructions when building the AST.

Determines whether each instruction is deep-copied into the AST from the instruction provider (true) or simply referenced (false). Note that because the partitioner allows the same instruction to appear in more than one function, referencing instructions directly in the AST will violate the basic property of a tree: the instruction will be reachable in an AST depth-first traversal more than once although the instruction will have only one arbitrarily chosen basic block as its parent. Turning off the copying makes AST construction faster.

Definition at line 1349 of file Engine.h.


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