Package ghidra.program.database

Class ProgramBuilder

java.lang.Object

ghidra.program.database.ProgramBuilder

Direct Known Subclasses:

ClassicSampleX86ProgramBuilder, ToyProgramBuilder

public class ProgramBuilder
extends Object

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ProgramBuilder.ExceptionalSupplier<R,E extends Exception>

Field Summary

Fields

Modifier and Type	Field	Description
static final String	_8051
static final String	_AARCH64
static final String	_ARM
static final String	_MIPS
static final String	_MIPS_6432
static final String	_PPC_32
static final String	_PPC_64
static final String	_PPC_6432
static final String	_SPARC64
static final String	_TOY
static final String	_TOY_BE
static final String	_TOY_BE_POSITIVE
protected static final String	_TOY_LANGUAGE_PREFIX
static final String	_TOY_LE
static final String	_TOY_WORDSIZE2_BE
static final String	_TOY_WORDSIZE2_LE
static final String	_TOY64_BE
static final String	_TOY64_LE
static final String	_X64
static final String	_X86
static final String	_X86_16_REAL_MODE

Constructor Summary

Constructors

Constructor	Description
ProgramBuilder()	Construct program builder using the big-endian Toy language and default compiler spec.
ProgramBuilder(String name, Language language)	Construct program builder using a full language object rather than a language id string
ProgramBuilder(String name, String languageName)	Construct program builder using specified language and default compiler spec.
ProgramBuilder(String name, String languageName, Object consumer)	Construct program builder using specified language and default compiler spec
ProgramBuilder(String name, String languageName, String compilerSpecID, Object consumer)	Construct program builder using specified language

Method Summary

