public interface

IDebuggerUnit

implements IInteractiveUnit
com.pnfsoftware.jeb.core.units.code.debug.IDebuggerUnit

Class Overview

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

Summary

Public Methods
abstract boolean attach(DebuggerSetupInformation setupInformation)
Attach the debugger to a target.
abstract boolean canPerformOperation(DebuggerOperationType op)
Indicate if performing a given operation is likely to be safe.
abstract boolean clearBreakpoint(IDebuggerBreakpoint breakpoint)
Remove an execution breakpoint.
abstract boolean clearBreakpoints()
Remove all execution breakpoints.
abstract long convertSymbolicAddressToMemoryToAddress(String symbol, ICodeUnit unit)
Convert a symbolic address, such as a register name, method symbol, string representation of a physical address, etc.
abstract 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.
abstract boolean detach()
Detach from the target (if possible).
abstract IDebuggerBreakpoint getBreakpoint(long memoryAddress)
Get the breakpoints set at the explicit memory address.
abstract IDebuggerBreakpoint getBreakpoint(String address, ICodeUnit unit)
Get the execution breakpoint set at the given address.
abstract List<? extends IDebuggerBreakpoint> getBreakpoints()
Retrieve a list of execution breakpoints.
abstract IDebuggerThread getDefaultThread()
Get the default thread.
abstract IDebuggerVirtualMemory getMemory()
Retrieve an VM object representing the memory of the target.
abstract List<? extends IDebuggerModule> getModules()
Get the list of modules or libraries that are relevant to the target.
abstract List<? extends ICodeUnit> getPotentialDebuggees()
Retrieve a list of code units that could potentially be managed by this debugger.
abstract IProcessor<? extends IInstruction> getProcessor()
abstract DebuggerSuspendPolicy getSuspendPolicy(DebuggerEventType eventType)
Get the suspend policy.
abstract IDebuggerTargetEnumerator getTargetEnumerator()
Provide an optional target enumerator.
abstract IDebuggerTargetInformation getTargetInformation()
Retrieve information about the target being debugged.
abstract IDebuggerThread getThreadById(long threadId)
Get a thread by its identifier.
abstract List<? extends IDebuggerThread> getThreads()
Get a list of threads running on the target.
abstract boolean hasDefaultThread()
Non blocking method that checks a default thread is set.
abstract boolean isAttached()
Determine whether or not this debugger is attached to a target.
abstract boolean isPaused()
Determine if the target is paused.
abstract boolean pause()
Pause the target.
abstract int readMemory(long memoryAddress, int size, byte[] dst, int dstOffset)
Read from memory.
abstract boolean registerDebuggee(ICodeUnit unit)
abstract boolean restart()
Restart the target (if possible).
abstract boolean run()
Run or resume execution of the target.
abstract IDebuggerBreakpoint setBreakpoint(long memoryAddress)
abstract IDebuggerBreakpoint setBreakpoint(String address, ICodeUnit unit)
Set an execution breakpoint at the given address.
abstract IDebuggerBreakpoint setBreakpoint(long memoryAddress, int processorMode)
Set a breakpoint at the explicit memory address.
abstract boolean setDefaultThread(long threadId)
Set the default thread.
abstract 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.
abstract boolean terminate()
Kill the target (if possible).
abstract boolean unregisterDebuggee(ICodeUnit unit)
abstract int writeMemory(long memoryAddress, int size, byte[] src, int srcOffset)
Write to memory.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.IUnitCreator
From interface com.pnfsoftware.jeb.core.units.IAddressableUnit
From interface com.pnfsoftware.jeb.core.units.IInteractiveUnit
From interface com.pnfsoftware.jeb.core.units.IUnit
From interface com.pnfsoftware.jeb.util.events.IEventSource

Public Methods

public abstract 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

public abstract 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.

public abstract boolean clearBreakpoint (IDebuggerBreakpoint breakpoint)

Remove an execution breakpoint.

public abstract boolean clearBreakpoints ()

Remove all execution breakpoints.

public abstract 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

public abstract 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.

public abstract boolean detach ()

Detach from the target (if possible).

public abstract IDebuggerBreakpoint getBreakpoint (long memoryAddress)

Get the breakpoints set at the explicit memory address.

Returns
  • the breakpoint or null on error or if not implemented

public abstract IDebuggerBreakpoint getBreakpoint (String address, ICodeUnit unit)

Get the execution breakpoint set at the given address.

Returns
  • the breakpoint object on success, null if none or the operation failed

public abstract List<? extends IDebuggerBreakpoint> getBreakpoints ()

Retrieve a list of execution breakpoints.

Returns
  • a list of breakpoints, possibly empty; null on error

public abstract IDebuggerThread getDefaultThread ()

Get the default thread. Note that clients may call this method very frequently.

public abstract 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.

public abstract List<? extends IDebuggerModule> getModules ()

Get the list of modules or libraries that are relevant to the target.

public abstract 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 #attach(IDebuggerSetupInformation) attached to a target.

public abstract IProcessor<? extends IInstruction> getProcessor ()

public abstract DebuggerSuspendPolicy getSuspendPolicy (DebuggerEventType eventType)

Get the suspend policy.

public abstract IDebuggerTargetEnumerator getTargetEnumerator ()

Provide an optional target enumerator.

public abstract IDebuggerTargetInformation getTargetInformation ()

Retrieve information about the target being debugged.

public abstract IDebuggerThread getThreadById (long threadId)

Get a thread by its identifier.

public abstract 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

public abstract boolean hasDefaultThread ()

Non blocking method that checks a default thread is set.

public abstract boolean isAttached ()

Determine whether or not this debugger is attached to a target. Unless attached, most operations are likely to fail.

public abstract 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

public abstract 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

public abstract 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.

Returns
  • number of bytes read, -1 on error

public abstract boolean registerDebuggee (ICodeUnit unit)

public abstract boolean restart ()

Restart the target (if possible).

public abstract boolean run ()

Run or resume execution of the target.

Returns
  • success indicator

public abstract IDebuggerBreakpoint setBreakpoint (long memoryAddress)

public abstract IDebuggerBreakpoint setBreakpoint (String address, ICodeUnit unit)

Set an execution 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

public abstract 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 MODE_DEFAULT is unknown.
Returns
  • the breakpoint or null on error or if not implemented

public abstract boolean setDefaultThread (long threadId)

Set the default thread.

Returns
  • true on success, false if the thread cannot be set as the default thread

public abstract 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.

public abstract boolean terminate ()

Kill the target (if possible).

public abstract boolean unregisterDebuggee (ICodeUnit unit)

public abstract 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.

Returns
  • number of bytes written, -1 on error