ROSE  0.11.145.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Rose::BinaryAnalysis::Partitioner2::EngineJvm Class Reference

Description

Engine for Java Virtual Machine (JVM) specimens.

This engine is reponsible for creating a partitioner for a specimen that has byte code for the Java Virtual Machine.

This engine provides an instance static member function that instantiates an engine of this type on the heap and returns a shared-ownership pointer to the instance. Refer to the base class, Partitioner2::Engine, to learn how to instantiate engines from factories.

Definition at line 20 of file EngineJvm.h.

#include <Rose/BinaryAnalysis/Partitioner2/EngineJvm.h>

Inheritance diagram for Rose::BinaryAnalysis::Partitioner2::EngineJvm:
Inheritance graph
[legend]
Collaboration diagram for Rose::BinaryAnalysis::Partitioner2::EngineJvm:
Collaboration graph
[legend]

Classes

class  Exception
 Errors from the engine. More...
 

Public Types

using Ptr = EngineJvmPtr
 Shared ownership pointer. More...
 
- Public Types inherited from Rose::BinaryAnalysis::Partitioner2::Engine
using Ptr = EnginePtr
 Shared ownership pointer. More...
 

Public Member Functions

 EngineJvm ()=delete
 Default constructor. More...
 
 EngineJvm (const EngineJvm &)=delete
 
EngineJvmoperator= (const EngineJvm &)=delete
 
virtual bool matchFactory (const std::vector< std::string > &specimen) const override
 
virtual EnginePtr instanceFromFactory (const Settings &) override
 
virtual std::pair< std::string, std::string > specimenNameDocumentation () override
 
virtual SgAsmBlockfrontend (const std::vector< std::string > &args, const std::string &purpose, const std::string &description) override
 Most basic usage of the partitioner. More...
 
virtual SgAsmInterpretationparseContainers (const std::vector< std::string > &fileNames) override
 Parse specimen binary containers. More...
 
virtual bool isNonContainer (const std::string &) override
 Determine whether a specimen name is a non-container. More...
 
virtual bool areContainersParsed () const override
 Returns true if containers are parsed. More...
 
virtual bool areSpecimensLoaded () const override
 Returns true if specimens are loaded. More...
 
virtual MemoryMapPtr loadSpecimens (const std::vector< std::string > &fileNames=std::vector< std::string >()) override
 Load interpretation. More...
 
rose_addr_t loadClassFile (boost::filesystem::path, SgAsmGenericFileList *, rose_addr_t)
 Load a class file by parsing its contents at the given address. More...
 
rose_addr_t loadSuperClasses (const std::string &, SgAsmGenericFileList *, rose_addr_t)
 Recursively find and load all super classes starting at the given address. More...
 
rose_addr_t loadDiscoverableClasses (SgAsmGenericFileList *, rose_addr_t)
 Load classes discoverable from the file list starting at the given address. More...
 
rose_addr_t loadClass (uint16_t, SgAsmJvmConstantPool *, SgAsmGenericFileList *, rose_addr_t)
 Load class and super class starting at the given address. More...
 
boost::filesystem::path pathToClass (const std::string &)
 Path to the given class. More...
 
void discoverFunctionCalls (SgAsmJvmMethod *, SgAsmJvmConstantPool *, std::map< std::string, rose_addr_t > &)
 Discover function calls (invoke instructions) made from a method. More...
 
virtual PartitionerPtr partition (const std::vector< std::string > &fileNames=std::vector< std::string >()) override
 Partition instructions into basic blocks and functions. More...
 
virtual void checkCreatePartitionerPrerequisites () const override
 Check that we have everything necessary to create a partitioner. More...
 
PartitionerPtr createJvmTunedPartitioner ()
 Create a partitioner for JVM. More...
 
virtual PartitionerPtr createPartitioner () override
 Create partitioner. More...
 
virtual void runPartitionerInit (const PartitionerPtr &) override
 Finds interesting things to work on initially. More...
 
virtual void runPartitionerRecursive (const PartitionerPtr &) override
 Runs the recursive part of partioning. More...
 
virtual void runPartitionerFinal (const PartitionerPtr &) override
 Runs the final parts of partitioning. More...
 
virtual void discoverBasicBlocks (const PartitionerPtr &, const ByteCode::Method *)
 Discover as many basic blocks as possible. More...
 
virtual void discoverFunctions (const PartitionerPtr &, const ByteCode::Class *)
 Discover as many functions as possible. More...
 
virtual SgAsmBlockbuildAst (const std::vector< std::string > &fileNames=std::vector< std::string >()) override
 Obtain an abstract syntax tree. More...
 
const std::string & isaName () const
 Property: Instruction set architecture name. More...
 
virtual void isaName (const std::string &)
 Property: Instruction set architecture name. More...
 
const std::vector< rose_addr_t > & functionStartingVas () const
 Property: Starting addresses for disassembly. More...
 
std::vector< rose_addr_t > & functionStartingVas ()
 Property: Starting addresses for disassembly. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 
- Public Member Functions inherited from Sawyer::SharedFromThis< Engine >
SharedPointer< Engine > sharedFromThis ()
 Create a shared pointer from this. More...
 
SharedPointer< const Engine > sharedFromThis () const
 Create a shared pointer from this. More...
 

Static Public Member Functions

static Ptr instance (const Settings &)
 Allocating constructor with settings. More...
 
static Ptr factory ()
 Allocate a factory. More...
 

Protected Member Functions

 EngineJvm (const Settings &settings)
 
virtual SgProjectroseFrontendReplacement (const std::vector< boost::filesystem::path > &fileNames) override
 
