Translate Class Reference

The interface to a translation engine for a processor. More...

#include <translate.hh>

Inheritance diagram for Translate:

Collaboration diagram for Translate:

Public Member Functions
	Translate (void)
	Constructor for the translator. More...
void	setDefaultFloatFormats (void)
	If no explicit float formats, set up default formats. More...
bool	isBigEndian (void) const
	Is the processor big endian? More...
const FloatFormat *	getFloatFormat (int4 size) const
	Get format for a particular floating point encoding. More...
int4	getAlignment (void) const
	Get the instruction alignment for the processor. More...
uintm	getUniqueBase (void) const
	Get the base offset for new temporary registers. More...
virtual void	initialize (DocumentStorage &store)=0
	Initialize the translator given XML configuration documents. More...
virtual void	registerContext (const string &name, int4 sbit, int4 ebit)
	Add a new context variable to the model for this processor. More...
virtual void	setContextDefault (const string &name, uintm val)
	Set the default value for a particular context variable. More...
virtual void	allowContextSet (bool val) const
	Toggle whether disassembly is allowed to affect context. More...
virtual void	addRegister (const string &nm, AddrSpace *base, uintb offset, int4 size)=0
	Add a named register to the model for this processor. More...
virtual const VarnodeData &	getRegister (const string &nm) const =0
	Get a register as VarnodeData given its name. More...
virtual string	getRegisterName (AddrSpace *base, uintb off, int4 size) const =0
	Get the name of a register given its location. More...
virtual void	getAllRegisters (map< VarnodeData, string > &reglist) const =0
	Get a list of all register names and the corresponding location. More...
virtual void	getUserOpNames (vector< string > &res) const =0
	Get a list of all user-defined pcode ops. More...
virtual int4	instructionLength (const Address &baseaddr) const =0
	Get the length of a machine instruction. More...
virtual int4	oneInstruction (PcodeEmit &emit, const Address &baseaddr) const =0
	Transform a single machine instruction into pcode. More...
virtual int4	printAssembly (AssemblyEmit &emit, const Address &baseaddr) const =0
	Disassemble a single machine instruction. More...
Public Member Functions inherited from AddrSpaceManager
	AddrSpaceManager (void)
	Construct an empty address space manager. More...
virtual	~AddrSpaceManager (void)
	Destroy the manager. More...
int4	getDefaultSize (void) const
	Get size of addresses for the default space. More...
AddrSpace *	getSpaceByName (const string &nm) const
	Get address space by name. More...
AddrSpace *	getSpaceByShortcut (char sc) const
	Get address space from its shortcut. More...
AddrSpace *	getIopSpace (void) const
	Get the internal pcode op space. More...
AddrSpace *	getFspecSpace (void) const
	Get the internal callspec space. More...
AddrSpace *	getJoinSpace (void) const
	Get the joining space. More...
AddrSpace *	getStackSpace (void) const
	Get the stack space for this processor. More...
AddrSpace *	getUniqueSpace (void) const
	Get the temporary register space for this processor. More...
AddrSpace *	getDefaultCodeSpace (void) const
	Get the default address space of this processor. More...
AddrSpace *	getDefaultDataSpace (void) const
	Get the default address space where data is stored. More...
AddrSpace *	getConstantSpace (void) const
	Get the constant space. More...
Address	getConstant (uintb val) const
	Get a constant encoded as an Address. More...
Address	createConstFromSpace (AddrSpace *spc) const
	Create a constant address encoding an address space. More...
Address	resolveConstant (AddrSpace *spc, uintb val, int4 sz, const Address &point, uintb &fullEncoding) const
	Resolve a native constant into an Address. More...
int4	numSpaces (void) const
	Get the number of address spaces for this processor. More...
AddrSpace *	getSpace (int4 i) const
	Get an address space via its index. More...
AddrSpace *	getNextSpaceInOrder (AddrSpace *spc) const
	Get the next contiguous address space. More...
JoinRecord *	findAddJoin (const vector< VarnodeData > &pieces, uint4 logicalsize)
	Get (or create) JoinRecord for pieces. More...
JoinRecord *	findJoin (uintb offset) const
	Find JoinRecord for offset in the join space. More...
void	setDeadcodeDelay (AddrSpace *spc, int4 delaydelta)
	Set the deadcodedelay for a specific space. More...
void	truncateSpace (const TruncationTag &tag)
	Mark a space as truncated from its original size. More...
Address	constructFloatExtensionAddress (const Address &realaddr, int4 realsize, int4 logicalsize)
	Build a logically lower precision storage location for a bigger floating point register. More...
Address	constructJoinAddress (const Translate *translate, const Address &hiaddr, int4 hisz, const Address &loaddr, int4 losz)
	Build a logical whole from register pairs. More...
void	renormalizeJoinAddress (Address &addr, int4 size)
	Make sure a possibly offset join address has a proper JoinRecord. More...

Protected Member Functions
void	setBigEndian (bool val)
	Set general endianness to big if val is true. More...
