Description

Architecture-specific information and algorithms.

The main feature of this namespace is a class hierarchy rooted at the Rose::BinaryAnalysis::Architecture::Base class. The hierarchy's leaf subclases contain information and algorithms specific to particular processor architectures such as "Intel Pentium4", and "NXP Coldfire", while its non-leaf subclasses contain information and algorithms specific to a family of architectures such as "Intel X86" and "Motorola". The base class provides an architecture-independent API that can be used throughout the rest of the ROSE library, ROSE tools, and user-created tools, and the subclasses implement that API in architecture-specific ways.

ROSE has a number of built-in architectures, and additional architectures can be registered at runtime by allocating an architecture object in the heap and providing a shared-ownership pointer to an architecture registration function in the ROSE library. There are two ways to register a new architecture:

If the architecture is intended to be part of the ROSE library, then it should be compiled when the ROSE library is compiled, and linked in as part of the ROSE library. These are called the "built-in" architecture definitions and are registered by modifying the initRegistryHelper function in Rose::BinaryAnalysis::Architecture in the "BasicTypes.C" source file.

If the architecture is not intended to be part of the ROSE library, then it should be compiled into its own shared library and provided to binary analysis tools at runtime. These are called "external" architecture definitions. Most tools have a "--architectures" switch that can load the shared library (see Rose::CommandLine::genericSwitches). Each such library should have a registerArchitectures function with C linkage, and this function should create architecture objects and register them by calling Rose::BinaryAnalysis::Architecture::registerDefinition.

Many of the main analysis objects in ROSE (instruction decoders, instruction dispatchers, partitioner results, assembly unparsers, etc.) have pointers to an architecture. Additionally, the architecture definition registry can look up an architecture by various mechanisms, such as by name, by file header, or by finding the best architecture for a binary interpretation. See the functions in this namespace for more information about the registry.

The ROSE tools come with an example of an external architecture definition called "simple" defined in the "SimpleArch.C" file. The build system builds a "libSimpleArch.so" shared library and a test case runs various ROSE tools by providing that shared library at runtime.

Changes from previous versions

The introduction of this namespace in December 2023 to support user-defined instruction sets necessitated a number of minor changes but also one major change.

The major change is that instead of defining architecture-specific behavior in the subclasses of SgAsmInstruction, they're now defined in the subclasses of Rose::BinaryAnalysis::Architecture::Base. This means that the most of the SgAsmInstruction member functions have moved to Rose::BinaryAnalysis::Architecture::Base and take an SgAsmInstruction pointer as their first argument. This rearrangement makes it possible for all external architecture definitions to share a single AST instruction type, SgAsmUserInstruction. We hope that ROSE's ability to describe instruction operands is sufficiently general that it can be used as-is.

A somewhat major change is that Rose::BinaryAnalysis::Disassembler::Base is no longer the go-to class for obtaining information about an architecture (other than it has an architecture property). Instead of asking a disassembler for a register dictionary, a special register (such as a stack pointer), an instruction dispatcher (for semantics), or an assembly unparser, one asks the architecture. In most situation an architecture is readily available since all the main objects have a architecture property that holds a non-null pointer (even SgAsmInstruction).

The other changes are relatively minor and shouldn't cause many problems. For instance, instruction decoders are no longer registered individually and looked up at runtime by name. Instead, the architecture is looked up and a decoder is obtained from the architecture.

Classes
class	Amd64
	Architecture-specific information for x86-64, x86_64, x64, amd64, Intel 64. More...

class	Base
	Base class for architecture definitions. More...

class	Cil
	Architecture-specific information for the Common Intermediate Language. More...

class	Exception
	Base class for exceptions thrown by architecture definitions. More...

class	Intel80286
	Architecture specific information for Intel 80286. More...

class	Intel8086
	Architecture-specific information for Intel 8086. More...

class	Intel8088
	Architecture-specific information for Intel 8088. More...

class	IntelI386
	Architecture-specific information for Intel i386. More...

class	IntelI486
	Architecture-specific information for Intel i486. More...

class	IntelPentium
	Architecture-specific information for Intel Pentium. More...

class	IntelPentium4
	Architecture-specific information for Intel Pentium4. More...

class	IntelPentiumii
	Architecture-specific information for Intel Pentium II. More...

class	IntelPentiumiii
	Architecture-specific information for Intel Pentium III. More...

class	Jvm
	Architecture-specific information for the Java virtual machine. More...