- Protected Member Functions inherited from Rose::BinaryAnalysis::Partitioner2::Engine
 Engine ()=delete
 Default constructor. More...
 
 Engine (const Engine &)=delete
 
Engineoperator= (const Engine &)=delete
 
 Engine (const std::string &name, const Settings &settings)
 Allocating instance constructors are implemented by the non-abstract subclasses. More...
 

Member Typedef Documentation

Shared ownership pointer.

Definition at line 23 of file EngineJvm.h.

Constructor & Destructor Documentation

Rose::BinaryAnalysis::Partitioner2::EngineJvm::EngineJvm ( )
delete

Default constructor.

Constructor is deleted and class noncopyable.

Member Function Documentation

static Ptr Rose::BinaryAnalysis::Partitioner2::EngineJvm::instance ( const Settings )
static

Allocating constructor with settings.

static Ptr Rose::BinaryAnalysis::Partitioner2::EngineJvm::factory ( )
static

Allocate a factory.

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

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 SgAsmInterpretation* Rose::BinaryAnalysis::Partitioner2::EngineJvm::parseContainers ( const std::vector< std::string > &  fileNames)
overridevirtual

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 allocate a disassembler 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 bool Rose::BinaryAnalysis::Partitioner2::EngineJvm::isNonContainer ( const std::string &  )
overridevirtual

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::EngineJvm::areContainersParsed ( ) const
overridevirtual

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::EngineJvm::areSpecimensLoaded ( ) const
overridevirtual

Returns true if specimens are loaded.

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

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

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

rose_addr_t Rose::BinaryAnalysis::Partitioner2::EngineJvm::loadClassFile ( boost::filesystem::path  ,
SgAsmGenericFileList ,
rose_addr_t   
)

Load a class file by parsing its contents at the given address.

Returns the AST node representing the file.

rose_addr_t Rose::BinaryAnalysis::Partitioner2::EngineJvm::loadSuperClasses ( const std::string &  ,
SgAsmGenericFileList ,
rose_addr_t   
)

Recursively find and load all super classes starting at the given address.

Returns the address of the last preloaded class.

rose_addr_t Rose::BinaryAnalysis::Partitioner2::EngineJvm::loadDiscoverableClasses ( SgAsmGenericFileList ,
rose_addr_t   
)

Load classes discoverable from the file list starting at the given address.

Loads all classes and superclasses discovered by examining instructions.

Returns the next available address.

rose_addr_t Rose::BinaryAnalysis::Partitioner2::EngineJvm::loadClass ( uint16_t  ,
SgAsmJvmConstantPool ,
SgAsmGenericFileList ,
rose_addr_t   
)

Load class and super class starting at the given address.

Loads the class and super class from the file header and adds new files to the file list.

Returns the next available address.

boost::filesystem::path Rose::BinaryAnalysis::Partitioner2::EngineJvm::pathToClass ( const std::string &  )

Path to the given class.

Returns the path to the class (may not exist).

void Rose::BinaryAnalysis::Partitioner2::EngineJvm::discoverFunctionCalls ( SgAsmJvmMethod ,
SgAsmJvmConstantPool ,
std::map< std::string, rose_addr_t > &   
)

Discover function calls (invoke instructions) made from a method.

Stores in a map of fully resolved function names to unique virtual addresses.

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

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.
  • Obtain a disassembler by calling obtainDisassembler.
  • 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 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 void Rose::BinaryAnalysis::Partitioner2::EngineJvm::checkCreatePartitionerPrerequisites ( ) const
overridevirtual

Check that we have everything necessary to create a partitioner.

PartitionerPtr Rose::BinaryAnalysis::Partitioner2::EngineJvm::createJvmTunedPartitioner ( )

Create a partitioner for JVM.

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

virtual PartitionerPtr Rose::BinaryAnalysis::Partitioner2::EngineJvm::createPartitioner ( )
overridevirtual

Create partitioner.

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

virtual void Rose::BinaryAnalysis::Partitioner2::EngineJvm::runPartitionerInit ( const PartitionerPtr )
overridevirtual

Finds interesting things to work on initially.

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

virtual void Rose::BinaryAnalysis::Partitioner2::EngineJvm::runPartitionerRecursive ( const PartitionerPtr )
overridevirtual

Runs the recursive part of partioning.

This is the long-running guts of the partitioner.

virtual void Rose::BinaryAnalysis::Partitioner2::EngineJvm::runPartitionerFinal ( const PartitionerPtr )
overridevirtual

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::EngineJvm::discoverBasicBlocks ( const PartitionerPtr ,
const ByteCode::Method  
)
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 void Rose::BinaryAnalysis::Partitioner2::EngineJvm::discoverFunctions ( const PartitionerPtr ,
const ByteCode::Class  
)
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 SgAsmBlock* Rose::BinaryAnalysis::Partitioner2::EngineJvm::buildAst ( const std::vector< std::string > &  fileNames = std::vector< std::string >())
overridevirtual

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.

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.

const std::string& Rose::BinaryAnalysis::Partitioner2::EngineJvm::isaName ( ) const

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.

virtual void Rose::BinaryAnalysis::Partitioner2::EngineJvm::isaName ( const std::string &  )
virtual

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.

const std::vector<rose_addr_t>& Rose::BinaryAnalysis::Partitioner2::EngineJvm::functionStartingVas ( ) const

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.

std::vector<rose_addr_t>& Rose::BinaryAnalysis::Partitioner2::EngineJvm::functionStartingVas ( )

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.


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