Package ghidra.program.disassemble

Class Disassembler

java.lang.Object
ghidra.program.disassemble.Disassembler
All Implemented Interfaces:
DisassemblerConflictHandler
public class Disassembler extends Object implements DisassemblerConflictHandler
Class to perform disassembly. Contains the logic to follow instruction flows to continue the disassembly. 17-Nov-2008: moved to ghidra.program.disassemble package since this is now used during language upgrades which may occur during construction of ProgramDB. 12-Dec-2012: major refactor of disassembly to perform bulk add of instructions to program to avoid context related conflicts

  • Field Details

    • MARK_BAD_INSTRUCTION_PROPERTY

      public static final String MARK_BAD_INSTRUCTION_PROPERTY
      MARK_BAD_INSTRUCTION_PROPERTY Program Disassembler property enables marking of instruction disassembly errors. Boolean property is defined within the Disassembler property list, see Program.DISASSEMBLER_PROPERTIES.
      See Also:

    • MARK_UNIMPL_PCODE_PROPERTY

      public static final String MARK_UNIMPL_PCODE_PROPERTY
      MARK_UNIMPL_PCODE_PROPERTY Program Disassembler property enables marking of instructions which are missing their pcode implementation. Boolean property is defined within the Disassembler property list, see Program.DISASSEMBLER_PROPERTIES.
      See Also:

    • RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY

      public static final String RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY
      RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY Program Disassembler property restricts disassembly to executable memory only. Boolean property is defined within the Disassembler property list, see Program.DISASSEMBLER_PROPERTIES.
      See Also:

    • ERROR_BOOKMARK_CATEGORY

      public static final String ERROR_BOOKMARK_CATEGORY
      See Also:

    • UNIMPL_BOOKMARK_CATEGORY

      public static final String UNIMPL_BOOKMARK_CATEGORY
      See Also:

    • MAX_REPEAT_PATTERN_LENGTH

      public static final int MAX_REPEAT_PATTERN_LENGTH
      See Also:

    • language

      protected final Language language

    • addrFactory

      protected final AddressFactory addrFactory

    • baseContextRegister

      protected final Register baseContextRegister

    • parallelHelper

      protected final ParallelInstructionLanguageHelper parallelHelper

    • disassemblerProgramContext

      protected Disassembler.DisassemblerProgramContext disassemblerProgramContext

    • disassemblerContext

      protected DisassemblerContextImpl disassemblerContext

    • bmMgr

      protected BookmarkManager bmMgr

    • doMarkBadInstructions

      protected boolean doMarkBadInstructions

  • Constructor Details

    • Disassembler

      protected Disassembler(Program program, TaskMonitor monitor, DisassemblerMessageListener listener)
      Disassembler constructor. The following Program options are used during disassbly:
      Parameters:
      program - the program to be disassembled.
      monitor - progress monitor
      listener - object to notify of disassembly messages.

    • Disassembler

      protected Disassembler(Language language, AddressFactory addrFactory, TaskMonitor monitor, DisassemblerMessageListener listener)
      Disassembler constructor. Intended for block pseudo-disassembly use only. NOTE: Executable memory restriction is not provided but should possibly be considered by any use of the resulting instance.
      Parameters:
      language - processor language
      addrFactory - address factory
      monitor - progress monitor
      listener - object to notify of disassembly messages.

    • Disassembler

      protected Disassembler(Program program, boolean markBadInstructions, boolean markUnimplementedPcode, boolean restrictToExecuteMemory, TaskMonitor monitor, DisassemblerMessageListener listener)
      Disassembler constructor
      Parameters:
      program - the program to be disassembled.
      markBadInstructions - if true bad instructions will be marked
      markUnimplementedPcode - if true instructions with unimplemented pcode will be marked
      restrictToExecuteMemory - if true disassembly will only be permitted with executable memory blocks
      monitor - progress monitor
      listener - object to notify of disassembly messages.

  • Method Details

    • getDisassembler

      public static Disassembler getDisassembler(Program program, TaskMonitor monitor, DisassemblerMessageListener listener)
      Get a suitable disassembler instance. The following Program options are used during disassbly:
      Parameters:
      program - the program to be disassembled.
      monitor - progress monitor
      listener - object to notify of disassembly messages.
      Returns:
      a disassembler ready to disassemble

    • getDisassembler

      public static Disassembler getDisassembler(Language language, AddressFactory addrFactory, TaskMonitor monitor, DisassemblerMessageListener listener)
      Get a suitable disassembler instance. Intended for block pseudo-disassembly use only when the method pseudoDisassembleBlock(MemBuffer, RegisterValue, int) is used. NOTE: Executable memory restriction is not provided but should possibly be considered by any use of the resulting instance.
      Parameters:
      language - processor language
      addrFactory - address factory
      monitor - progress monitor
      listener - object to notify of disassembly messages.
      Returns:
      a disassembler ready to disassemble

    • getDisassembler

      public static Disassembler getDisassembler(Program program, boolean markBadInstructions, boolean markUnimplementedPcode, boolean restrictToExecuteMemory, TaskMonitor monitor, DisassemblerMessageListener listener)
      Get a suitable disassembler instance.
      Parameters:
      program - the program to be disassembled.
      markBadInstructions - if true bad instructions will be marked
      markUnimplementedPcode - if true instructions with unimplemented pcode will be marked
      restrictToExecuteMemory - if true disassembly will only be permitted with executable memory blocks
      monitor - progress monitor
      listener - object to notify of disassembly messages.
      Returns:
      a disassembler ready to disassemble

    • setSeedContext

      public void setSeedContext(DisassemblerContextImpl seedContext)
      Set seed context which will be used to establish initial context at starting points which are not arrived at via a natural disassembly flow. A null value will disable use of any previously set seed context
      Parameters:
      seedContext - initial context for disassembly

    • setRepeatPatternLimit

      public void setRepeatPatternLimit(int maxInstructions)
      Set the maximum number of instructions in a single run which contain the same byte values. Disassembly flow will stop and be flagged when this threshold is encountered. This check is set to MAX_REPEAT_PATTERN_LENGTH by default, and can be disabled by setting a value of -1 NOTE: This restriction will only work for those cases where a given repeated byte results in an instruction which has a fall-through.
      Parameters:
      maxInstructions - limit on the number of consecutive instructions with the same byte values

    • setRepeatPatternLimitIgnored

      public void setRepeatPatternLimitIgnored(AddressSetView set)
      Set the region over which the repeat pattern limit will be ignored. This allows areas which have been explicitly disassembled to be free of bad bookmarks caused by the repeat pattern limit being exceeded.
      Parameters:
      set - region over which the repeat pattern limit will be ignored

    • isMarkBadDisassemblyOptionEnabled

      public static boolean isMarkBadDisassemblyOptionEnabled(Program program)
      Parameters:
      program - the program to check
      Returns:
      true if program MARK_BAD_INSTRUCTION_PROPERTY has been enabled

    • isMarkUnimplementedPcodeOptionEnabled

      public static boolean isMarkUnimplementedPcodeOptionEnabled(Program program)
      Parameters:
      program - the program to check
      Returns:
      true if program MARK_UNIMPL_PCODE_PROPERTY has been enabled

    • isRestrictToExecuteMemory

      public static boolean isRestrictToExecuteMemory(Program program)
      Parameters:
      program - the program to check
      Returns:
      true if program RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY has been enabled

    • disassemble

      public AddressSet disassemble(AddressSetView startSet, AddressSetView restrictedSet, boolean doFollowFlow)
      Attempt disassembly of all undefined code units within the specified set of addresses. NOTE: A single instance of this Disassembler does not support concurrent invocations of the various disassemble methods. Disassembler must be instantiated with a Program object.
      Parameters:
      startSet - the minimum set of addresses to disassemble
      restrictedSet - the set of addresses that disassembling is restricted to (may be null)
      doFollowFlow - flag to follow references while disassembling.
      Returns:
      the set of addresses that were disassembled.

    • disassemble

      public AddressSet disassemble(AddressSetView startSet, AddressSetView restrictedSet, RegisterValue initialContextValue, boolean doFollowFlow)
      Attempt disassembly of all undefined code units within the specified set of addresses. NOTE: A single instance of this Disassembler does not support concurrent invocations of the various disassemble methods. Disassembler must be instantiated with a Program object.
      Parameters:
      startSet - the minimum set of addresses to disassemble
      restrictedSet - the set of addresses that disassembling is restricted to (may be null)
      initialContextValue - initial context value to be applied at the startAddr. If not null this value will take precedence when combined with any seed value or program context.
      doFollowFlow - flag to follow references while disassembling.
      Returns:
      the set of addresses that were disassembled.

    • disassemble

      public AddressSet disassemble(Address startAddr, AddressSetView restrictedSet)
      Disassembles code starting at startAddr and restricted to addrSet. NOTE: A single instance of this Disassembler does not support concurrent invocations of the various disassemble methods. Disassembler must be instantiated with a Program object.
      Parameters:
      startAddr - the address to begin disassembling.
      restrictedSet - the set of addresses that disassembling is restricted to.
      Returns:
      AddressSet the set of addresses that were disassembled.

    • disassemble

      public AddressSet disassemble(Address startAddr, AddressSetView restrictedSet, boolean doFollowFlow)
      Disassembles code starting at startAddr and restricted to addrSet. NOTE: A single instance of this Disassembler does not support concurrent invocations of the various disassemble methods. Disassembler must be instantiated with a Program object.
      Parameters:
      startAddr - the address to begin disassembling.
      restrictedSet - the set of addresses that disassembling is restricted to.
      doFollowFlow - flag to follow references while disassembling.
      Returns:
      AddressSet the set of addresses that were disassembled.

    • disassemble

      public AddressSet disassemble(Address startAddr, AddressSetView restrictedSet, RegisterValue initialContextValue, boolean doFollowFlow)
      Disassembles code starting at startAddr and restricted to addrSet. NOTE: A single instance of this Disassembler does not support concurrent invocations of the various disassemble methods. Disassembler must be instantiated with a Program object.
      Parameters:
      startAddr - the address to begin disassembling.
      restrictedSet - the set of addresses that disassembling is restricted to.
      initialContextValue - initial context value to be applied at the startAddr. If not null this value will take precedence when combined with any seed value or program context.
      doFollowFlow - flag to follow references while disassembling.
      Returns:
      AddressSet the set of addresses that were disassembled.

    • resetDisassemblerContext

      public void resetDisassemblerContext()
      Clear any retained context state which may have been accumulated. Use of this method is only needed when using the pseudoDisassembleBlock method over an extended code range to avoid excessive in-memory state accumulation.

    • pseudoDisassembleBlock

      public InstructionBlock pseudoDisassembleBlock(Address addr, RegisterValue defaultContextValue, int limit)
      Perform a pseudo-disassembly of an single instruction block only following fall-throughs. WARNING! This method should not be used in conjunction with other disassembly methods on the this Disassembler instance. Disassembler must be instantiated with a Program object.
      Parameters:
      addr - start of block
      defaultContextValue - starting context to use if no context has previously been established for the specified startAddr
      limit - maximum number of instructions to disassemble
      Returns:
      instruction block of pseudo-instructions

    • pseudoDisassembleBlock

      public InstructionBlock pseudoDisassembleBlock(MemBuffer blockMemBuffer, RegisterValue defaultContextValue, int limit)
      Perform a pseudo-disassembly of an single instruction block only following fall-throughs. WARNING! This method should not be used in conjunction with other disassembly methods on the this Disassembler instance.
      Parameters:
      blockMemBuffer - block memory buffer
      defaultContextValue - starting context to use if no context has previously been established for the specified startAddr
      limit - maximum number of instructions to disassemble
      Returns:
      instruction block of pseudo-instructions or null if minimum address of blockMemBuffer is not properly aligned for instruction parsing.

    • disassembleInstructionBlock

      protected void disassembleInstructionBlock(InstructionBlock block, MemBuffer blockMemBuffer, Address flowFrom, int limit, InstructionSet instructionSet, boolean skipIfBlockAlreadyDisassembled)

    • adjustPreParseContext

      protected void adjustPreParseContext(MemBuffer instrMemBuffer) throws UnknownInstructionException
      Adjust disassembler context prior to disassembly of a new instruction.
      Parameters:
      instrMemBuffer - buffer for bytes from memory
      Throws:
      UnknownInstructionException - if instruction is invalid

    • getPseudoInstruction

      protected PseudoInstruction getPseudoInstruction(Address addr, InstructionPrototype prototype, MemBuffer memBuffer, RegisterValue contextValue, InstructionBlock block) throws AddressOverflowException
      Throws:
      AddressOverflowException

    • isBlockTerminationOK

      protected boolean isBlockTerminationOK(Instruction instr)

    • processInstruction

      protected Address processInstruction(PseudoInstruction inst, MemBuffer blockMemBuffer, InstructionBlock block, InstructionSet instructionSet) throws InsufficientBytesException, UnknownInstructionException, AddressOverflowException, NestedDelaySlotException
      Process a new instruction which has just been parsed. This method is responsible for adding the instruction to the current block as well as any delay-slotted instructions. This method may be overridden and the instruction re-parsed if necessary.
      Parameters:
      inst - instruction to process
      blockMemBuffer - buffer to get bytes
      block - current block of instructions
      instructionSet - address set of current instructions in block
      Returns:
      instruction fallthrough address or null if no fallthrough
      Throws:
      InsufficientBytesException - if a memory error occurs during instruction processing
      UnknownInstructionException - if an error occurs during a modified re-parse of the instruction.
      AddressOverflowException - if address goes out of address space
      NestedDelaySlotException - if delay slot found in a delay slot

    • markInstructionError

      public void markInstructionError(InstructionError conflict)
      Specified by:
      markInstructionError in interface DisassemblerConflictHandler

    • markUnimplementedPcode

      public static void markUnimplementedPcode(Program program, AddressSetView addressSet, TaskMonitor monitor) throws CancelledException
      Mark all instructions with unimplemented pcode over the specified address set
      Parameters:
      program - to mark unimplemented in
      addressSet - restricted address set or null for entire program
      monitor - allow canceling
      Throws:
      CancelledException - if monitor canceled

    • clearUnimplementedPcodeWarnings

      public static void clearUnimplementedPcodeWarnings(Program program, AddressSetView addressSet, TaskMonitor monitor) throws CancelledException
      Clear all bookmarks which indicate unimplemented pcode within the specified address set.
      Parameters:
      program - program to clear bookmarks
      addressSet - restricted address set or null for entire program
      monitor - allow canceling
      Throws:
      CancelledException - if monitor canceled

    • clearBadInstructionErrors

      public static void clearBadInstructionErrors(Program program, AddressSetView addressSet, TaskMonitor monitor) throws CancelledException
      Clear all bookmarks which indicate Bad Instruction within the specified address set.
      Parameters:
      program - program to clear bookmarks
      addressSet - restricted address set or null for entire program
      monitor - allow canceling
      Throws:
      CancelledException - if monitor canceled