class	Mips32
	Architecture-specific information for MIPS with 32-bit word size. More...

class	Motorola
	Base class for Motorola processors. More...

class	Motorola68040
	Architecture-specific information for Motorola 68040'. More...

class	NotFound
	Error when an architecture is not found. More...

class	NxpColdfire
	Architecture-specific information for NXP ColdFire'. More...

class	Powerpc
	Base class for PowerPC architectures. More...

class	Powerpc32
	Architecture-specific information for PowerPC with 32-bit word size. More...

class	Powerpc64
	Architecture-specific information for PowerPC with 64-bit word size. More...

class	X86
	Common base class for all x86 architectures. More...

Typedefs
using	Amd64Ptr = std::shared_ptr< Amd64 >
	Reference counted pointer for Amd64.

using	ArmAarch32Ptr = std::shared_ptr< ArmAarch32 >
	Reference counted pointer for ArmAarch32.

using	ArmAarch64Ptr = std::shared_ptr< ArmAarch64 >
	Reference counted pointer for ArmAarch64.

using	BasePtr = std::shared_ptr< Base >
	Reference counted pointer for Architecture::Base.

using	BaseConstPtr = std::shared_ptr< const Base >
	Reference counted pointer for Architecture::Base.

using	CilPtr = std::shared_ptr< Cil >
	Reference counted pointer for Cil.

using	Intel80286Ptr = std::shared_ptr< Intel80286 >
	Reference counted pointer for Intel80286.

using	Intel8086Ptr = std::shared_ptr< Intel8086 >
	Reference counted pointer for Intel8086.

using	Intel8088Ptr = std::shared_ptr< Intel8088 >
	Reference counted pointer for Intel8088.

using	IntelI386Ptr = std::shared_ptr< IntelI386 >
	Reference counted pointer for IntelI386.

using	IntelI486Ptr = std::shared_ptr< IntelI486 >
	Reference counted pointer for IntelI486.

using	IntelPentiumPtr = std::shared_ptr< IntelPentium >
	Reference counted pointer for IntelPentium.

using	IntelPentiumiiPtr = std::shared_ptr< IntelPentiumii >
	Reference counted pointer for IntelPentiumii.

using	IntelPentiumiiiPtr = std::shared_ptr< IntelPentiumiii >
	Reference counted pointer for IntelPentiumiii.

using	IntelPentium4Ptr = std::shared_ptr< IntelPentium4 >
	Reference counted pointer for IntelPentium4.

using	JvmPtr = std::shared_ptr< Jvm >
	Reference counted pointer for Jvm.

using	Mips32Ptr = std::shared_ptr< Mips32 >
	Reference counted pointer for Mips32.

using	MotorolaPtr = std::shared_ptr< Motorola >
	Reference counted pointer for Motorola.

using	Motorola68040Ptr = std::shared_ptr< Motorola68040 >
	Reference counted pointer for Motorola68040.

using	NxpColdfirePtr = std::shared_ptr< NxpColdfire >
	Reference counted pointer for NxpColdfire.

using	PowerpcPtr = std::shared_ptr< Powerpc >
	Reference counted pointer for Powerpc.

using	Powerpc32Ptr = std::shared_ptr< Powerpc32 >
	Reference counted pointer for Powerpc32.

using	Powerpc64Ptr = std::shared_ptr< Powerpc64 >
	Reference counted pointer for Powerpc64.

using	X86Ptr = std::shared_ptr< X86 >
	Reference counted pointer for X86.

Functions
void	initDiagnostics ()
	Initialize and registers architecture diagnostic streams.

size_t	registerDefinition (const BasePtr &)
	Register a new architecture definition.

void	registerDefinition (const std::string &)
	Register definitions from a shared library.

template<class Iterator >
void	registerDefinitions (Iterator begin, Iterator end)
	Register definitions from shared libraries.

bool	deregisterDefinition (const BasePtr &)
	Remove the specified architecture from the list of registered architectures.

std::vector< BasePtr >	registeredDefinitions ()
	Registered architectures.

std::set< std::string >	registeredNames ()
	Names of all registered architectures.

Sawyer::Result< BasePtr, NotFound >	findByName (const std::string &)
	Look up a new architecture by name.

Sawyer::Result< BasePtr, NotFound >	findById (size_t)
	Look up a new architecture by registration ID.

Sawyer::Result< BasePtr, NotFound >	findByHeader (SgAsmGenericHeader *)
	Finds a suitable architecture for a file header.