Modifier and Type	Method	Description
void	addCategory(CategoryPath path)
void	addDataType(DataType dt)
void	addFunctionVariable(Function f, Variable v)
Address	addr(long offset)
Address	addr(String addressString)
void	analyze()	Perform complete analysis on the built program.
void	applyDataType(String addressString, DataType dt)
void	applyDataType(String addressString, DataType dt, int n)	Creates a data instance at the specified address, repeated N times.
void	applyFixedLengthDataType(String addressString, DataType dt, int length)
void	applyStringDataType(String addressString, AbstractStringDataType dt, int n)	Creates a sting data type instance at the specified address, repeated N times.
void	bindExternalLibrary(String libraryName, String pathname)
void	clearCodeUnits(String startAddressString, String endAddressString, boolean clearContext)
Bookmark	createBookmark(String address, String bookmarkType, String category, String comment)
GhidraClass	createClassNamespace(String name, String parentNamespace, SourceType type)
void	createComment(String address, String comment, int commentType)	Deprecated, for removal: This API element is subject to removal in a future version.
void	createComment(String address, String comment, CommentType commentType)
Function	createEmptyFunction(String name, String address, int size, DataType returnType, boolean varargs, boolean inline, boolean noReturn, Parameter... params)
Function	createEmptyFunction(String name, String address, int size, DataType returnType, Parameter... params)
Function	createEmptyFunction(String name, String namespace, String callingConventionName, boolean customStorage, String address, int bodySize, DataType returnType, Parameter... params)
Function	createEmptyFunction(String name, String namespace, String address, int bodySize, DataType returnType, Parameter... params)
Function	createEmptyFunction(String name, String namespace, String callingConventionName, String address, int size, DataType returnType, DataType... paramTypes)
void	createEncodedString(String address, String string, Charset encoding, boolean nullTerminate)
Symbol	createEntryPoint(String addressString, String name)
Equate	createEquate(String address, String name, long value, int opIndex)
ExternalLocation	createExternalFunction(String extAddress, String libName, String functionName)
ExternalLocation	createExternalFunction(String extAddress, String libName, String functionName, String originalName)
void	createExternalLibraries(String... libraryNames)
void	createExternalReference(String fromAddress, String libraryName, String externalLabel, int opIndex)
void	createExternalReference(String fromAddress, String libraryName, String externalLabel, String extAddress, int opIndex)
void	createExternalReference(String fromAddress, String libraryName, String externalLabel, String extAddress, int opIndex, RefType refType, SourceType sourceType)
FileBytes	createFileBytes(int size)
void	createFragment(String treeName, String modulePath, String fragmentName, String startAddr, String endAddr)
Function	createFunction(String addressString)	Creates a function by examining the instructions to find the body.
void	createFunctionComment(String entryPointAddress, String comment)
Symbol	createLabel(String addressString, String name)
Symbol	createLabel(String addressString, String name, String namespace)
Library	createLibrary(String libraryName)
Library	createLibrary(String libraryName, SourceType type)
void	createLocalVariable(Function function, String name, DataType dt, int stackOffset)
MemoryBlock	createMemory(String name, String address, int size)
MemoryBlock	createMemory(String name, String address, int size, String comment)
MemoryBlock	createMemory(String name, String address, int size, String comment, byte initialValue)
MemoryBlock	createMemory(String name, String address, FileBytes fileBytes, int size)
Reference	createMemoryCallReference(String fromAddress, String toAddress)
Reference	createMemoryJumpReference(String fromAddress, String toAddress)
Reference	createMemoryReadReference(String fromAddress, String toAddress)
Reference	createMemoryReference(String fromAddress, String toAddress, RefType refType, SourceType sourceType)
Reference	createMemoryReference(String fromAddress, String toAddress, RefType refType, SourceType sourceType, int opIndex)
Namespace	createNamespace(String namespace)
Namespace	createNamespace(String namespace, SourceType type)
Namespace	createNamespace(String namespace, String parentNamespace, SourceType type)
Reference	createOffsetMemReference(String fromAddress, String toAddress, int offset, RefType refType, SourceType sourceType, int opIndex)
MemoryBlock	createOverlayMemory(String name, String address, int size)
void	createProgramTree(String treeName)
Reference	createRegisterReference(String fromAddress, RefType refType, String registerName, SourceType sourceType, int opIndex)
Reference	createRegisterReference(String fromAddress, String registerName, int opIndex)
Reference	createStackReference(String fromAddress, RefType refType, int stackOffset, SourceType sourceType, int opIndex)
Data	createString(String address, byte[] stringBytes, Charset charset, DataType dataType)
Data	createString(String address, String string, Charset charset, boolean nullTerminate, DataType dataType)
MemoryBlock	createUninitializedMemory(String name, String address, int size)
void	deleteFunction(String address)
void	deleteReference(Reference reference)
void	disassemble(AddressSetView set)
void	disassemble(AddressSetView set, boolean followFlows)
void	disassemble(String addressString, int length)
void	disassemble(String addressString, int length, boolean followFlows)
void	disassembleArm(String addressString, int length, boolean thumb)
void	dispose()
protected void	endTransaction()
protected void	endTransaction(boolean commit)
CompilerSpec	getCompilerSpec()
Language	getLanguage()
Namespace	getNamespace(String namespace)
Namespace	getNamespace(String namespace, Address address)
ProgramModule	getOrCreateModule(String treeName, String modulePath)
ProgramDB	getProgram()	Get the constructed program.
Register	getRegister(String regName)
void	setAnalysisEnabled(String name, boolean enabled)
void	setAnalyzed()	This prevents the 'ask to analyze' dialog from showing when called with true
void	setBytes(String stringAddress, byte[] bytes)
void	setBytes(String stringAddress, byte[] bytes, boolean disassemble)	Sets the bytes starting at stringAddress to the byte values in bytes and then optionally disassembling.
void	setBytes(String address, String byteString)	Sets the bytes starting at address to the values encoded in byteString.
void	setBytes(String address, String byteString, boolean disassemble)	Sets the bytes starting at address to the values encoded in byteString and then optionally disassembling.
void	setChanged(boolean changed)
void	setExecute(MemoryBlock block, boolean e)
void	setFallthrough(String from, String to)
void	setIntProperty(String address, String propertyName, int value)
void	setName(String name)
void	setObjectProperty(String address, String propertyName, Saveable value)
void	setProperty(String name, Object value)
void	setRead(MemoryBlock block, boolean r)
void	setRecordChanges(boolean enabled)
void	setRegisterValue(String registerName, String startAddress, String endAddress, long value)
void	setStringProperty(String address, String propertyName, String value)
void	setWrite(MemoryBlock block, boolean w)
protected void	startTransaction()
<R, E extends Exception> R	tx(ProgramBuilder.ExceptionalSupplier<R,E> s)
<E extends Exception> void	tx(ExceptionalCallback<E> c)
void	withTransaction(Runnable r)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

