Package ghidra.app.util.opinion

Class AbstractProgramLoader

java.lang.Object

ghidra.app.util.opinion.AbstractProgramLoader

All Implemented Interfaces:

Loader, ExtensionPoint, Comparable<Loader>

Direct Known Subclasses:

AbstractLibrarySupportLoader, AbstractProgramWrapperLoader, BinaryLoader, DecompileDebugXmlLoader, IntelHexLoader, MotorolaHexLoader, XmlLoader

public abstract class AbstractProgramLoader
extends 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.

Nested Class Summary

Nested classes/interfaces inherited from interface ghidra.app.util.opinion.Loader

Loader.ImporterSettings

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ANCHOR_LABELS_OPTION_NAME
static final String	APPLY_LABELS_OPTION_NAME

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

COMMAND_LINE_ARG_PREFIX, loggingDisabled, OPTIONS_PROJECT_SAVE_STATE_KEY

Constructor Summary

Constructors

Constructor	Description
AbstractProgramLoader()

Method Summary

Modifier and Type	Method	Description
static Address	addExternalBlock(Program program, long size, MessageLog log)	Adds the EXERNAL block to memory, or adds to an existing one
protected void	createDefaultMemoryBlocks(Program program, Loader.ImporterSettings settings)	Creates default memory blocks for the given Program.
protected Program	createProgram(Loader.ImporterSettings settings)	Creates a Program with the specified attributes at the LoadSpec's desired image base
protected Program	createProgram(Address imageBase, Loader.ImporterSettings settings)	Creates a Program with the specified attributes.
protected String	generateBlockName(Program program, boolean isOverlay, AddressSpace space)	Generates a block name.
List<Option>	getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram, boolean mirrorFsLayout)	Gets the default Loader options.
protected LanguageService	getLanguageService()	Gets the Loader's language service.
final LoadResults<? extends DomainObject>	load(Loader.ImporterSettings settings)	Loads bytes in a particular format as a new Loaded DomainObject.
final void	loadInto(Program program, Loader.ImporterSettings settings)	Loads bytes into the specified Program.
protected abstract List<Loaded<Program>>	loadProgram(Loader.ImporterSettings settings)	Loads bytes in a particular format as a new Loaded Program.
protected abstract void	loadProgramInto(Program program, Loader.ImporterSettings settings)	Loads program bytes into the specified Program.
static void	markAsFunction(Program program, String name, Address funcStart)	Mark this address as a function by creating a one byte function.
protected void	postLoadCleanup(boolean success)	This gets called as the final step of the load process.
protected void	postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Loader.ImporterSettings settings)	This gets called after the given list of loaded programss is finished loading.
static void	setProgramProperties(Program prog, ByteProvider provider, String executableFormatName)	Sets a program's Executable Path, Executable Format, MD5, SHA256, and FSRL properties.
protected boolean	shouldApplyProcessorLabelsByDefault()	Returns whether or not processor labels should be applied by default.
String	validateOptions(ByteProvider provider, LoadSpec loadSpec, 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, loadsIntoNewFolder, supportsLoadIntoProgram, supportsLoadIntoProgram

Field Details

APPLY_LABELS_OPTION_NAME

public static final String APPLY_LABELS_OPTION_NAME

See Also:

• Constant Field Values

ANCHOR_LABELS_OPTION_NAME

public static final String ANCHOR_LABELS_OPTION_NAME

See Also:

• Constant Field Values

Constructor Details

AbstractProgramLoader

public AbstractProgramLoader()

Method Details

loadProgram

protected abstract List<Loaded<Program>> loadProgram(Loader.ImporterSettings settings)
                                              throws IOException,
LoadException,
CancelledException

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

Note that when the load completes, the returned Loaded Programs are not saved to a project. That is the responsibility of the caller (see Loaded.save(TaskMonitor)).

It is also the responsibility of the caller to close the returned Loaded Programs with Loaded.close() when they are no longer needed.

Parameters:

settings - The Loader.ImporterSettings.

Returns:

A List of one or more Loaded Programs (created but not saved).

Throws:

LoadException - if the load failed in an expected way.

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

CancelledException - if the user cancelled the load.

loadProgramInto

protected abstract void loadProgramInto(Program program,
 Loader.ImporterSettings settings)
                                 throws IOException,
LoadException,
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:

program - The Program to load into.

settings - The Loader.ImporterSettings.

Throws:

LoadException - if the load failed in an expected way.

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

CancelledException - if the user cancelled the load.

load

public final LoadResults<? extends DomainObject> load(Loader.ImporterSettings settings)
                                               throws IOException,
CancelledException,
VersionException,
LoadException

Description copied from interface: Loader

Loads bytes in a particular format as a new Loaded DomainObject. Multiple DomainObjects may end up getting created, depending on the nature of the format. The Loaded DomainObjects are bundled together in a LoadResults object which provides convenience methods to operate on the entire group of Loaded DomainObjects.

Note that when the load completes, the returned Loaded DomainObjects are not saved to a project. That is the responsibility of the caller (see LoadResults.save(TaskMonitor)).

It is also the responsibility of the caller to close the returned Loaded DomainObjects with LoadResults.close() when they are no longer needed.

Specified by:

load in interface Loader

Parameters:

settings - The Loader.ImporterSettings.

Returns:

The LoadResults which contains one or more Loaded DomainObjects (created but not saved).

Throws:

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

CancelledException - if the user cancelled the load.

VersionException - if the load process tried to open an existing DomainFile which was created with a newer or unsupported version of Ghidra

LoadException - if the load failed in an expected way

loadInto

public final void loadInto(Program program,
 Loader.ImporterSettings settings)
                    throws IOException,
LoadException,
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:

program - The Program to load into.

settings - The Loader.ImporterSettings.

Throws:

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

LoadException - if the load failed in an expected way.

CancelledException - if the user cancelled the load.

getDefaultOptions

public List<Option> getDefaultOptions(ByteProvider provider,
 LoadSpec loadSpec,
 DomainObject domainObject,
 boolean loadIntoProgram,
 boolean mirrorFsLayout)

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.

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

mirrorFsLayout - True if the filesystem layout should be mirrored when loading; otherwise, false

Returns:

A list of the Loader's default options.

validateOptions

public String validateOptions(ByteProvider provider,
 LoadSpec loadSpec,
 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(List<Loaded<Program>> loadedPrograms,
 Loader.ImporterSettings settings)
                              throws CancelledException,
IOException

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

Parameters:

loadedPrograms - The loaded programs to be fixed up.

settings - The Loader.ImporterSettings.

Throws:

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

CancelledException - if the user cancelled the load.

postLoadCleanup

protected void postLoadCleanup(boolean success)

This gets called as the final step of the load process. Subclasses may override it to ensure any resources they created can be cleaned up after the load finishes.

NOTE: Subclasses should not use this method to release any Programs they created when failure occurs. That should be done by the subclass as soon as it detects failure has occurred.

Parameters:

success - True if the load completed successfully; otherwise, false

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 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(Address imageBase,
 Loader.ImporterSettings settings)
                         throws IOException

Creates a Program with the specified attributes.

Parameters:

imageBase - The image base address of the Program.

settings - The Loader.ImporterSettings.

Returns:

The newly created Program.

Throws:

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

createProgram

protected Program createProgram(Loader.ImporterSettings settings)
                         throws IOException

Creates a Program with the specified attributes at the LoadSpec's desired image base

Parameters:

settings - The Loader.ImporterSettings.

Returns:

The newly created Program.

Throws:

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

setProgramProperties

public static void setProgramProperties(Program prog,
 ByteProvider provider,
 String executableFormatName)
                                 throws IOException

Sets a program's Executable Path, Executable Format, MD5, SHA256, and FSRL properties.

Parameters:

prog - Program (with active transaction)

provider - ByteProvider that the program was created from

executableFormatName - executable format string

Throws:

IOException - if error reading from ByteProvider

createDefaultMemoryBlocks

protected void createDefaultMemoryBlocks(Program program,
 Loader.ImporterSettings settings)

Creates default memory blocks for the given Program.

Parameters:

program - The Program to create default memory blocks for.

settings - The Loader.ImporterSettings.

markAsFunction

public static void markAsFunction(Program program,
 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

addExternalBlock

public static Address addExternalBlock(Program program,
 long size,
 MessageLog log)
                                throws Exception

Adds the EXERNAL block to memory, or adds to an existing one

Parameters:

program - The Program

size - The desired size of the new EXTERNAL block

log - The MessageLog

Returns:

The Address of the new (or new piece) of EXTERNAL block

Throws:

Exception - if there was an issue creating or adding to the EXTERNAL block

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.