Sawyer::Result< BasePtr, NotFound >	findByInterpretation (SgAsmInterpretation *)
	Finds a suitable architecture for a binary interpretation.

std::pair< BasePtr, size_t >	findBestByInterpretation (SgAsmInterpretation *)
	Finds the architecture that matches the most file headers.

InstructionSemantics::BaseSemantics::DispatcherPtr	newInstructionDispatcher (const std::string &name, const InstructionSemantics::BaseSemantics::RiscOperatorsPtr &)
	Create a new instruction dispatcher by name.


const std::string &	name (const BaseConstPtr &)
	Architecture name free function.

const std::string &	name (size_t registrationId)
	Architecture name free function.

Variables
Sawyer::Message::Facility	mlog
	Diagnostic facility for architecture definitions.

Typedef Documentation

◆ Amd64Ptr

using Rose::BinaryAnalysis::Architecture::Amd64Ptr = typedef std::shared_ptr<Amd64>

Reference counted pointer for Amd64.

Definition at line 31 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ ArmAarch32Ptr

using Rose::BinaryAnalysis::Architecture::ArmAarch32Ptr = typedef std::shared_ptr<ArmAarch32>

Reference counted pointer for ArmAarch32.

Definition at line 34 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ ArmAarch64Ptr

using Rose::BinaryAnalysis::Architecture::ArmAarch64Ptr = typedef std::shared_ptr<ArmAarch64>

Reference counted pointer for ArmAarch64.

Definition at line 37 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ BasePtr

using Rose::BinaryAnalysis::Architecture::BasePtr = typedef std::shared_ptr<Base>

Reference counted pointer for Architecture::Base.

Definition at line 40 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ BaseConstPtr

using Rose::BinaryAnalysis::Architecture::BaseConstPtr = typedef std::shared_ptr<const Base>

Reference counted pointer for Architecture::Base.

Definition at line 41 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ CilPtr

using Rose::BinaryAnalysis::Architecture::CilPtr = typedef std::shared_ptr<Cil>

Reference counted pointer for Cil.

Definition at line 44 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Intel80286Ptr

using Rose::BinaryAnalysis::Architecture::Intel80286Ptr = typedef std::shared_ptr<Intel80286>

Reference counted pointer for Intel80286.

Definition at line 47 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Intel8086Ptr

using Rose::BinaryAnalysis::Architecture::Intel8086Ptr = typedef std::shared_ptr<Intel8086>

Reference counted pointer for Intel8086.

Definition at line 50 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Intel8088Ptr

using Rose::BinaryAnalysis::Architecture::Intel8088Ptr = typedef std::shared_ptr<Intel8088>

Reference counted pointer for Intel8088.

Definition at line 53 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelI386Ptr

using Rose::BinaryAnalysis::Architecture::IntelI386Ptr = typedef std::shared_ptr<IntelI386>

Reference counted pointer for IntelI386.

Definition at line 56 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelI486Ptr

using Rose::BinaryAnalysis::Architecture::IntelI486Ptr = typedef std::shared_ptr<IntelI486>

Reference counted pointer for IntelI486.

Definition at line 59 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelPentiumPtr

using Rose::BinaryAnalysis::Architecture::IntelPentiumPtr = typedef std::shared_ptr<IntelPentium>

Reference counted pointer for IntelPentium.

Definition at line 62 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelPentiumiiPtr

using Rose::BinaryAnalysis::Architecture::IntelPentiumiiPtr = typedef std::shared_ptr<IntelPentiumii>

Reference counted pointer for IntelPentiumii.

Definition at line 65 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelPentiumiiiPtr

using Rose::BinaryAnalysis::Architecture::IntelPentiumiiiPtr = typedef std::shared_ptr<IntelPentiumiii>

Reference counted pointer for IntelPentiumiii.

Definition at line 68 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ IntelPentium4Ptr

using Rose::BinaryAnalysis::Architecture::IntelPentium4Ptr = typedef std::shared_ptr<IntelPentium4>

Reference counted pointer for IntelPentium4.

Definition at line 71 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ JvmPtr

using Rose::BinaryAnalysis::Architecture::JvmPtr = typedef std::shared_ptr<Jvm>

Reference counted pointer for Jvm.

Definition at line 74 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Mips32Ptr

using Rose::BinaryAnalysis::Architecture::Mips32Ptr = typedef std::shared_ptr<Mips32>

Reference counted pointer for Mips32.

Definition at line 77 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ MotorolaPtr

