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. Processor-specific methods, when not implemented by a plugin, should raise the UnsupportedOperationException . 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(IDebuggerSetupInformation 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(String address, ICodeUnit unit)
Get the execution breakpoint set at the given address.
| ||||||||||
| abstract IDebuggerBreakpoint |
getBreakpoint(long memoryAddress)
Get the breakpoints set at the explicit memory address.@return
| ||||||||||
| abstract List<? extends IDebuggerBreakpoint> |
getBreakpoints()
Retrieve a list of execution breakpoints.
| ||||||||||
| abstract IDebuggerThread |
getDefaultThread()
Get the default thread.
| ||||||||||
| abstract IDebuggerVirtualMemory |
getMemoryUnsafe()
Retrieve a direct reference to the virtual memory running on the target.
| ||||||||||
| abstract List<? extends IDebuggerModule> |
getModules()
Get the list of modules or libraries that are relevant to the target.
| ||||||||||
| abstract List<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 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 |
isAttached()
Determine whether or not this debugger is attached to a target.
| ||||||||||
| abstract List<? extends IDebuggerMachineInformation> |
listMachines()
List relevant machines for this debugger unit.
| ||||||||||
| abstract List<? extends IDebuggerProcessInformation> |
listProcesses(IDebuggerMachineInformation machine)
List relevant a machine's processes that are relevant to this debugger unit.
| ||||||||||
| abstract boolean |
pause()
Pause the target.
| ||||||||||
| abstract int |
readMemory(long memoryAddress, int size, byte[] dst, int dstOffset)
Read from memory.
| ||||||||||
| abstract boolean |
restart()
Restart the target (if possible).
| ||||||||||
| abstract boolean |
run()
Run or resume execution of the target.
| ||||||||||
| abstract IDebuggerBreakpoint |
setBreakpoint(long memoryAddress, int processorMode)
Set a breakpoint at the explicit memory address.
| ||||||||||
| abstract IDebuggerBreakpoint |
setBreakpoint(String address, ICodeUnit unit)
Set an execution breakpoint at the given address.
| ||||||||||
| abstract IDebuggerBreakpoint |
setBreakpoint(long memoryAddress)
Same as
setBreakpoint(memoryAddress, 0). | ||||||||||
| 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 int |
writeMemory(long memoryAddress, int size, byte[] src, int srcOffset)
Write to memory.
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
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 (IDebuggerSetupInformation 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 (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 IDebuggerBreakpoint getBreakpoint (long memoryAddress)
Get the breakpoints set at the explicit memory address.@return
Throws
| method is specific to native code. It throws UnsupportedOperationException if not supported |
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 getMemoryUnsafe ()
Retrieve a direct reference to the virtual memory running on the target. Optional method, supported only if the debugger allows direct memory access. Warning: reading or writing to memory through this object is unsafe if the target is not in a suspended state.
Returns
- a virtual memory object, null on error
public abstract List<? extends IDebuggerModule> getModules ()
Get the list of modules or libraries that are relevant to the target.
public abstract List<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.
public abstract DebuggerSuspendPolicy getSuspendPolicy (DebuggerEventType eventType)
Get the suspend policy.
public abstract IDebuggerTargetInformation getTargetInformation ()
Retrieve information about the target being debugged.
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 isAttached ()
Determine whether or not this debugger is attached to a target. Unless attached, most operations are likely to fail.
public abstract List<? extends IDebuggerMachineInformation> listMachines ()
List relevant machines for this debugger unit. This method works regardless of which state the debugger is currently in.
Returns
- a list of machines, possibly empty
public abstract List<? extends IDebuggerProcessInformation> listProcesses (IDebuggerMachineInformation machine)
List relevant a machine's processes that are relevant to this debugger unit. This method works regardless of which state the debugger is currently in.
Parameters
| machine | mandatory machine |
|---|
Returns
- a list of processes, possibly empty
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.
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.
Returns
- number of bytes read, -1 on error
public abstract boolean restart ()
Restart the target (if possible).
public abstract boolean run ()
Run or resume execution of the target.
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
Throws
| method is specific to native code. It throws UnsupportedOperationException if not supported |
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)
Same as setBreakpoint(memoryAddress, 0).
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 int writeMemory (long memoryAddress, int size, byte[] src, int srcOffset)
Write to memory. Optional method, supported only if the debugger allows direct memory access.
Returns
- number of bytes written, -1 on error