_ARM

public static final String _ARM

See Also:

• Constant Field Values

_AARCH64

public static final String _AARCH64

See Also:

• Constant Field Values

_X86

public static final String _X86

See Also:

• Constant Field Values

_X86_16_REAL_MODE

public static final String _X86_16_REAL_MODE

See Also:

• Constant Field Values

_X64

public static final String _X64

See Also:

• Constant Field Values

_8051

public static final String _8051

See Also:

• Constant Field Values

_SPARC64

public static final String _SPARC64

See Also:

• Constant Field Values

_MIPS

public static final String _MIPS

See Also:

• Constant Field Values

_MIPS_6432

public static final String _MIPS_6432

See Also:

• Constant Field Values

_PPC_32

public static final String _PPC_32

See Also:

• Constant Field Values

_PPC_6432

public static final String _PPC_6432

See Also:

• Constant Field Values

_PPC_64

public static final String _PPC_64

See Also:

• Constant Field Values

_TOY_BE

public static final String _TOY_BE

See Also:

• Constant Field Values

_TOY_BE_POSITIVE

public static final String _TOY_BE_POSITIVE

See Also:

• Constant Field Values

_TOY_LE

public static final String _TOY_LE

See Also:

• Constant Field Values

_TOY_WORDSIZE2_BE

public static final String _TOY_WORDSIZE2_BE

See Also:

• Constant Field Values

_TOY_WORDSIZE2_LE

public static final String _TOY_WORDSIZE2_LE

See Also:

• Constant Field Values

_TOY64_BE

public static final String _TOY64_BE

See Also:

• Constant Field Values

_TOY64_LE

public static final String _TOY64_LE

See Also:

• Constant Field Values

_TOY

public static final String _TOY

See Also:

• Constant Field Values

_TOY_LANGUAGE_PREFIX

protected static final String _TOY_LANGUAGE_PREFIX

See Also:

• Constant Field Values

Constructor Details

ProgramBuilder

public ProgramBuilder()
               throws Exception

Construct program builder using the big-endian Toy language and default compiler spec. This builder object will be the program consumer and must be disposed to properly release the program.

Throws:

Exception - if there is an exception creating the program

ProgramBuilder

public ProgramBuilder(String name,
 String languageName)
               throws Exception

Construct program builder using specified language and default compiler spec. This builder object will be the program consumer and must be disposed to properly release the program.

Parameters:

name - program name

languageName - supported language ID (includes all Toy language IDs)

Throws:

Exception - if there is an exception creating the program

ProgramBuilder

public ProgramBuilder(String name,
 String languageName,
 Object consumer)
               throws Exception

Construct program builder using specified language and default compiler spec

Parameters:

name - program name

languageName - supported language ID (includes all Toy language IDs)

consumer - program consumer (if null this builder will be used as consumer and must be disposed to release program)

Throws:

Exception - if there is an exception creating the program

ProgramBuilder

public ProgramBuilder(String name,
 String languageName,
 String compilerSpecID,
 Object consumer)
               throws Exception

Construct program builder using specified language

Parameters:

name - program name

languageName - supported language ID (includes all Toy language IDs)

compilerSpecID - compiler specification ID (if null default spec will be used)

consumer - program consumer (if null this builder will be used as consumer and must be disposed to release program)

Throws:

Exception - if there is an exception creating the program

ProgramBuilder

public ProgramBuilder(String name,
 Language language)
               throws Exception

Construct program builder using a full language object rather than a language id string

Parameters:

name - program name

language - Language object

Throws:

Exception - if there is an exception creating the program

Method Details

analyze

public void analyze()

Perform complete analysis on the built program. Limited analysis may already have been performed during disassembly - so it may not be necessary to do complete analysis

getProgram

public ProgramDB getProgram()

