Package ghidra.program.disassemble

Class Disassembler

  • All Implemented Interfaces:
    DisassemblerConflictHandler
    public class Disassembler
extends java.lang.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 Detail

      • MARK_BAD_INSTRUCTION_PROPERTY

        public static final java.lang.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 java.lang.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 java.lang.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 java.lang.String ERROR_BOOKMARK_CATEGORY
        See Also:
        Constant Field Values

      • UNIMPL_BOOKMARK_CATEGORY

        public static final java.lang.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

      • baseContextRegister

        protected final Register baseContextRegister

      • doMarkBadInstructions

        protected boolean doMarkBadInstructions

    • Constructor Detail

      • Disassembler

        protected Disassembler​(Program program,
                       TaskMonitor monitor,
                       DisassemblerMessageListener listener)
        Disassembler constructor. Marking of bad instructions honors "Mark Bad Disassembly" program Disassembler option.
        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.
        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.
        language - the language module that "understands" the bytes.
        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 Detail

      • getDisassembler

        public static Disassembler getDisassembler​(Program program,
                                           TaskMonitor monitor,
                                           DisassemblerMessageListener listener)
        Get a suitable disassembler instance. Marking of bad instructions honors "Mark Bad Disassembly" program Disassembler option.
        Parameters:
        program - the program to be disassembled.
        monitor - progress monitor
        listener - object to notify of disassembly messages.

      • 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.
        language - the language module that "understands" the bytes.
        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.

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

      • 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 -
        Returns:
        true if program MARK_BAD_INSTRUCTION_PROPERTY has been enabled

      • isMarkUnimplementedPcodeOptionEnabled

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

      • isRestrictToExecuteMemory

        public static boolean isRestrictToExecuteMemory​(Program program)
        Parameters:
        program -
        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 psuedo-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 psuedo-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)

      • isBlockTerminationOK

        protected boolean isBlockTerminationOK​(Instruction instr)

      • 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 -
        addressSet - restricted address set or null for entire program
        monitor -
        Throws:
        CancelledException

      • 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 -
        addressSet - restricted address set or null for entire program
        monitor -
        Throws:
        CancelledException