Package ghidra.app.util.opinion

Class AbstractProgramLoader

java.lang.Object

ghidra.app.util.opinion.AbstractProgramLoader

All Implemented Interfaces:

Loader, ExtensionPoint, java.lang.Comparable<Loader>

Direct Known Subclasses:

AbstractLibrarySupportLoader, BinaryLoader, IntelHexLoader, MotorolaHexLoader, XmlLoader

public abstract class AbstractProgramLoader
extends java.lang.Object
implements Loader

An abstract Loader that provides a framework to conveniently load Programs. Subclasses are responsible for the actual load.

This Loader provides a couple processor-related options, as all Programs will have a processor associated with them.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	ANCHOR_LABELS_OPTION_NAME
static java.lang.String	APPLY_LABELS_OPTION_NAME

Fields inherited from interface ghidra.app.util.opinion.Loader

COMMAND_LINE_ARG_PREFIX

Constructor Summary

Constructors

Constructor	Description
AbstractProgramLoader()

Method Summary

Modifier and Type	Method	Description
protected void	createDefaultMemoryBlocks(Program program, Language language, MessageLog log)	Creates default memory blocks for the given Program.
protected Program	createProgram(ByteProvider provider, java.lang.String programName, Address imageBase, java.lang.String executableFormatName, Language language, CompilerSpec compilerSpec, java.lang.Object consumer)	Creates a Program with the specified attributes.
protected java.lang.String	generateBlockName(Program program, boolean isOverlay, AddressSpace space)	Generates a block name.
java.util.List<Option>	getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean isLoadIntoProgram)	Gets the default Loader options.
protected LanguageService	getLanguageService()	Gets the Loader's language service.
java.util.List<DomainObject>	load(ByteProvider provider, java.lang.String name, DomainFolder folder, LoadSpec loadSpec, java.util.List<Option> options, MessageLog messageLog, java.lang.Object consumer, TaskMonitor monitor)	Loads bytes in a particular format as a new DomainObject.
boolean	loadInto(ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor)	Loads bytes into the specified Program.
protected abstract java.util.List<Program>	loadProgram(ByteProvider provider, java.lang.String programName, DomainFolder programFolder, LoadSpec loadSpec, java.util.List<Option> options, MessageLog log, java.lang.Object consumer, TaskMonitor monitor)	Loads program bytes in a particular format as a new Program.
protected abstract boolean	loadProgramInto(ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor)	Loads program bytes into the specified Program.
static void	markAsFunction(Program program, java.lang.String name, Address funcStart)	Mark this address as a function by creating a one byte function.
protected void	postLoadProgramFixups(java.util.List<Program> loadedPrograms, DomainFolder folder, java.util.List<Option> options, MessageLog messageLog, TaskMonitor monitor)	This gets called after the given list of Programs is finished loading.
protected void	release(java.util.List<? extends DomainObject> domainObjects, java.lang.Object consumer)	Releases the given consumer from each of the provided DomainObjects.
protected boolean	shouldApplyProcessorLabelsByDefault()	Returns whether or not processor labels should be applied by default.
java.lang.String	validateOptions(ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, Program program)	Validates the Loader's options and returns null if all options are valid; otherwise, an error message describing the problem is returned.

Methods inherited from class java.lang.Object

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

Methods inherited from interface ghidra.app.util.opinion.Loader

compareTo, findSupportedLoadSpecs, getName, getPreferredFileName, getTier, getTierPriority, supportsLoadIntoProgram

Field Detail

APPLY_LABELS_OPTION_NAME

public static final java.lang.String APPLY_LABELS_OPTION_NAME

See Also:

Constant Field Values

ANCHOR_LABELS_OPTION_NAME

public static final java.lang.String ANCHOR_LABELS_OPTION_NAME

See Also:

Constant Field Values

Constructor Detail

AbstractProgramLoader

public AbstractProgramLoader()

Method Detail

loadProgram