Get the constructed program. If this builder was not constructed with a consumer, the caller should dispose the builder after either the program is no longer in use, or a new consumer has been added to the program (e.g., program opened in a tool or another consumer explicitly added).

Returns:

constructed program

getLanguage

public Language getLanguage()

getCompilerSpec

public CompilerSpec getCompilerSpec()

getRegister

public Register getRegister(String regName)

addr

public Address addr(long offset)

addr

public Address addr(String addressString)

dispose

public void dispose()

setName

public void setName(String name)

withTransaction

public void withTransaction(Runnable r)

startTransaction

protected void startTransaction()

endTransaction

protected void endTransaction()

endTransaction

protected void endTransaction(boolean commit)

setRecordChanges

public void setRecordChanges(boolean enabled)

setAnalyzed

public void setAnalyzed()

This prevents the 'ask to analyze' dialog from showing when called with true

createMemory

public MemoryBlock createMemory(String name,
 String address,
 int size)

createMemory

public MemoryBlock createMemory(String name,
 String address,
 int size,
 String comment)

createMemory

public MemoryBlock createMemory(String name,
 String address,
 FileBytes fileBytes,
 int size)

createMemory

public MemoryBlock createMemory(String name,
 String address,
 int size,
 String comment,
 byte initialValue)

createUninitializedMemory

public MemoryBlock createUninitializedMemory(String name,
 String address,
 int size)

createOverlayMemory

public MemoryBlock createOverlayMemory(String name,
 String address,
 int size)

setBytes

public void setBytes(String address,
 String byteString)
              throws Exception

Sets the bytes starting at address to the values encoded in byteString.

See setBytes(String, byte[], boolean).

Parameters:

address - String containing numeric value, preferably hex encoded: "0x1004000"

byteString - String containing 2 digit hex values, separated by ' ' space chars or by comma ',' chars: "12 05 ff". See NumericUtilities.parseHexLong(String).

Throws:

Exception - if there is an exception applying the bytes

setBytes

public void setBytes(String address,
 String byteString,
 boolean disassemble)
              throws Exception

Sets the bytes starting at address to the values encoded in byteString and then optionally disassembling.

See setBytes(String, byte[], boolean).

Parameters:

address - String containing numeric value, preferably hex encoded: "0x1004000"

byteString - String containing 2 digit hex values, separated by ' ' space chars or by comma ',' chars: "12 05 ff". See NumericUtilities.parseHexLong(String).

disassemble - boolean flag.

Throws:

Exception - if there is an exception applying the bytes

setBytes

public void setBytes(String stringAddress,
 byte[] bytes)
              throws Exception

Throws:

Exception

setBytes

public void setBytes(String stringAddress,
 byte[] bytes,
 boolean disassemble)
              throws Exception

Sets the bytes starting at stringAddress to the byte values in bytes and then optionally disassembling.

Parameters:

stringAddress - String containing numeric value, preferably hex encoded: "0x1004000"

bytes - array of bytes to copy into the memory buffer at the addresss.

disassemble - boolean flag. See disassemble(String, int)

Throws:

Exception - if there is an exception applying the bytes

setRead

public void setRead(MemoryBlock block,
 boolean r)

setWrite

public void setWrite(MemoryBlock block,
 boolean w)

setExecute

public void setExecute(MemoryBlock block,
 boolean e)

disassemble

public void disassemble(String addressString,
 int length)

disassemble

public void disassemble(String addressString,
 int length,
 boolean followFlows)

disassemble

public void disassemble(AddressSetView set)

disassemble

public void disassemble(AddressSetView set,
 boolean followFlows)

disassembleArm

public void disassembleArm(String addressString,
 int length,
 boolean thumb)

clearCodeUnits

public void clearCodeUnits(String startAddressString,
 String endAddressString,
 boolean clearContext)
                    throws Exception

Throws:

Exception

createLabel

public Symbol createLabel(String addressString,
 String name)

createLabel

public Symbol createLabel(String addressString,
 String name,
 String namespace)

createFunction

public Function createFunction(String addressString)

Creates a function by examining the instructions to find the body.

Parameters:

addressString - the address

Returns:

the function

addFunctionVariable

