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, 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.

  • Field Details

  • Constructor Details

    • AbstractProgramLoader

      public AbstractProgramLoader()

  • Method Details

    • loadProgram

      protected abstract List<Loaded<Program>> loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) 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(Project, MessageLog, TaskMonitor)).

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

      Parameters:
      provider - The bytes to load.
      loadedName - A suggested name for the primary Loaded Program. This is just a suggestion, and a Loader implementation reserves the right to change it. The Loaded Programs should be queried for their true names using Loaded.getName().
      project - The Project. Loaders can use this to take advantage of existing DomainFolders and DomainFiles to do custom behaviors such as loading libraries. Could be null if there is no project.
      projectFolderPath - A suggested project folder path for the Loaded Programs. This is just a suggestion, and a Loader implementation reserves the right to change it for each Loaded result. The Loaded Programs should be queried for their true project folder paths using Loaded.getProjectFolderPath().
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      log - The message log.
      consumer - A consumer object for generated Programs.
      monitor - A task monitor.
      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(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor) 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:
      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.
      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(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Object consumer, TaskMonitor monitor) 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(Project, Object, MessageLog, TaskMonitor)).

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

      Specified by:
      load in interface Loader
      Parameters:
      provider - The bytes to load.
      loadedName - A suggested name for the primary Loaded DomainObject. This is just a suggestion, and a Loader implementation reserves the right to change it. The LoadResults should be queried for their true names using Loaded.getName().
      project - The Project. Loaders can use this to take advantage of existing DomainFolders and DomainFiles to do custom behaviors such as loading libraries. Could be null if there is no project.
      projectFolderPath - A suggested project folder path for the Loaded DomainObjects. This is just a suggestion, and a Loader implementation reserves the right to change it for each Loaded result. The LoadResults should be queried for their true project folder paths using Loaded.getProjectFolderPath().
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      messageLog - The message log.
      consumer - A consumer object for generated DomainObjects.
      monitor - A task monitor.
      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(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor) 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:
      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.
      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 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 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, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor) 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.
      project - The Project to load into. Could be null if there is no project.
      options - The load options.
      messageLog - The message log.
      monitor - A cancelable task monitor.
      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.

    • concatenatePaths

      protected String concatenatePaths(String... pathElements)
      Concatenates the given path elements to form a single path. Empty and null path elements are ignored.
      Parameters:
      pathElements - The path elements to append to one another
      Returns:
      A single path consisting of the given path elements appended together

    • 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(ByteProvider provider, String domainFileName, Address imageBase, String executableFormatName, Language language, CompilerSpec compilerSpec, Object consumer) throws IOException
      Creates a Program with the specified attributes.
      Parameters:
      provider - The bytes that will make up the Program.
      domainFileName - The name for the DomainFile that will store 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:
      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, 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, 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(List<Loaded<Program>> loadedPrograms, Object consumer)
      Releases the given consumer from each of the provided loaded programs
      Parameters:
      loadedPrograms - A list of loaded programs which are no longer being used
      consumer - The consumer that was marking the Programs as being used