Description

Base class for engines driving the partitioner.

The Partitioner2::Engine is an abstract base class whose derived classes implement the algorithms for creating functions, basic blocks, instructions, control flow graphs (CFGs), address usage maps (AUMs), static data blocks, and everything else that can be stored in a Partitioner.

Although subclasses can be instantiated directly, it is often easier to do so through the base class's factory methods. For instance, a tool that operates on various kinds of specimens would want to decide what engine subclass to instantiate based on the types of specimens that are being analyzed. The ROSE library defines a few sublcasses, and the factory mechanism allows external tools to register their own subclasses.

Factories

Using the engine factories is a two-step process: first the subclasses are registered with the ROSE library, then the ROSE library chooses which engine should be instantiated and does so.

A subclass is registered by instantiating a "factory instance" of the subclass and calling registerFactory, which takes shared ownership of the factory instance. Additional member functions such as deregisterFactory and registeredFactories can be used to manipulate the factory list. The engine types that are built into ROSE are registered automatically and appear at the beginning of the list.

To directly instantiate an instance of a subclass without going through the factory mechanism, one calls the static instance method of the subclass. The instance method allocates a new instance in the heap and returns a shared-ownership pointer to the new instance. This is how almost all binary analysis works in ROSE.

On the other hand, to instantiate an engine using the factory method, one calls the Engine::forge static member function. The words "forge" and "factory" both start with "f" as a reminder that they go together in this API. The forge method will scan the list of registered factories from the end toward the beginning and the first factory whose matchFactory predicate returns true will be the type of engine to be used. The engine actually returned is not the registered factory directly, but the result of calling instanceFromFactory on the registered factory.

Command-line parsing

Every engine instance has a settings property. Currently this is shared by all engine types, but in the future we may make this more extensible. Every engine supports ROSE's command-line parsing (Sawyer::CommandLine) to modify its settings from the command-line. There is a chicken-or-egg dilemma with command-line parsing: in order to choose the correct engine type, we need to find the command-line positional arguments that describe the specimen; in order to find the positional arguments, we need to be able to accurately parse the command-line switches; in order to parse the engine-specific command-line switches, we need to know which engine will be used for the parsing.

The solution that ROSE uses isn't perfect, but works well in practice. Each engine type is able to register its command-line switches as a switch group within a command-line parser. As long as the switches don't conflict with each other, or can be disambiguated to not conflict, we're able to parse the command-line switches as the union of all the switches from all known engine types. Switches can be disambiguated by giving each engine type its own switch group name (i.e., optional switch prefix). For example, the JVM engine might use "--[jvm-]foo" while the binary machine engine uses "--[binary-]foo".

In order to choose a matching factory from the list of factories, ROSE constructs a temporary command-line parser that handles the switches from all known engines and binds the parser to the registered factories (i.e., the presence of a switch modifies the settings in the factory instance). ROSE then parses the command-line to find the specimen positional arguments which it uses to choose a factory instance. Once the factory instance is chosen, ROSE instantiates a regular instance from the factory and constructs a new command-line parser with just that engine's switches, and bound to the engine being returned. Later, when the tool parses the command-line for real and applies the parse result, the returned engine's settings are updated.

Although this mechanism for handling engine-specific command-line switches is not perfect, we think it will provide a means by which tools can define their own command-line switches, and other factories besides Partitioner2::Engine can operate in similar ways.

Basic usage

An engine drives the process of building a Partitioner2::Partitioner which is then used as an efficient means of obtaining information that's needed during analysis. Although every engine can operate in a different way, there's a common API that's intended to be quite general. The engine API is divided into abstraction layers. The most abstract layer consists of functions that do the most things in one step, from parsing of command-lines to generation of the Partitioner and/or abstract syntax tree (AST). The next layer of less abstract functions does smaller parts, such as parsing containers like ELF or PE, loading parts of specimen files into memory, finding related specimens like shared libraries, linking specimens together into a common address space, organizing instructions into basic blocks and functions, creating an AST, etc. Finally, at the least level of abstraction, many of the functions are specific enough to be defined only in subclasses.

Here's an example of basic usage of the engine to instantiate and populate a Partitioner that can be used for analysis. First, the tool needs to define the necessary classes, which it can do by including either the top-level "Partitioner2.h" header, or the headers for the individual Partitioner2 types.

#include <rose.h>
#include <Rose/BinaryAnalysis/Partitioner2.h>
using namespace Rose;
namespace P2 = Rose::BinaryAnalysis::Partitioner2;