protected abstract java.util.List<Program> loadProgram(ByteProvider provider,
                                                       java.lang.String programName,
                                                       DomainFolder programFolder,
                                                       LoadSpec loadSpec,
                                                       java.util.List<Option> options,
                                                       MessageLog log,
                                                       java.lang.Object consumer,
                                                       TaskMonitor monitor)
                                                throws java.io.IOException,
                                                       CancelledException

Loads program bytes in a particular format as a new Program. Multiple Programs may end up getting created, depending on the nature of the format.

Parameters:

provider - The bytes to load.

programName - The name of the Program that's being loaded.

programFolder - The DomainFolder where the loaded thing should be saved. Could be null if the thing should not be pre-saved.

loadSpec - The LoadSpec to use during load.

options - The load options.

log - The message log.

consumer - A consumer object for Programs generated.

monitor - A cancelable task monitor.

Returns:

A list of loaded Programs (element 0 corresponds to primary loaded Program).

Throws:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

loadProgramInto

protected abstract boolean loadProgramInto(ByteProvider provider,
                                           LoadSpec loadSpec,
                                           java.util.List<Option> options,
                                           MessageLog messageLog,
                                           Program program,
                                           TaskMonitor monitor)
                                    throws java.io.IOException,
                                           CancelledException

Loads program bytes into the specified Program. This method will not create any new Programs. It is only for adding to an existing Program.

NOTE: The loading that occurs in this method will automatically be done in a transaction.

Parameters:

provider - The bytes to load into the Program.

loadSpec - The LoadSpec to use during load.

options - The load options.

messageLog - The message log.

program - The Program to load into.

monitor - A cancelable task monitor.

Returns:

True if the file was successfully loaded; otherwise, false.

Throws:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

load

public final java.util.List<DomainObject> load(ByteProvider provider,
                                               java.lang.String name,
                                               DomainFolder folder,
                                               LoadSpec loadSpec,
                                               java.util.List<Option> options,
                                               MessageLog messageLog,
                                               java.lang.Object consumer,
                                               TaskMonitor monitor)
                                        throws java.io.IOException,
                                               CancelledException,
                                               InvalidNameException,
                                               DuplicateNameException,
                                               VersionException

Description copied from interface: Loader

Loads bytes in a particular format as a new DomainObject. Multiple DomainObjects may end up getting created, depending on the nature of the format.

Specified by:

load in interface Loader

Parameters:

provider - The bytes to load.

name - The name of the thing that's being loaded.

folder - The DomainFolder where the loaded thing should be saved. Could be null if the thing should not be pre-saved.

loadSpec - The LoadSpec to use during load.

options - The load options.

messageLog - The message log.

consumer - A consumer object for DomainObject generated.

monitor - A cancelable task monitor.

Returns:

A list of loaded DomainObjects (element 0 corresponds to primary loaded object).

Throws:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

InvalidNameException - if an invalid DomainObject name was used during load.

DuplicateNameException - if the load resulted in a naming conflict with the DomainObject.

VersionException - if there was an issue with database versions, probably due to a failed language upgrade.

loadInto

public final boolean loadInto(ByteProvider provider,
                              LoadSpec loadSpec,
                              java.util.List<Option> options,
                              MessageLog messageLog,
                              Program program,
                              TaskMonitor monitor)
                       throws java.io.IOException,
                              CancelledException

Description copied from interface: Loader

Loads bytes into the specified Program. This method will not create any new Programs. It is only for adding to an existing Program.

Specified by:

loadInto in interface Loader

Parameters:

provider - The bytes to load into the Program.

loadSpec - The LoadSpec to use during load.

options - The load options.

messageLog - The message log.

program - The Program to load into.

monitor - A cancelable task monitor.

Returns:

True if the file was successfully loaded; otherwise, false.

Throws:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

getDefaultOptions

public java.util.List<Option> getDefaultOptions(ByteProvider provider,
                                                LoadSpec loadSpec,
                                                DomainObject domainObject,
                                                boolean isLoadIntoProgram)

Description copied from interface: Loader

Gets the default Loader options.

Specified by:

getDefaultOptions in interface Loader

Parameters:

provider - The bytes of the thing being loaded.

loadSpec - The LoadSpec.

domainObject - The DomainObject being loaded.

isLoadIntoProgram - True if the load is adding to an existing DomainObject; otherwise, false.

Returns:

A list of the Loader's default options.

validateOptions

public java.lang.String validateOptions(ByteProvider provider,
                                        LoadSpec loadSpec,
                                        java.util.List<Option> options,
                                        Program program)

Description copied from interface: Loader

Validates the Loader's options and returns null if all options are valid; otherwise, an error message describing the problem is returned.

Specified by:

validateOptions in interface Loader

Parameters:

provider - The bytes of the thing being loaded.

loadSpec - The proposed LoadSpec.

options - The list of Options to validate.

program - existing program if the loader is adding to an existing program. If it is a fresh import, then this will be null.

Returns:

null if all Options are valid; otherwise, an error message describing the problem is returned.

postLoadProgramFixups

protected void postLoadProgramFixups(java.util.List<Program> loadedPrograms,
                                     DomainFolder folder,
                                     java.util.List<Option> options,
                                     MessageLog messageLog,
                                     TaskMonitor monitor)
                              throws CancelledException,
                                     java.io.IOException

This gets called after the given list of Programs is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.

Parameters:

loadedPrograms - The Programs that got loaded.

folder - The folder the programs were loaded to.

options - The load options.

messageLog - The message log.

monitor - A cancelable task monitor.

Throws:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

shouldApplyProcessorLabelsByDefault

protected boolean shouldApplyProcessorLabelsByDefault()

Returns whether or not processor labels should be applied by default. Most loaders will not need to override this method because they will not want the labels applied by default.

Returns:

Whether or not processor labels should be applied by default.

generateBlockName

protected java.lang.String generateBlockName(Program program,
                                             boolean isOverlay,
                                             AddressSpace space)

Generates a block name.

Parameters:

program - The Program for the block.

isOverlay - true if the block is an overlay; use "ov" in the name.

space - The AddressSpace for the block.

Returns:

The generated block name.

createProgram

protected Program createProgram(ByteProvider provider,
                                java.lang.String programName,
                                Address imageBase,
                                java.lang.String executableFormatName,
                                Language language,
                                CompilerSpec compilerSpec,
                                java.lang.Object consumer)
                         throws java.io.IOException

Creates a Program with the specified attributes.

Parameters:

provider - The bytes that will make up the Program.

programName - The name of the Program.

imageBase - The image base address of the Program.

executableFormatName - The file format name of the Program. Typically this will be the Loader name.

language - The Language of the Program.

compilerSpec - The CompilerSpec of the Program.

consumer - A consumer object for the Program generated.

Returns:

The newly created Program.

Throws:

java.io.IOException - if there was an IO-related problem with creating the Program.

createDefaultMemoryBlocks

protected void createDefaultMemoryBlocks(Program program,
                                         Language language,
                                         MessageLog log)

Creates default memory blocks for the given Program.

Parameters:

program - The Program to create default memory blocks for.

language - The Programs Language.

log - The log to use during memory block creation.

markAsFunction

public static void markAsFunction(Program program,
                                  java.lang.String name,
                                  Address funcStart)

Mark this address as a function by creating a one byte function. The single byte body function is picked up by the function analyzer, disassembled, and the body fixed. Marking the function this way keeps disassembly and follow on analysis out of the loaders.

Parameters:

program - the program

name - name of function, null if name not known

funcStart - starting address of the function

getLanguageService

protected LanguageService getLanguageService()

Gets the Loader's language service.

The default behavior of this method is to return the DefaultLanguageService.

Returns:

The Loader's language service.

release

protected final void release(java.util.List<? extends DomainObject> domainObjects,
                             java.lang.Object consumer)

Releases the given consumer from each of the provided DomainObjects.

Parameters:

domainObjects - A list of DomainObjects which are no longer being used.

consumer - The consumer that was marking the DomainObjects as being used.