public void addFunctionVariable(Function f,
 Variable v)
                         throws Exception

Throws:

Exception

createEmptyFunction

public Function createEmptyFunction(String name,
 String address,
 int size,
 DataType returnType,
 Parameter... params)
                             throws Exception,
OverlappingFunctionException

Throws:

Exception

OverlappingFunctionException

createEmptyFunction

public Function createEmptyFunction(String name,
 String address,
 int size,
 DataType returnType,
 boolean varargs,
 boolean inline,
 boolean noReturn,
 Parameter... params)
                             throws Exception

Throws:

Exception

createEmptyFunction

public Function createEmptyFunction(String name,
 String namespace,
 String address,
 int bodySize,
 DataType returnType,
 Parameter... params)
                             throws Exception

Throws:

Exception

createEmptyFunction

public Function createEmptyFunction(String name,
 String namespace,
 String callingConventionName,
 boolean customStorage,
 String address,
 int bodySize,
 DataType returnType,
 Parameter... params)
                             throws Exception

Throws:

Exception

createEmptyFunction

public Function createEmptyFunction(String name,
 String namespace,
 String callingConventionName,
 String address,
 int size,
 DataType returnType,
 DataType... paramTypes)
                             throws Exception

Throws:

Exception

deleteFunction

public void deleteFunction(String address)
                    throws Exception

Throws:

Exception

createLibrary

public Library createLibrary(String libraryName)
                      throws DuplicateNameException,
InvalidInputException

Throws:

DuplicateNameException

InvalidInputException

createLibrary

public Library createLibrary(String libraryName,
 SourceType type)
                      throws DuplicateNameException,
InvalidInputException

Throws:

DuplicateNameException

InvalidInputException

createNamespace

public Namespace createNamespace(String namespace)

getNamespace

public Namespace getNamespace(String namespace)

getNamespace

public Namespace getNamespace(String namespace,
 Address address)

createNamespace

public Namespace createNamespace(String namespace,
 SourceType type)

createNamespace

public Namespace createNamespace(String namespace,
 String parentNamespace,
 SourceType type)

createClassNamespace

public GhidraClass createClassNamespace(String name,
 String parentNamespace,
 SourceType type)
                                 throws Exception

Throws:

Exception

applyFixedLengthDataType

public void applyFixedLengthDataType(String addressString,
 DataType dt,
 int length)

applyDataType

public void applyDataType(String addressString,
 DataType dt)

applyDataType

public void applyDataType(String addressString,
 DataType dt,
 int n)

Creates a data instance at the specified address, repeated N times. Any conflicting Data will be overwritten.

Parameters:

addressString - address.

dt - DataType to place at address, Dynamic length datatype not supported.

n - repeat count.

applyStringDataType

public void applyStringDataType(String addressString,
 AbstractStringDataType dt,
 int n)

Creates a sting data type instance at the specified address, repeated N times.

Parameters:

addressString - address.

dt - AbstractStringDataType string type to place at address.

n - repeat count.

deleteReference

public void deleteReference(Reference reference)

createMemoryReadReference

public Reference createMemoryReadReference(String fromAddress,
 String toAddress)

createMemoryCallReference

public Reference createMemoryCallReference(String fromAddress,
 String toAddress)

createMemoryJumpReference

public Reference createMemoryJumpReference(String fromAddress,
 String toAddress)

createMemoryReference

public Reference createMemoryReference(String fromAddress,
 String toAddress,
 RefType refType,
 SourceType sourceType)

createMemoryReference

public Reference createMemoryReference(String fromAddress,
 String toAddress,
 RefType refType,
 SourceType sourceType,
 int opIndex)

createOffsetMemReference

public Reference createOffsetMemReference(String fromAddress,
 String toAddress,
 int offset,
 RefType refType,
 SourceType sourceType,
 int opIndex)

createStackReference

public Reference createStackReference(String fromAddress,
 RefType refType,
 int stackOffset,
 SourceType sourceType,
 int opIndex)

createRegisterReference

public Reference createRegisterReference(String fromAddress,
 String registerName,
 int opIndex)

createRegisterReference