using Rose::BinaryAnalysis::Architecture::MotorolaPtr = typedef std::shared_ptr<Motorola>

Reference counted pointer for Motorola.

Definition at line 80 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Motorola68040Ptr

using Rose::BinaryAnalysis::Architecture::Motorola68040Ptr = typedef std::shared_ptr<Motorola68040>

Reference counted pointer for Motorola68040.

Definition at line 83 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ NxpColdfirePtr

using Rose::BinaryAnalysis::Architecture::NxpColdfirePtr = typedef std::shared_ptr<NxpColdfire>

Reference counted pointer for NxpColdfire.

Definition at line 86 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ PowerpcPtr

using Rose::BinaryAnalysis::Architecture::PowerpcPtr = typedef std::shared_ptr<Powerpc>

Reference counted pointer for Powerpc.

Definition at line 89 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Powerpc32Ptr

using Rose::BinaryAnalysis::Architecture::Powerpc32Ptr = typedef std::shared_ptr<Powerpc32>

Reference counted pointer for Powerpc32.

Definition at line 92 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ Powerpc64Ptr

using Rose::BinaryAnalysis::Architecture::Powerpc64Ptr = typedef std::shared_ptr<Powerpc64>

Reference counted pointer for Powerpc64.

Definition at line 95 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

◆ X86Ptr

using Rose::BinaryAnalysis::Architecture::X86Ptr = typedef std::shared_ptr<X86>

Reference counted pointer for X86.

Definition at line 98 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

Function Documentation

◆ initDiagnostics()

void Rose::BinaryAnalysis::Architecture::initDiagnostics ( )

Initialize and registers architecture diagnostic streams.

See Rose::Diagnostics::initialize.

◆ registerDefinition() [1/2]

size_t Rose::BinaryAnalysis::Architecture::registerDefinition ( const BasePtr & )

Register a new architecture definition.

The specified definition is added to the ROSE library. When searching for an architecture, architectures registered later are preferred over architectures registered earlier.

Returns the registration ID number assigned to the architecture. Since the argument can have only one registration ID number, it is an error to register the same architecture object multiple times concurrently. The registration ID is also stored in the architecture object's registrationId property.

Thread safety: This function is thread safe.

Referenced by registerDefinitions().

◆ registerDefinition() [2/2]

void Rose::BinaryAnalysis::Architecture::registerDefinition ( const std::string & )

Register definitions from a shared library.

If the specified name is a directory, then all files in that directory whose names end with ".so" are loaded. If the shared library has a function named "registerArchitectures" then it will be called. It must have C linkage and a type of void(void). This function is expected to register zero or more architecture definitions. The library must be compiled and linked in a manner consistent with the ROSE library.

Thread safety: Thread safe.

◆ registerDefinitions()

template<class Iterator >

void Rose::BinaryAnalysis::Architecture::registerDefinitions	(	Iterator	begin,
		Iterator	end
	)

Register definitions from shared libraries.

Calls registerDefinition for each library name, which should be a std::string.

Definition at line 144 of file Rose/BinaryAnalysis/Architecture/BasicTypes.h.

References registerDefinition().

◆ deregisterDefinition()

bool Rose::BinaryAnalysis::Architecture::deregisterDefinition ( const BasePtr & )

Remove the specified architecture from the list of registered architectures.

If the specified architecture object is found, then it is removed from the registration list and its registration ID is reset to zero. This function is a no-op if the argument is a null pointer.

Returns true if any architecture definition object was removed, false if the object was not found.

Thread safety: This function is thread safe.

◆ registeredDefinitions()

std::vector< BasePtr > Rose::BinaryAnalysis::Architecture::registeredDefinitions ( )

Registered architectures.

Returns the registered architectures in the reverse order they were registered.

Thread safety: This function is thread safe.

◆ registeredNames()

std::set< std::string > Rose::BinaryAnalysis::Architecture::registeredNames ( )

Names of all registered architectures.

Returns the names of all registered architectures. This is returned as a set, although there is no requirement that the registered architectures have unique names.

Thread safety: This function is thread safe.

◆ findByName()

Sawyer::Result< BasePtr, NotFound > Rose::BinaryAnalysis::Architecture::findByName ( const std::string & )

Look up a new architecture by name.

Looks through the list of registered architectures (from most recently registered to earliest registered) and returns the first one whose matchesName predicate returns true. If none match, then a NotFound error is returned.

The time to look up a name has linear time complexity which is a function of the number of architectures registered.

Thread safety: This function is thread safe.

