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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `Disassembler.DisassemblerProgramContext`
  `DisassemblerProgramContext` is used as a proxy program context due to the delayed nature of laying down instructions and their associated context state.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final AddressFactory`
  `addrFactory`
  `protected final Register`
  `baseContextRegister`
  `protected BookmarkManager`
  `bmMgr`
  `protected DisassemblerContextImpl`
  `disassemblerContext`
  `protected Disassembler.DisassemblerProgramContext`
  `disassemblerProgramContext`
  `protected boolean`
  `doMarkBadInstructions`
  `static final String`
  `ERROR_BOOKMARK_CATEGORY`
  `protected final Language`
  `language`
  `static final String`
  `MARK_BAD_INSTRUCTION_PROPERTY`
  `MARK_BAD_INSTRUCTION_PROPERTY` Program Disassembler property enables marking of instruction disassembly errors.
  `static final String`
  `MARK_UNIMPL_PCODE_PROPERTY`
  `MARK_UNIMPL_PCODE_PROPERTY` Program Disassembler property enables marking of instructions which are missing their pcode implementation.
  `static final int`
  `MAX_REPEAT_PATTERN_LENGTH`
  `protected final ParallelInstructionLanguageHelper`
  `parallelHelper`
  `static final String`
  `RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY`
  `RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY` Program Disassembler property restricts disassembly to executable memory only.
  `static final String`
  `UNIMPL_BOOKMARK_CATEGORY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Disassembler(Language language, AddressFactory addrFactory, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Disassembler constructor.
  `protected`
  `Disassembler(Program program, boolean markBadInstructions, boolean markUnimplementedPcode, boolean restrictToExecuteMemory, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Disassembler constructor
  `protected`
  `Disassembler(Program program, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Disassembler constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `blockTerminated(InstructionBlock block)`
  Signal that block disassembly has been terminated.
  `static void`
  `clearBadInstructionErrors(Program program, AddressSetView addressSet, TaskMonitor monitor)`
  Clear all bookmarks which indicate Bad Instruction within the specified address set.
  `static void`
  `clearUnimplementedPcodeWarnings(Program program, AddressSetView addressSet, TaskMonitor monitor)`
  Clear all bookmarks which indicate unimplemented pcode within the specified address set.
  `AddressSet`
  `disassemble(Address startAddr, AddressSetView restrictedSet)`
  Disassembles code starting at startAddr and restricted to addrSet.
  `AddressSet`
  `disassemble(Address startAddr, AddressSetView restrictedSet, boolean doFollowFlow)`
  Disassembles code starting at startAddr and restricted to addrSet.
  `AddressSet`
  `disassemble(Address startAddr, AddressSetView restrictedSet, RegisterValue initialContextValue, boolean doFollowFlow)`
  Disassembles code starting at startAddr and restricted to addrSet.
  `AddressSet`
  `disassemble(AddressSetView startSet, AddressSetView restrictedSet, boolean doFollowFlow)`
  Attempt disassembly of all undefined code units within the specified set of addresses.
  `AddressSet`
  `disassemble(AddressSetView startSet, AddressSetView restrictedSet, RegisterValue initialContextValue, boolean doFollowFlow)`
  Attempt disassembly of all undefined code units within the specified set of addresses.
  `protected void`
  `disassembleInstructionBlock(InstructionBlock block, MemBuffer blockMemBuffer, Address flowFrom, int limit, InstructionSet instructionSet, boolean skipIfBlockAlreadyDisassembled)`
  `static Disassembler`
  `getDisassembler(Language language, AddressFactory addrFactory, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Get a suitable disassembler instance.
  `static Disassembler`
  `getDisassembler(Program program, boolean markBadInstructions, boolean markUnimplementedPcode, boolean restrictToExecuteMemory, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Get a suitable disassembler instance.
  `static Disassembler`
  `getDisassembler(Program program, TaskMonitor monitor, DisassemblerMessageListener listener)`
  Get a suitable disassembler instance.
  `protected ProcessorContext`
  `getProcessorContext(Address addr, int instrLength, RegisterValue contextValue)`
  Get the processor context for the current instruction being disassembled as reflected by the `disassemblerContext`.
  `protected boolean`
  `isBlockTerminationOK(Instruction instr)`
  Determine if `InstructionBlock` termination is allowed after the specified instruction has been added.
  `static boolean`
  `isMarkBadDisassemblyOptionEnabled(Program program)`
  `static boolean`
  `isMarkUnimplementedPcodeOptionEnabled(Program program)`
  `static boolean`
  `isRestrictToExecuteMemory(Program program)`
  `void`
  `markInstructionError(InstructionError conflict)`
  `static void`
  `markUnimplementedPcode(Program program, AddressSetView addressSet, TaskMonitor monitor)`
  Mark all instructions with unimplemented pcode over the specified address set
  `protected InstructionPrototype`
  `parseInstructionPrototype(MemBuffer instrMemBuffer, InstructionBlock block)`
  Perform parse of instruction bytes and context to produce an instruction prototype.
  `protected Address`
  `processInstruction(PseudoInstruction inst, MemBuffer blockMemBuffer, InstructionBlock block, InstructionSet instructionSet)`
  Process a new instruction which has just been parsed.
  `InstructionBlock`
  `pseudoDisassembleBlock(Address addr, RegisterValue defaultContextValue, int limit)`
  Perform a pseudo-disassembly of an single instruction block only following fall-throughs.
  `InstructionBlock`
  `pseudoDisassembleBlock(MemBuffer blockMemBuffer, RegisterValue defaultContextValue, int limit)`
  Perform a pseudo-disassembly of an single instruction block only following fall-throughs.
  `void`
  `resetDisassemblerContext()`
  Clear any retained context state which may have been accumulated.
  `void`
  `setRepeatPatternLimit(int maxInstructions)`
  Set the maximum number of instructions in a single run which contain the same byte values.
  `void`
  `setRepeatPatternLimitIgnored(AddressSetView set)`
  Set the region over which the repeat pattern limit will be ignored.
  `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.

  ### Methods inherited from class java.lang.Object

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

- ## 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### ERROR_BOOKMARK_CATEGORY

    public static final String ERROR_BOOKMARK_CATEGORY
    See Also:
      - Constant Field Values

  - ### UNIMPL_BOOKMARK_CATEGORY

    public static final String UNIMPL_BOOKMARK_CATEGORY
    See Also:
      - Constant Field Values

  - ### MAX_REPEAT_PATTERN_LENGTH

    public static final int MAX_REPEAT_PATTERN_LENGTH
    See Also:
      - Constant Field Values

  - ### 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:
    - `MARK_BAD_INSTRUCTION_PROPERTY`
    - `MARK_UNIMPL_PCODE_PROPERTY`
    - `RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY`
    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:
    - `MARK_BAD_INSTRUCTION_PROPERTY`
    - `MARK_UNIMPL_PCODE_PROPERTY`
    - `RESTRICT_DISASSEMBLY_TO_EXECUTE_MEMORY_PROPERTY`
    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)

  - ### blockTerminated

    protected void blockTerminated(InstructionBlock block)
    Signal that block disassembly has been terminated. An error condition may have been recorded within the block (see `InstructionBlock.hasInstructionError()` or block terminated early due to a matching instruction within the active instruction set had already been disassembled.
    Parameters:
      `block` - instruction block

  - ### parseInstructionPrototype

    protected InstructionPrototype parseInstructionPrototype(MemBuffer instrMemBuffer, InstructionBlock block) throws InsufficientBytesException, UnknownInstructionException
    Perform parse of instruction bytes and context to produce an instruction prototype.
    Parameters:
      `instrMemBuffer` - memory buffer
      `block` - fallthrough sequence of instructions preceding current instruction required to facilitate potential crossbuilds for current instruction.
    Returns:
      instruction prototype
    Throws:
      `InsufficientBytesException`
      `UnknownInstructionException`

  - ### getProcessorContext

    protected ProcessorContext getProcessorContext(Address addr, int instrLength, RegisterValue contextValue)
    Get the processor context for the current instruction being disassembled as reflected by the `disassemblerContext`. This is intended to be used in forming a `PseudoInstruction` or exercising certain methods on an `InstructionPrototype`.
    Parameters:
      `addr` - current instruction address
      `instrLength` - instruction byte length
      `contextValue` - instruction context register value
    Returns:
      processor context

  - ### isBlockTerminationOK

    protected boolean isBlockTerminationOK(Instruction instr)
    Determine if `InstructionBlock` termination is allowed after the specified instruction has been added. Based upon the crossbuild requirements / parallel instruction semantics, this method may return false to force continued fallthrough instruction accumulation within the current block.
    Parameters:
      `instr` - last instruction disassembled
    Returns:
      true if current block with last instruction may be terminated, false if block must continue fallthrough instruction accumulation.

  - ### 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