Package com.pnfsoftware.jeb.core.units.code.debug

Interface IDebuggerUnit

All Superinterfaces:
IAddressableUnit, IEventSource, IInteractiveUnit, IUnit, IUnitCreator, IUserDataSupport
All Known Subinterfaces:
IDalvikDebuggerUnit, INativeDebuggerUnit
public interface IDebuggerUnit extends IInteractiveUnit
Main Application Programming / Service Provider interface for JEB debugger units. Most methods in this class do not raise exceptions; they return false or null on error or if the implementation is not present or irrelevant. This interface is designed to be as generic as possible, in order to accommodate all types of debuggers (native code, bytecode, etc.)

  • Method Details

    • getTargetEnumerator

      IDebuggerTargetEnumerator getTargetEnumerator()
      Provide an optional target enumerator.
      Returns:
      target enumerator, or null

    • canPerformOperation

      boolean canPerformOperation(DebuggerOperationType op)
      Indicate if performing a given operation is likely to be safe. This method does not provide synchronization/locking facility; its result is purely indicative and may be used by front-ends and clients to minimize error generation.
      Parameters:
      op - operation type
      Returns:
      true if the operation is likely safe

    • setSuspendPolicy

      boolean setSuspendPolicy(DebuggerEventType eventType, DebuggerSuspendPolicy suspendPolicy)
      Set the suspend policy, that is what threads are/are not paused when a breakpoint-like event is reported to the debugger.
      Parameters:
      eventType - event type
      suspendPolicy - suspend policy
      Returns:
      true if the policy was set

    • getSuspendPolicy

      DebuggerSuspendPolicy getSuspendPolicy(DebuggerEventType eventType)
      Get the suspend policy.
      Parameters:
      eventType - event type
      Returns:
      suspend policy, or null if unavailable

    • getModules

      List<? extends IDebuggerModule> getModules()
      Get the list of modules or libraries that are relevant to the target.
      Returns:
      target modules, or null on error

    • getPotentialDebuggees

      List<? extends ICodeUnit> getPotentialDebuggees()
      Retrieve a list of code units that could potentially be managed by this debugger. The list returned by this method is likely to change after the debugger is attached to a target. Note that a potential debuggee may not have been processed.
      Returns:
      candidate debuggee units, or null on error

    • registerDebuggee

      boolean registerDebuggee(ICodeUnit unit)
      Register a code unit as a debuggee candidate.
      Parameters:
      unit - code unit
      Returns:
      true if the unit was registered

    • unregisterDebuggee

      boolean unregisterDebuggee(ICodeUnit unit)
      Unregister a code unit as a debuggee candidate.
      Parameters:
      unit - code unit
      Returns:
      true if the unit was unregistered

    • getTargetApplication

      IUnit getTargetApplication()
      Retrieve the optional target application.
      Returns:
      target application, or null

    • isAttached

      boolean isAttached()
      Determine whether or not this debugger is attached to a target. Unless attached, most operations are likely to fail.
      Returns:
      true if the debugger is attached

    • attach

      boolean attach(DebuggerSetupInformation setupInformation)
      Attach the debugger to a target.
      Parameters:
      setupInformation - the target information
      Returns:
      true if the target was successfully attached, false otherwise

    • restart

      boolean restart()
      Restart the target (if possible).
      Returns:
      true if the target was restarted

    • detach

      boolean detach()
      Detach from the target (if possible).
      Returns:
      true if the debugger was detached

    • getTargetInformation

      IDebuggerTargetInformation getTargetInformation()
      Retrieve information about the target being debugged.
      Returns:
      target information, or null

    • run

      boolean run()
      Run or resume execution of the target.
      Returns:
      success indicator

    • pause

      boolean pause()
      Pause the target. The debugger should stop execution of the target, as much as it possibly can. Typically, if the debugger has enough privilege to do so, this means pausing all threads currently executing within the target.
      Returns:
      success indicator

    • isPaused

      boolean isPaused()
      Determine if the target is paused. Generally, that is equivalent to determining that all threads are suspended.
      Returns:
      true if the target is suspended

    • terminate

      boolean terminate()
      Kill the target (if possible).
      Returns:
      true if the target was terminated

    • getThreads

      List<? extends IDebuggerThread> getThreads()
      Get a list of threads running on the target.
      Returns:
      a list of threads (possibly, but unlikely, empty), null on error

    • getThreadById

      IDebuggerThread getThreadById(long threadId)
      Get a thread by its identifier.
      Parameters:
      threadId - thread id
      Returns:
      thread, or null

    • setDefaultThread

      boolean setDefaultThread(long threadId)
      Set the default thread.
      Parameters:
      threadId - thread id
      Returns:
      true on success, false if the thread cannot be set as the default thread

    • getDefaultThread

      IDebuggerThread getDefaultThread()
      Get the default thread. Note that clients may call this method very frequently.
      Returns:
      default thread, or null

    • hasDefaultThread

      boolean hasDefaultThread()
      Non blocking method that checks a default thread is set.
      Returns:
      true if a default thread is set

    • setBreakpoint

      IDebuggerBreakpoint setBreakpoint(String address, ICodeUnit unit, int flags)
      Set a general breakpoint at the given address. Specific breakpoint operations (such as enabling/disabling a breakpoint) can be executed directly on the breakpoint object.
      Parameters:
      address - address, as defined by interactive units
      unit - code unit relevant to the address
      flags - optional, or a combination of IDebuggerBreakpoint.BREAK_ON_xxx flags
      Returns:
      a breakpoint object, representing a new or existing breakpoint; null on error

    • setBreakpoint

      default IDebuggerBreakpoint setBreakpoint(String address, ICodeUnit unit)
      Set a general standard breakpoint at the given address. Specific breakpoint operations (such as enabling/disabling a breakpoint) can be executed directly on the breakpoint object.
      Parameters:
      address - address, as defined by interactive units
      unit - code unit relevant to the address
      Returns:
      a breakpoint object, representing a new or existing breakpoint; null on error

    • getBreakpoint

      IDebuggerBreakpoint getBreakpoint(String address, ICodeUnit unit)
      Get the execution breakpoint set at the given address.
      Parameters:
      address - address, as defined by interactive units
      unit - code unit relevant to the address
      Returns:
      the breakpoint object on success, null if none or the operation failed

    • getBreakpoints

      List<? extends IDebuggerBreakpoint> getBreakpoints()
      Retrieve a list of execution breakpoints.
      Returns:
      a list of breakpoints, possibly empty; null on error

    • clearBreakpoint

      boolean clearBreakpoint(IDebuggerBreakpoint breakpoint)
      Remove an execution breakpoint.
      Parameters:
      breakpoint - breakpoint to clear
      Returns:
      true if the breakpoint was cleared

    • clearBreakpoints

      boolean clearBreakpoints()
      Remove all execution breakpoints.
      Returns:
      true if breakpoints were cleared

    • setBreakpoint

      IDebuggerBreakpoint setBreakpoint(long memoryAddress)
      Same as setBreakpoint(memoryAddress, 0).
      Parameters:
      memoryAddress - requested breakpoint address
      Returns:
      the breakpoint or null on error or if not implemented

    • setBreakpoint

      IDebuggerBreakpoint setBreakpoint(long memoryAddress, int processorMode)
      Set a breakpoint at the explicit memory address. This method is valid only for targets supporting numerical addressing, such as physical processors.
      Parameters:
      memoryAddress - requested breakpoint address
      processorMode - a processor mode (see IProcessor.MODE_xxx constant) specifying the breakpoint. Leave to IProcessor.MODE_DEFAULT is unknown.
      Returns:
      the breakpoint or null on error or if not implemented

    • getBreakpoint

      IDebuggerBreakpoint getBreakpoint(long memoryAddress)
      Get the breakpoints set at the explicit memory address.
      Parameters:
      memoryAddress - memory address
      Returns:
      the breakpoint or null on error or if not implemented

    • getMemory

      IDebuggerVirtualMemory getMemory()
      Retrieve an VM object representing the memory of the target. Operations on that object are safe and will attempt to modify the state of the debuggee if it needs to.
      Returns:
      debugger virtual memory, or null if unavailable

    • readMemory

      int readMemory(long memoryAddress, int size, byte[] dst, int dstOffset)
      Read from memory. Optional method, supported only if the debugger allows direct memory access. If the memory cannot be read at the time of the call, the method should fail instead of attempting to modify the state of the debuggee to allow the read operation.
      Parameters:
      memoryAddress - source memory address
      size - number of bytes to read
      dst - destination buffer
      dstOffset - destination buffer offset
      Returns:
      number of bytes read, -1 on error

    • writeMemory

      int writeMemory(long memoryAddress, int size, byte[] src, int srcOffset)
      Write to memory. Optional method, supported only if the debugger allows direct memory access. If the memory cannot be written at the time of the call, the method may attempt to modify the state of the debuggee to allow the write operation.
      Parameters:
      memoryAddress - destination memory address
      size - number of bytes to write
      src - source buffer
      srcOffset - source buffer offset
      Returns:
      number of bytes written, -1 on error

    • convertToUnitAddress

      UnitAddress<ICodeUnit> convertToUnitAddress(String address)
      Convert a global address (not specifying the unit to which it applies) to an address explicitly relevant to a unit. The conversion may not be possible, for example if the unit is not handled by this debugger.
      Parameters:
      address - debugger-global address
      Returns:
      unit address, or null if conversion failed

    • convertSymbolicAddressToMemoryToAddress

      long convertSymbolicAddressToMemoryToAddress(String symbol, ICodeUnit unit)
      Convert a symbolic address, such as a register name, method symbol, string representation of a physical address, etc. to its associated physical memory address.
      Parameters:
      symbol - the symbol name
      unit - optional
      Returns:
      the physical address associated with the symbol, 0 on error

    • getProcessor

      IProcessor<? extends IInstruction> getProcessor()
      Retrieve the processor associated with this debugger.
      Returns:
      processor, or null if not applicable