◆ findById()

Sawyer::Result< BasePtr, NotFound > Rose::BinaryAnalysis::Architecture::findById ( size_t )

Look up a new architecture by registration ID.

Returns the architecture having the specified registration ID. If there is no such architecture, then a NotFound error is returned.

Lookup by ID is a constant time operation.

Thread safety: This function is thread safe.

◆ findByHeader()

Sawyer::Result< BasePtr, NotFound > Rose::BinaryAnalysis::Architecture::findByHeader ( SgAsmGenericHeader * )

Finds a suitable architecture for a file header.

Looks through the list of registered architectures (from most recently registered to earliest registered) and returns the first one whose matchesHeader() predicate returns true. If none match, then a NotFound error is returned.

Thread safety: This function is thread safe. However, no other thread can be modifying the AST at the same time.

◆ findByInterpretation()

Sawyer::Result< BasePtr, NotFound > Rose::BinaryAnalysis::Architecture::findByInterpretation ( SgAsmInterpretation * )

Finds a suitable architecture for a binary interpretation.

Looks through the list of registered architectures (from most recently registered to earliest registered) and returns the first one whose matchesHeader() predicate returns true for all the headers in the interpration. Returns the architecture that matches, or a NotFound error.

Thread safety: This function is thread safe. However, no other thread can be modifying the AST at the same time.

◆ findBestByInterpretation()

std::pair< BasePtr, size_t > Rose::BinaryAnalysis::Architecture::findBestByInterpretation ( SgAsmInterpretation * )

Finds the architecture that matches the most file headers.

Given an interpretation containing zero of more file headers, find the architecture that matches the most headers and return it along with now many headers it matched. If there is a tie, then the latest such registered architecture is returned. If no architecture matches any of the headers, then a null pointer and zero is returned.

Thread safety: This function is thread safe. However, no other thread can be modifying the AST at the same time.

◆ name() [1/2]

const std::string & Rose::BinaryAnalysis::Architecture::name ( const BaseConstPtr & )

Architecture name free function.

This is a convenient way to obtain an architecture definition's name without having to include "Base.h", and is therefore useful in header files that try to include a minimal number of type definitions. If the argument is a null architecture or invalid registration ID, then an empty name is returned.

Returns a null pointer if the argument is a null pointer.

◆ name() [2/2]

const std::string & Rose::BinaryAnalysis::Architecture::name ( size_t registrationId )

Architecture name free function.

This is a convenient way to obtain an architecture definition's name without having to include "Base.h", and is therefore useful in header files that try to include a minimal number of type definitions. If the argument is a null architecture or invalid registration ID, then an empty name is returned.

Returns a null pointer if the argument is a null pointer.

◆ newInstructionDispatcher()

InstructionSemantics::BaseSemantics::DispatcherPtr Rose::BinaryAnalysis::Architecture::newInstructionDispatcher	(	const std::string &	name,
		const InstructionSemantics::BaseSemantics::RiscOperatorsPtr &
	)

Create a new instruction dispatcher by name.

This is a conventient way to obtain a dispatcher without having to include "Base.h" and is therefore useful in header files that try to include a minimal number of type definitions. Throws a NotFound error if the name is not found.

Description

Changes from previous versions

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ Amd64Ptr

◆ ArmAarch32Ptr

◆ ArmAarch64Ptr

◆ BasePtr

◆ BaseConstPtr

◆ CilPtr

◆ Intel80286Ptr

◆ Intel8086Ptr

◆ Intel8088Ptr

◆ IntelI386Ptr

◆ IntelI486Ptr

◆ IntelPentiumPtr

◆ IntelPentiumiiPtr

◆ IntelPentiumiiiPtr

◆ IntelPentium4Ptr

◆ JvmPtr

◆ Mips32Ptr

◆ MotorolaPtr

◆ Motorola68040Ptr

◆ NxpColdfirePtr

◆ PowerpcPtr

◆ Powerpc32Ptr

◆ Powerpc64Ptr

◆ X86Ptr

Function Documentation

◆ initDiagnostics()

◆ registerDefinition() [1/2]

◆ registerDefinition() [2/2]

◆ registerDefinitions()

◆ deregisterDefinition()

◆ registeredDefinitions()

◆ registeredNames()

◆ findByName()

◆ findById()

◆ findByHeader()

◆ findByInterpretation()

◆ findBestByInterpretation()

◆ name() [1/2]

◆ name() [2/2]

◆ newInstructionDispatcher()