public Reference createRegisterReference(String fromAddress,
 RefType refType,
 String registerName,
 SourceType sourceType,
 int opIndex)

createEntryPoint

public Symbol createEntryPoint(String addressString,
 String name)

createBookmark

public Bookmark createBookmark(String address,
 String bookmarkType,
 String category,
 String comment)

createEncodedString

public void createEncodedString(String address,
 String string,
 Charset encoding,
 boolean nullTerminate)
                         throws Exception

Throws:

Exception

createString

public Data createString(String address,
 String string,
 Charset charset,
 boolean nullTerminate,
 DataType dataType)
                  throws Exception

Throws:

Exception

createString

public Data createString(String address,
 byte[] stringBytes,
 Charset charset,
 DataType dataType)
                  throws Exception

Throws:

Exception

setProperty

public void setProperty(String name,
 Object value)

setAnalysisEnabled

public void setAnalysisEnabled(String name,
 boolean enabled)

addDataType

public void addDataType(DataType dt)

addCategory

public void addCategory(CategoryPath path)

createProgramTree

public void createProgramTree(String treeName)
                       throws Exception

Throws:

Exception

createFragment

public void createFragment(String treeName,
 String modulePath,
 String fragmentName,
 String startAddr,
 String endAddr)
                    throws Exception

Throws:

Exception

getOrCreateModule

public ProgramModule getOrCreateModule(String treeName,
 String modulePath)
                                throws Exception

Throws:

Exception

createEquate

public Equate createEquate(String address,
 String name,
 long value,
 int opIndex)

createComment

@Deprecated(forRemoval=true,
            since="11.4")
public void createComment(String address,
 String comment,
 int commentType)

Deprecated, for removal: This API element is subject to removal in a future version.

createComment

public void createComment(String address,
 String comment,
 CommentType commentType)

createFunctionComment

public void createFunctionComment(String entryPointAddress,
 String comment)

setFallthrough

public void setFallthrough(String from,
 String to)

createExternalLibraries

public void createExternalLibraries(String... libraryNames)
                             throws Exception

Throws:

Exception

bindExternalLibrary

public void bindExternalLibrary(String libraryName,
 String pathname)
                         throws Exception

Throws:

Exception

createExternalReference

public void createExternalReference(String fromAddress,
 String libraryName,
 String externalLabel,
 int opIndex)
                             throws Exception

Throws:

Exception

createExternalReference

public void createExternalReference(String fromAddress,
 String libraryName,
 String externalLabel,
 String extAddress,
 int opIndex)
                             throws Exception

Throws:

Exception

createExternalReference

public void createExternalReference(String fromAddress,
 String libraryName,
 String externalLabel,
 String extAddress,
 int opIndex,
 RefType refType,
 SourceType sourceType)
                             throws Exception

Throws:

Exception

createExternalFunction

public ExternalLocation createExternalFunction(String extAddress,
 String libName,
 String functionName)
                                        throws Exception

Throws:

Exception

createExternalFunction

public ExternalLocation createExternalFunction(String extAddress,
 String libName,
 String functionName,
 String originalName)
                                        throws Exception

Throws:

Exception

createLocalVariable

public void createLocalVariable(Function function,
 String name,
 DataType dt,
 int stackOffset)
                         throws Exception

Throws:

Exception

setRegisterValue

public void setRegisterValue(String registerName,
 String startAddress,
 String endAddress,
 long value)
                      throws Exception

Throws:

Exception

setIntProperty

public void setIntProperty(String address,
 String propertyName,
 int value)
                    throws Exception

Throws:

Exception

setStringProperty

public void setStringProperty(String address,
 String propertyName,
 String value)
                       throws Exception

Throws:

Exception

setObjectProperty

public void setObjectProperty(String address,
 String propertyName,
 Saveable value)
                       throws Exception

Throws:

Exception

setChanged

public void setChanged(boolean changed)

createFileBytes

public FileBytes createFileBytes(int size)
                          throws Exception

Throws:

Exception

tx

public <E extends Exception> void tx(ExceptionalCallback<E> c)

tx

public <R,
E extends Exception> R tx(ProgramBuilder.ExceptionalSupplier<R,E> s)