void	setUniqueBase (uintm val)
	Set the base offset for new temporary registers. More...
Protected Member Functions inherited from AddrSpaceManager
AddrSpace *	restoreXmlSpace (const Element *el, const Translate *trans)
	Add a space to the model based an on XML tag. More...
void	restoreXmlSpaces (const Element *el, const Translate *trans)
	Restore address spaces in the model from an XML tag. More...
void	setDefaultCodeSpace (int4 index)
	Set the default address space (for code) More...
void	setDefaultDataSpace (int4 index)
	Set the default address space for data. More...
void	setReverseJustified (AddrSpace *spc)
	Set reverse justified property on this space. More...
void	assignShortcut (AddrSpace *spc)
	Select a shortcut character for a new space. More...
void	markNearPointers (AddrSpace *spc, int4 size)
	Mark that given space can be accessed with near pointers. More...
void	insertSpace (AddrSpace *spc)
	Add a new address space to the model. More...
void	copySpaces (const AddrSpaceManager *op2)
	Copy spaces from another manager. More...
void	addSpacebasePointer (SpacebaseSpace *basespace, const VarnodeData &ptrdata, int4 truncSize, bool stackGrowth)
	Set the base register of a spacebase space. More...
void	insertResolver (AddrSpace *spc, AddressResolver *rsolv)
	Override the base resolver for a space. More...
JoinRecord *	findJoinInternal (uintb offset) const
	Find JoinRecord for offset in the join space. More...

Protected Attributes
int4	alignment
	Byte modulo on which instructions are aligned.
vector< FloatFormat >	floatformats
	Floating point formats utilized by the processor.

Detailed Description

The interface to a translation engine for a processor.

This interface performs translations of instruction data for a particular processor. It has two main functions

• Disassemble single machine instructions
• Translate single machine instructions into pcode.

It is also the repository for information about the exact configuration of the reverse engineering model associated with the processor. In particular, it knows about all the address spaces, registers, and spacebases for the processor.

Constructor & Destructor Documentation

Translate()

Translate::Translate

(

void

)

Constructor for the translator.

This constructs only a shell for the Translate object. It won't be usable until it is initialized for a specific processor The main entry point for this is the Translate::initialize method, which must be overridden by a derived class

Member Function Documentation

addRegister()

virtual void Translate::addRegister ( const string &  nm, AddrSpace *  base, uintb  offset, int4  size  )

pure virtual

Add a named register to the model for this processor.

Deprecated:

All registers used to be formally added to the processor model through this method.

Parameters

nm	is the name of the new register
base	is the address space containing the register
offset	is the offset of the register
size	is the number of bytes in the register

Implemented in DummyTranslate, SleighBase, and GhidraTranslate.

allowContextSet()

virtual void Translate::allowContextSet ( bool  val ) const

inlinevirtual

Toggle whether disassembly is allowed to affect context.

By default the disassembly/pcode translation engine can change the global context, thereby affecting later disassembly. Context may be getting determined by something other than control flow in, the disassembly, in which case this function can turn off changes made by the disassembly

Parameters

val	is true to allow context changes, false prevents changes

Reimplemented in Sleigh.

getAlignment()

int4 Translate::getAlignment ( void  ) const

inline

Get the instruction alignment for the processor.

If machine instructions need to have a specific alignment for this processor, this routine returns it. I.e. a return value of 4, means that the address of all instructions must be a multiple of 4. If there is no specific alignment requirement, this routine returns 1.

Returns

the instruction alignment

getAllRegisters()

virtual void Translate::getAllRegisters ( map< VarnodeData, string > &  reglist ) const

pure virtual

Get a list of all register names and the corresponding location.

Most processors have a list of named registers and possibly other memory locations that are specific to it. This function populates a map from the location information to the name, for every named location known by the translator

Parameters

reglist

is the map which will be populated by the call

Implemented in DummyTranslate, SleighBase, and GhidraTranslate.

getFloatFormat()

const FloatFormat * Translate::getFloatFormat

(

int4

size

)

const

Get format for a particular floating point encoding.

The pcode model for floating point encoding assumes that a consistent encoding is used for all values of a given size. This routine fetches the FloatFormat object given the size, in bytes, of the desired encoding.

Parameters

size	is the size of the floating-point value in bytes

Returns

a pointer to the floating-point format

getRegister()

virtual const VarnodeData& Translate::getRegister ( const string &  nm ) const

pure virtual

Get a register as VarnodeData given its name.

Retrieve the location and size of a register given its name

Parameters

nm	is the name of the register

Returns

the VarnodeData for the register

Implemented in DummyTranslate, SleighBase, and GhidraTranslate.

getRegisterName()

virtual string Translate::getRegisterName ( AddrSpace *  base, uintb  off, int4  size  ) const

pure virtual

Get the name of a register given its location.

Generic references to locations in a register space can be translated into the associated register name. If the location doesn't match a register exactly, an empty string is returned.

Parameters