Most tools, after initializing the ROSE library, will create a command-line parser to parse the tool's own switches.

int main(int argc, char *argv[]) {
    ROSE_INITIALIZE;
    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.";
 
    ToolSettings settings;
    Sawyer::CommandLine::Parser parser = buildSwitchParser(settings);

In order for the tool to choose the correct engine, it needs to be able to find the positional command-line arguments that describe the specimen. The tool could do all its own command-line parsing and adjust the values in a Engine::Settings object which it ultimately copies into an engine instance, or it could use ROSE's command-line parsing mechanism. We'll show the latter since we already started creating such a parser above.

Since we're using ROSE to parse the command-line, we pass the command-line and our partial command-line parser to the forge method like this:

P2::Engine::Ptr engine = P2::Engine::forge(argc, argv, parser);

When the forge call returns, it also adjusts the parser so it knows how to parse the command-line switches that are specific to the returned engine type, and those switches are bound to the settings in that returned engine instance. Thus the tool is now able to parse the command-line, update the settings in the engine, and obtain the positional arguments that describe the specimen.

std::vector<std::string> specimen = parser.parse(argc, argv).apply().unreachedArgs();

Rose::BinaryAnalysis::Partitioner2::Engine::specimen

const std::vector< std::string > & specimen() const

Property: specimen.

Sawyer::CommandLine::ParserResult::apply

const ParserResult & apply() const

Saves parsed values in switch-specified locations.

Sawyer::CommandLine::ParserResult::unreachedArgs

std::vector< std::string > unreachedArgs() const

Returns program arguments that were not reached during parsing.

Sawyer::CommandLine::Parser::parse

ParserResult parse(int argc, char *argv[])

Parse program arguments.

Finally, now that the engine has been obtained, the tool can cause the engine to produce a fully initialized Partitioner, or do any of the other things that an engine is designed to do.

P2::Partitioner::Ptr partitioner = engine.partition(specimen);

On the other hand, if you perform your own command-line parser then you'll have the engine settings and the specimen arguments already parsed, in which case you can create the engine with fewer steps:

int main(int argc, char *argv[]) {
    P2::Engine::Settings settings;
    std::vector<std::string> specimen = parseCommandLine(settings);
    auto engine = P2::Engine::forge(specimen);
    auto partitioner = engine->partition(specimen);

Classes
class	AllButLastArguments
	All but the last N arguments are the specimen. More...

class	AllPositionalArguments
	Return all positional arguments as the specimen. More...

class	BasicBlockFinalizer

class	CodeConstants

class	Exception
	Errors from the engine. More...

class	FirstPositionalArguments
	Up to first N arguments are the specimen. More...

class	GroupedPositionalArguments
	Nth group of arguments are the specimen. More...

class	PositionalArgumentParser
	How to parse positional command-line arguments. More...

struct	Settings
	Settings for the engine. More...

Public Types
using	Ptr = EnginePtr
	Shared ownership pointer.

Public Member Functions
virtual std::list< Sawyer::CommandLine::SwitchGroup >	commandLineSwitches ()
	Command-line switches for a particular engine.

std::list< Sawyer::CommandLine::SwitchGroup >	allCommandLineSwitches ()
	List of command-line switches for all engines.

virtual std::pair< std::string, std::string >	specimenNameDocumentation ()=0
	Documentation about how the specimen is specified.

virtual void	addToParser (Sawyer::CommandLine::Parser &)
	Add switches and sections to command-line parser.

void	addAllToParser (Sawyer::CommandLine::Parser &)
	Add switches and sections to command-line parser.

virtual Sawyer::CommandLine::Parser	commandLineParser (const std::string &purpose, const std::string &description)
	Creates a command-line parser.

virtual bool	matchFactory (const std::vector< std::string > &specimen) const =0
	Predicate for matching a concrete engine factory by settings and specimen.

virtual EnginePtr	instanceFromFactory (const Settings &)=0
	Virtual constructor for factories.

bool	isFactory () const
	Returns true if this object is a factory.

virtual void	reset ()
	Reset the engine to its initial state.

virtual void	savePartitioner (const PartitionerConstPtr &, const boost::filesystem::path &, SerialIo::Format=SerialIo::BINARY)

virtual PartitionerPtr	loadPartitioner (const boost::filesystem::path &, SerialIo::Format=SerialIo::BINARY)

virtual void	checkSettings ()
	Check settings after command-line is processed.

virtual bool	isRbaFile (const std::string &)
	Determine whether a specimen is an RBA file.

virtual bool	isNonContainer (const std::string &)=0
	Determine whether a specimen name is a non-container.

virtual bool	areContainersParsed () const =0
	Returns true if containers are parsed.

virtual bool	areSpecimensLoaded () const
	Returns true if specimens are loaded.

virtual void	adjustMemoryMap ()
	Adjust memory map post-loading.

virtual void	checkCreatePartitionerPrerequisites () const
	Check that we have everything necessary to create a partitioner.

virtual PartitionerPtr	createBarePartitioner ()
	Create a bare partitioner.

virtual PartitionerPtr	createPartitioner ()=0
	Create partitioner.

virtual void	runPartitionerInit (const PartitionerPtr &)=0
	Finds interesting things to work on initially.

virtual void	runPartitionerRecursive (const PartitionerPtr &)=0
	Runs the recursive part of partioning.

virtual void	runPartitionerFinal (const PartitionerPtr &)=0
	Runs the final parts of partitioning.

virtual void	runPartitioner (const PartitionerPtr &)
	Partitions instructions into basic blocks and functions.

virtual void	labelAddresses (const PartitionerPtr &, const Configuration &)
	Label addresses.

virtual std::vector< DataBlockPtr >	makeConfiguredDataBlocks (const PartitionerPtr &, const Configuration &)
	Make data blocks based on configuration.

virtual std::vector< FunctionPtr >	makeConfiguredFunctions (const PartitionerPtr &, const Configuration &)
	Make functions based on configuration information.

virtual void	updateAnalysisResults (const PartitionerPtr &)
	Runs various analysis passes.

Architecture::BaseConstPtr	architecture ()
	Property: Architecture.


SgAsmBlock *	frontend (int argc, char *argv[], const std::string &purpose, const std::string &description)
	Most basic usage of the partitioner.

virtual SgAsmBlock *	frontend (const std::vector< std::string > &args, const std::string &purpose, const std::string &description)=0
	Most basic usage of the partitioner.


Sawyer::CommandLine::ParserResult	parseCommandLine (int argc, char *argv[], const std::string &purpose, const std::string &description)
	Parse the command-line.

virtual Sawyer::CommandLine::ParserResult	parseCommandLine (const std::vector< std::string > &args, const std::string &purpose, const std::string &description)
	Parse the command-line.


virtual SgAsmBlock *	buildAst (const std::vector< std::string > &fileNames=std::vector< std::string >())=0
	Obtain an abstract syntax tree.

SgAsmBlock *	buildAst (const std::string &fileName)
	Obtain an abstract syntax tree.


virtual SgAsmInterpretation *	parseContainers (const std::vector< std::string > &fileNames)=0
	Parse specimen binary containers.

SgAsmInterpretation *	parseContainers (const std::string &fileName)
	Parse specimen binary containers.


virtual MemoryMapPtr	loadSpecimens (const std::vector< std::string > &fileNames=std::vector< std::string >())=0
	Load and/or link interpretation.

MemoryMapPtr	loadSpecimens (const std::string &fileName)
	Load and/or link interpretation.


virtual PartitionerPtr	partition (const std::vector< std::string > &fileNames=std::vector< std::string >())=0
	Partition instructions into basic blocks and functions.

PartitionerPtr	partition (const std::string &fileName)
	Partition instructions into basic blocks and functions.


MemoryMapPtr	memoryMap () const
	Property: memory map.

virtual void	memoryMap (const MemoryMapPtr &)
	Property: memory map.


virtual Architecture::BaseConstPtr	obtainArchitecture ()
	Determine the architecture.

virtual Architecture::BaseConstPtr	obtainArchitecture (const Architecture::BaseConstPtr &hint)
	Determine the architecture.


const std::string &	name () const
	Property: Name.

void	name (const std::string &)
	Property: Name.


const Settings &	settings () const
	Property: All settings.

Settings &	settings ()
	Property: All settings.

void	settings (const Settings &)
	Property: All settings.


BasicBlockWorkList::Ptr	basicBlockWorkList () const
	Property: BasicBlock work list.

void	basicBlockWorkList (const BasicBlockWorkList::Ptr &)
	Property: BasicBlock work list.

CodeConstants::Ptr	codeFunctionPointers () const
	Property: Instruction AST constants.

void	codeFunctionPointers (const CodeConstants::Ptr &)
	Property: BasicBlock work list.


SgAsmInterpretation *	interpretation () const
	Property: interpretation.

virtual void	interpretation (SgAsmInterpretation *)
	Property: interpretation.


ProgressPtr	progress () const
	Property: progress reporting.

virtual void	progress (const ProgressPtr &)
	Property: progress reporting.


const std::vector< std::string > &	specimen () const
	Property: specimen.

virtual void	specimen (const std::vector< std::string > &)
	Property: specimen.

Public Member Functions inherited from Sawyer::SharedObject
	SharedObject ()
	Default constructor.

	SharedObject (const SharedObject &)
	Copy constructor.

virtual	~SharedObject ()
	Virtual destructor.

SharedObject &	operator= (const SharedObject &)
	Assignment.

Public Member Functions inherited from Sawyer::SharedFromThis< Engine >
SharedPointer< Engine >	sharedFromThis ()
	Create a shared pointer from `this`.

SharedPointer< const Engine >	sharedFromThis () const
	Create a shared pointer from `this`.

Static Public Member Functions
static EngineBinaryPtr	instance ()

static std::list< std::pair< std::string, std::string > >	allSpecimenNameDocumentation ()
	Documentation for all specimen specifications.

static void	registerFactory (const EnginePtr &factory)
	Register an engine as a factory.

static bool	deregisterFactory (const EnginePtr &factory)
	Remove a concrete engine factory from the registry.

static std::vector< EnginePtr >	registeredFactories ()
	List of all registered factories.

static void	disassembleForRoseFrontend (SgAsmInterpretation *)


static EnginePtr	forge (const std::vector< std::string > &specimen)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (const std::string &specimen)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (const std::vector< std::string > &arguments, Sawyer::CommandLine::Parser &, const PositionalArgumentParser &, const Settings &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (const std::vector< std::string > &arguments, Sawyer::CommandLine::Parser &, const PositionalArgumentParser &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (const std::vector< std::string > &arguments, Sawyer::CommandLine::Parser &, const Settings &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (const std::vector< std::string > &arguments, Sawyer::CommandLine::Parser &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (int argc, char *argv[], Sawyer::CommandLine::Parser &, const PositionalArgumentParser &, const Settings &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (int argc, char *argv[], Sawyer::CommandLine::Parser &, const PositionalArgumentParser &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (int argc, char *argv[], Sawyer::CommandLine::Parser &, const Settings &)
	Creates a suitable engine based on the specimen.

static EnginePtr	forge (int argc, char *argv[], Sawyer::CommandLine::Parser &)
	Creates a suitable engine based on the specimen.

Protected Member Functions
	Engine ()=delete
	Default constructor.

	Engine (const Engine &)=delete

Engine &	operator= (const Engine &)=delete

	Engine (const std::string &name, const Settings &settings)
	Allocating `instance` constructors are implemented by the non-abstract subclasses.

virtual SgProject *	roseFrontendReplacement (const std::vector< boost::filesystem::path > &fileNames)=0

Member Typedef Documentation

◆ Ptr

using Rose::BinaryAnalysis::Partitioner2::Engine::Ptr = EnginePtr

Shared ownership pointer.

Definition at line 162 of file Partitioner2/Engine.h.

Constructor & Destructor Documentation

◆ Engine()

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

protecteddelete

Default constructor.

Constructor is deleted and class noncopyable.

Member Function Documentation

◆ commandLineSwitches()

virtual std::list< Sawyer::CommandLine::SwitchGroup > Rose::BinaryAnalysis::Partitioner2::Engine::commandLineSwitches ( )

virtual

Command-line switches for a particular engine.

Returns the list of switch groups that declare the command-line switches specific to a particular engine. Since every Engine subclass needs its own particular switches (possibly in addition to the base class switches), this is implemented in each subclass that needs switches. The base class returns a list of switch groups that are applicable to all engines, although the subclasses can refine this list, and the subclass implementations should augment what the base implementation returns.

In order to implement the "--help" switch to show the man page, we need a way to include the switch documentation for all possible engine subclasses at once. Therefore, the returned command line switch groups must have names and prefixes that are unique across all subclasses, and the descriptions should refer to the name of the subclass. For instance, the EngineBinary class, which returns many switch groups, will name the switch groups like "binary-load", "binary-dis", "binary-part", "binary-ast", etc. and will make it clear in each group description that these switches are intended for the binary engine.

See allCommandLineSwitches for details about how the "--help" man page is constructed.

Reimplemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ allCommandLineSwitches()

std::list< Sawyer::CommandLine::SwitchGroup > Rose::BinaryAnalysis::Partitioner2::Engine::allCommandLineSwitches ( )

List of command-line switches for all engines.

This function is used to construct the man page for a tool. It invokes commandLineSwitches for the base class and every registered subclass in the opposite order they were registered (i.e., the same order they're matched). It then traverses the list and removes any group that has the same name or prefix as an earlier group. The final list is returned.

◆ specimenNameDocumentation()

virtual std::pair< std::string, std::string > Rose::BinaryAnalysis::Partitioner2::Engine::specimenNameDocumentation ( )

pure virtual

Documentation about how the specimen is specified.

The documentation string that's returned is expected to be used in a command-line parser description and thus may contain special formatting constructs. For most engine subclasses, this will be a description of those command-line positional arguments that describe the specimen. For instance, the EngineJvm subclass would probably document that the specimen consists of one or more file names ending with the string ".class".

In order to support the –help switch that generates the man page, it must be possible to include the documentation for all subclasses concurrently. Therefore, each subclass returns both a section title and the section documentation string. The section title and documentation string should make it clear that this part of the documentation applies only to that particular subclass.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ allSpecimenNameDocumentation()

static std::list< std::pair< std::string, std::string > > Rose::BinaryAnalysis::Partitioner2::Engine::allSpecimenNameDocumentation ( )

static

Documentation for all specimen specifications.

This function calls the specimenNameDocumentation for all registered subclasses in the reverse order their factories were registered, which is the same order they're matched. It then combines (and warns) documentation that has the same title and returns the (possibly modified) list. The list consists of pairs where the first of each pair is the unique section title and the second is the documentation tht goes into that section.

◆ addToParser()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::addToParser ( Sawyer::CommandLine::Parser & )

virtual

Add switches and sections to command-line parser.

The switches and special documentation sections for the particular parser are added to the specified command-line parser.

Note that if you intend to create a parser that recognizes more than one engine type, it is better to use addAllToParser since that function is better for this purpose. If you want to include only a few engines, consider clearing the engine factory list and replacing it with only those you want before calling addAllToParser.

◆ addAllToParser()

void Rose::BinaryAnalysis::Partitioner2::Engine::addAllToParser ( Sawyer::CommandLine::Parser & )

Add switches and sections to command-line parser.

This function adds switch groups and descriptions for all available engine subclases, thus producing a parser that's suitable for generating a man page. It uses allCommandLineSwitches and allSpecimenNameDocumentation to acheive this goal.

◆ commandLineParser()

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

virtual

Creates a command-line parser.

This creates and returns a command-line parser that contains the switch groups and documentation sections for all registered engines. No other switches are included in the parser, particularly the switches defined by Rose::CommandLine::genericSwitches.

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.

◆ registerFactory()

static void Rose::BinaryAnalysis::Partitioner2::Engine::registerFactory ( const EnginePtr & factory )

static

Register an engine as a factory.

The specified engine is added to the end of a list of engine prototypical factory objects. When a new engine is needed, this list is scanned in reverse order until one of the matchFactory predicates for the prototypical object returns true, at which time a new copy of that object is created by passing the lookup arguments to its virtual instanceFromFactory constructor.

Thread safety: This method is thread safe.

◆ deregisterFactory()

static bool Rose::BinaryAnalysis::Partitioner2::Engine::deregisterFactory ( const EnginePtr & factory )

static

Remove a concrete engine factory from the registry.

The last occurrence of the specified factory is removed from the list of registered factories. This function returns true if a factory was removed, and false if no registered factories match.

Thread safety: This method is thread safe.

◆ registeredFactories()

static std::vector< EnginePtr > Rose::BinaryAnalysis::Partitioner2::Engine::registeredFactories ( )

static

List of all registered factories.

The returned list contains the registered factories in the order they were registereed, which is the reverse order of how they're searched.

Thread safety: This method is thread safe.

◆ forge() [1/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge ( const std::vector< std::string > & specimen )

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [2/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge ( const std::string & specimen )

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [3/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	const std::vector< std::string > &	arguments,
		Sawyer::CommandLine::Parser &	,
		const PositionalArgumentParser &	,
		const Settings &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [4/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	const std::vector< std::string > &	arguments,
		Sawyer::CommandLine::Parser &	,
		const PositionalArgumentParser &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [5/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	const std::vector< std::string > &	arguments,
		Sawyer::CommandLine::Parser &	,
		const Settings &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [6/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	const std::vector< std::string > &	arguments,
		Sawyer::CommandLine::Parser &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [7/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	int	argc,
		char *	argv[],
		Sawyer::CommandLine::Parser &	,
		const PositionalArgumentParser &	,
		const Settings &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [8/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	int	argc,
		char *	argv[],
		Sawyer::CommandLine::Parser &	,
		const PositionalArgumentParser &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [9/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	int	argc,
		char *	argv[],
		Sawyer::CommandLine::Parser &	,
		const Settings &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ forge() [10/10]

static EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::forge	(	int	argc,
		char *	argv[],
		Sawyer::CommandLine::Parser &
	)

static

Creates a suitable engine based on the specimen.

Scans the registeredFactories list in the reverse order looking for a factory whose matchFactory predicate returns true. The first factory whose predicate returns true is used to create and return a new concrete engine object by invoking the factory's virtual instanceFromFactory constructor with the first argument of this function.

The version that takes a string or vector of strings, the "specimen", returns a new engine from the first factory that says it can handle those strings. For instance, if the EngineJvm can handle a specimen whose name is a class file having the extension ".class".

The versions that takes a command-line switch parser and a an optional command-line positional argument parser attempts to parse the command-line to obtain the specimen, which is then passed to the version that takes a specimen. The incoming parser should not have definitions for switches that adjust the engine settings–they will be added automatically to the parser before returning. The returned parser will be augmented with switches for all engines so that "--help" and friends work propertly, however only the switches applicable to the returned engine will be linked to the returned engine (switches for other engine types are linked to their respective factories as a holding area, although they're never used for anything).

If settings are specified, then they are the defaults to be adjusted by the command-line parser. These defaults will also show up in the man page.

Thread safety: This method is thread safe.

◆ matchFactory()

virtual bool Rose::BinaryAnalysis::Partitioner2::Engine::matchFactory ( const std::vector< std::string > & specimen ) const

pure virtual

Predicate for matching a concrete engine factory by settings and specimen.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ instanceFromFactory()

virtual EnginePtr Rose::BinaryAnalysis::Partitioner2::Engine::instanceFromFactory ( const Settings & )

pure virtual

Virtual constructor for factories.

This creates a new object by calling the class method instance for the class of which this is a type. All arguments are passed to instance.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ isFactory()

bool Rose::BinaryAnalysis::Partitioner2::Engine::isFactory ( ) const

Returns true if this object is a factory.

Factories are created by the factory class methods rather than the usual instance class methods. A factory object should only be used to create other (non-factory) objects by registering it as a factory and eventually calling (directly or indirectly) its instanceFromFactory object method.

◆ frontend() [1/2]

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 EngineSettings::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.

◆ frontend() [2/2]

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

pure 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 EngineSettings::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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, Rose::BinaryAnalysis::Partitioner2::EngineJvm, and Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ reset()

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

virtual

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, 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.

Reimplemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ parseCommandLine() [1/2]

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 EngineSettings::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.

◆ parseCommandLine() [2/2]

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 EngineSettings::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.

◆ buildAst() [1/2]

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

pure virtual

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, 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 EngineSettings::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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, Rose::BinaryAnalysis::Partitioner2::EngineJvm, and Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ buildAst() [2/2]

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, 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 EngineSettings::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.

◆ parseContainers() [1/2]

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

pure 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 loadSpecimens stage.

This method tries to determine the specimen architecture. 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 EngineSettings::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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, Rose::BinaryAnalysis::Partitioner2::EngineJvm, and Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ parseContainers() [2/2]

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 loadSpecimens stage.

This method tries to determine the specimen architecture. 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 EngineSettings::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.

◆ loadSpecimens() [1/2]

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

pure 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.

Continue initializing the memory map by processing all non-container arguments.

Returns a reference to the engine's memory map.

If an std::runtime_exception occurs and the EngineSettings::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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, Rose::BinaryAnalysis::Partitioner2::EngineJvm, and Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ loadSpecimens() [2/2]

MemoryMapPtr 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.

Continue initializing the memory map by processing all non-container arguments.

Returns a reference to the engine's memory map.

If an std::runtime_exception occurs and the EngineSettings::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.

◆ partition() [1/2]

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

pure 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.

Determine the architecture for the specimen by calling obtainArchitecture.

Create a partitioner by calling createPartitioner.

Run the partitioner by calling runPartitioner.

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

If an std::runtime_exception occurs and the EngineSettings::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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, Rose::BinaryAnalysis::Partitioner2::EngineJvm, and Rose::BinaryAnalysis::Partitioner2::EngineBinary.

◆ partition() [2/2]

PartitionerPtr 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.

Determine the architecture for the specimen by calling obtainArchitecture.

Create a partitioner by calling createPartitioner.

Run the partitioner by calling runPartitioner.

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

If an std::runtime_exception occurs and the EngineSettings::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.

◆ checkSettings()

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 architecture has been set yet, then an architecture is chosen.

◆ isRbaFile()

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

virtual

Determine whether a specimen is an RBA file.

Returns true if the name looks like a ROSE Binary Analysis file. Such files are not intended to be passed to ROSE's global frontend function but may be passed to this Engine's Engine::frontend method.

◆ isNonContainer()

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

pure 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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ areContainersParsed()

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

pure 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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ areSpecimensLoaded()

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.

Reimplemented in Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ adjustMemoryMap()

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() [1/2]

MemoryMapPtr Rose::BinaryAnalysis::Partitioner2::Engine::memoryMap ( ) const

Property: memory map.

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

◆ memoryMap() [2/2]

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::memoryMap ( const MemoryMapPtr & )

virtual

Property: memory map.

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

◆ obtainArchitecture() [1/2]

virtual Architecture::BaseConstPtr Rose::BinaryAnalysis::Partitioner2::Engine::obtainArchitecture ( )

virtual

Determine the architecture.

Chooses an architecture based on one of the following (in this order):

If this engine's architecture property is non-null, then return that architecture.

If this engine's ISA name setting is non-empty, then use an architecture that handles that name.

If a binary container was parsed (areContainersParsed returns true and interpretation is non-null) then try to choose an architecture based on the interpretation.

If a hint is supplied, then use it.

Fail by throwing a Architecture::NotFound error.

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

◆ obtainArchitecture() [2/2]

virtual Architecture::BaseConstPtr Rose::BinaryAnalysis::Partitioner2::Engine::obtainArchitecture ( const Architecture::BaseConstPtr & hint )

virtual

Determine the architecture.

Chooses an architecture based on one of the following (in this order):

If this engine's architecture property is non-null, then return that architecture.

If this engine's ISA name setting is non-empty, then use an architecture that handles that name.

If a binary container was parsed (areContainersParsed returns true and interpretation is non-null) then try to choose an architecture based on the interpretation.

If a hint is supplied, then use it.

Fail by throwing a Architecture::NotFound error.

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

◆ checkCreatePartitionerPrerequisites()

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

virtual

Check that we have everything necessary to create a partitioner.

Reimplemented in Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ createBarePartitioner()

virtual PartitionerPtr 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!

◆ createPartitioner()

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

pure virtual

Create partitioner.

This is the method usually called to create a new partitioner.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ runPartitionerInit()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerInit ( const PartitionerPtr & )

pure virtual

Finds interesting things to work on initially.

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

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ runPartitionerRecursive()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerRecursive ( const PartitionerPtr & )

pure virtual

Runs the recursive part of partioning.

This is the long-running guts of the partitioner.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ runPartitionerFinal()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitionerFinal ( const PartitionerPtr & )

pure 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.

Implemented in Rose::BinaryAnalysis::Partitioner2::EngineBinary, and Rose::BinaryAnalysis::Partitioner2::EngineJvm.

◆ runPartitioner()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::runPartitioner ( const PartitionerPtr & )

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.

◆ labelAddresses()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::labelAddresses	(	const PartitionerPtr &	,
		const Configuration &
	)

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.

◆ makeConfiguredDataBlocks()

virtual std::vector< DataBlockPtr > Rose::BinaryAnalysis::Partitioner2::Engine::makeConfiguredDataBlocks	(	const PartitionerPtr &	,
		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]

◆ makeConfiguredFunctions()

virtual std::vector< FunctionPtr > Rose::BinaryAnalysis::Partitioner2::Engine::makeConfiguredFunctions	(	const PartitionerPtr &	,
		const Configuration &
	)

virtual

Make functions based on configuration information.

Uses the supplied function configuration information to make functions.

◆ updateAnalysisResults()

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::updateAnalysisResults ( const PartitionerPtr & )

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.

◆ name() [1/2]

const std::string & Rose::BinaryAnalysis::Partitioner2::Engine::name ( ) const

Property: Name.

The name of the engine comes from the engine factory, will be empty if not a factory.

◆ name() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Engine::name ( const std::string & )

Property: Name.

The name of the engine comes from the engine factory, will be empty if not a factory.

◆ architecture()

Architecture::BaseConstPtr Rose::BinaryAnalysis::Partitioner2::Engine::architecture ( )

Property: Architecture.

The non-null object representing architecture-specific information is returned, or an Architecture::NotFound exception is thrown if there is no architecture and none can be determined.

◆ settings() [1/3]

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

Property: All settings.

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

◆ settings() [2/3]

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

Property: All settings.

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

◆ settings() [3/3]

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

Property: All settings.

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

◆ basicBlockWorkList() [1/2]

BasicBlockWorkList::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::basicBlockWorkList ( ) const

Property: BasicBlock work list.

This property holds the list of what blocks to work on next.

◆ basicBlockWorkList() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Engine::basicBlockWorkList ( const BasicBlockWorkList::Ptr & )

Property: BasicBlock work list.

This property holds the list of what blocks to work on next.

◆ codeFunctionPointers() [1/2]

CodeConstants::Ptr Rose::BinaryAnalysis::Partitioner2::Engine::codeFunctionPointers ( ) const

Property: Instruction AST constants.

This property holds constants that are found in instruction ASTs.

◆ codeFunctionPointers() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Engine::codeFunctionPointers ( const CodeConstants::Ptr & )

Property: BasicBlock work list.

This property holds the list of what blocks to work on next.

◆ interpretation() [1/2]

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

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.

◆ interpretation() [2/2]

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::interpretation ( SgAsmInterpretation * )

virtual

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.

◆ progress() [1/2]

ProgressPtr Rose::BinaryAnalysis::Partitioner2::Engine::progress ( ) const

Property: progress reporting.

The optional object to receive progress reports.

◆ progress() [2/2]

virtual void Rose::BinaryAnalysis::Partitioner2::Engine::progress ( const ProgressPtr & )

virtual

Property: progress reporting.

The optional object to receive progress reports.

◆ specimen() [1/2]

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

Property: specimen.

The specimen is a list of additional command line arguments. It is often a list of file names.

◆ specimen() [2/2]

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

virtual

Property: specimen.

The specimen is a list of additional command line arguments. It is often a list of file names.

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

Partitioner2/Engine.h

Description

Factories

Command-line parsing

Basic usage

See also

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Typedef Documentation

◆ Ptr

Constructor & Destructor Documentation

◆ Engine()

Member Function Documentation

◆ commandLineSwitches()

◆ allCommandLineSwitches()

◆ specimenNameDocumentation()

◆ allSpecimenNameDocumentation()

◆ addToParser()

◆ addAllToParser()

◆ commandLineParser()

◆ registerFactory()

◆ deregisterFactory()

◆ registeredFactories()

◆ forge() [1/10]

◆ forge() [2/10]

◆ forge() [3/10]

◆ forge() [4/10]

◆ forge() [5/10]

◆ forge() [6/10]

◆ forge() [7/10]

◆ forge() [8/10]

◆ forge() [9/10]

◆ forge() [10/10]

◆ matchFactory()

◆ instanceFromFactory()

◆ isFactory()

◆ frontend() [1/2]

◆ frontend() [2/2]

◆ reset()

◆ parseCommandLine() [1/2]

◆ parseCommandLine() [2/2]

◆ buildAst() [1/2]

◆ buildAst() [2/2]

◆ parseContainers() [1/2]

◆ parseContainers() [2/2]

◆ loadSpecimens() [1/2]

◆ loadSpecimens() [2/2]

◆ partition() [1/2]

◆ partition() [2/2]

◆ checkSettings()

◆ isRbaFile()

◆ isNonContainer()

◆ areContainersParsed()

◆ areSpecimensLoaded()

◆ adjustMemoryMap()

◆ memoryMap() [1/2]

◆ memoryMap() [2/2]

◆ obtainArchitecture() [1/2]

◆ obtainArchitecture() [2/2]

◆ checkCreatePartitionerPrerequisites()

◆ createBarePartitioner()

◆ createPartitioner()

◆ runPartitionerInit()

◆ runPartitionerRecursive()

◆ runPartitionerFinal()

◆ runPartitioner()

◆ labelAddresses()

◆ makeConfiguredDataBlocks()

◆ makeConfiguredFunctions()

◆ updateAnalysisResults()

◆ name() [1/2]

◆ name() [2/2]

◆ architecture()

◆ settings() [1/3]

◆ settings() [2/3]

◆ settings() [3/3]

◆ basicBlockWorkList() [1/2]

◆ basicBlockWorkList() [2/2]