base	is the address space containing the location
off	is the offset of the location
size	is the size of the location

Returns

the name of the register, or an empty string

Implemented in DummyTranslate, SleighBase, and GhidraTranslate.

getUniqueBase()

uintm Translate::getUniqueBase ( void  ) const

inline

Get the base offset for new temporary registers.

This routine gets the base offset, within the unique temporary register space, where new registers can be allocated for the simplification process. Locations before this offset are reserved registers needed by the pcode translation engine.

Returns

the first allocatable offset

getUserOpNames()

virtual void Translate::getUserOpNames ( vector< string > &  res ) const

pure virtual

Get a list of all user-defined pcode ops.

The pcode model allows processors to define new pcode instructions that are specific to that processor. These user-defined instructions are all identified by a name and an index. This method returns a list of these ops in index order.

Parameters

res	is the resulting vector of user op names

Implemented in DummyTranslate, GhidraTranslate, and SleighBase.

initialize()

virtual void Translate::initialize ( DocumentStorage &  store )

pure virtual

Initialize the translator given XML configuration documents.

A translator gets initialized once, possibly using XML documents to configure it.

Parameters

store

is a set of configuration documents

Implemented in SleighCompile, Sleigh, DummyTranslate, and GhidraTranslate.

instructionLength()

virtual int4 Translate::instructionLength ( const Address &  baseaddr ) const

pure virtual

Get the length of a machine instruction.

This method decodes an instruction at a specific address just enough to find the number of bytes it uses within the instruction stream.

Parameters

baseaddr

is the Address of the instruction

Returns

the number of bytes in the instruction

Implemented in SleighCompile, Sleigh, DummyTranslate, and GhidraTranslate.

isBigEndian()

bool Translate::isBigEndian ( void  ) const

inline

Is the processor big endian?

Processors can usually be described as using a big endian encoding or a little endian encoding. This routine returns true if the processor globally uses big endian encoding.

Returns

true if big endian

oneInstruction()

virtual int4 Translate::oneInstruction ( PcodeEmit &  emit, const Address &  baseaddr  ) const

pure virtual

Transform a single machine instruction into pcode.

This is the main interface to the pcode translation engine. The dump method in the emit object is invoked exactly once for each pcode operation in the translation for the machine instruction at the given address. This routine can throw either

• UnimplError or
• BadDataError

Parameters

emit	is the tailored pcode emitting object
baseaddr	is the Address of the machine instruction

Returns

the number of bytes in the machine instruction

Implemented in SleighCompile, Sleigh, DummyTranslate, and GhidraTranslate.

printAssembly()

virtual int4 Translate::printAssembly ( AssemblyEmit &  emit, const Address &  baseaddr  ) const

pure virtual

Disassemble a single machine instruction.

This is the main interface to the disassembler for the processor. It disassembles a single instruction and returns the result to the application via the dump method in the emit object.

Parameters

emit	is the disassembly emitting object
baseaddr	is the address of the machine instruction to disassemble

Implemented in SleighCompile, Sleigh, DummyTranslate, and GhidraTranslate.

registerContext()

virtual void Translate::registerContext ( const string &  name, int4  sbit, int4  ebit  )

inlinevirtual

Add a new context variable to the model for this processor.

Add the name of a context register used by the processor and how that register is packed into the context state. This information is used by a ContextDatabase to associate names with context information and to pack context into a single state variable for the translation engine.

Parameters

name	is the name of the new context variable
sbit	is the first bit of the variable in the packed state
ebit	is the last bit of the variable in the packed state

Reimplemented in Sleigh.

setBigEndian()

void Translate::setBigEndian ( bool  val )

inlineprotected

Set general endianness to big if val is true.

Although endianness is usually specified on the space, most languages set an endianness across the entire processor. This routine sets the endianness to big if the -val- is passed in as true. Otherwise, the endianness is set to small.

Parameters

val	is true if the endianness should be set to big

setContextDefault()

virtual void Translate::setContextDefault ( const string &  name, uintm  val  )

inlinevirtual

Set the default value for a particular context variable.

Set the value to be returned for a context variable when there are no explicit address ranges specifying a value for the variable.

Parameters

name	is the name of the context variable
val	is the value to be considered default

Reimplemented in Sleigh.

setDefaultFloatFormats()

void Translate::setDefaultFloatFormats

(

void

)

If no explicit float formats, set up default formats.

If no floating-point format objects were registered by the initialize method, this method will fill in some suitable default formats. These defaults are based on the 4-byte and 8-byte encoding specified by the IEEE 754 standard.

setUniqueBase()

void Translate::setUniqueBase ( uintm  val )

inlineprotected

Set the base offset for new temporary registers.

The unique address space, for allocating temporary registers, is used for both registers needed by the pcode translation engine and, later, by the simplification engine. This routine sets the boundary of the portion of the space allocated for the pcode engine, and sets the base offset where registers created by the simplification process can start being allocated.

Parameters

val	is the boundary offset

---

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

• translate.hh
• translate.cc