Interface IDebuggerUnit
- All Superinterfaces:
IAddressableUnit
,IEventSource
,IInteractiveUnit
,IUnit
,IUnitCreator
,IUserDataSupport
- All Known Subinterfaces:
IDalvikDebuggerUnit
,INativeDebuggerUnit
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 Summary
Modifier and TypeMethodDescriptionboolean
attach
(DebuggerSetupInformation setupInformation) Attach the debugger to a target.boolean
Indicate if performing a given operation is likely to be safe.boolean
clearBreakpoint
(IDebuggerBreakpoint breakpoint) Remove an execution breakpoint.boolean
Remove all execution breakpoints.long
convertSymbolicAddressToMemoryToAddress
(String symbol, ICodeUnit unit) Convert a symbolic address, such as a register name, method symbol, string representation of a physical address, etc.convertToUnitAddress
(String address) Convert a global address (not specifying the unit to which it applies) to an address explicitly relevant to a unit.boolean
detach()
Detach from the target (if possible).getBreakpoint
(long memoryAddress) Get the breakpoints set at the explicit memory address.getBreakpoint
(String address, ICodeUnit unit) Get the execution breakpoint set at the given address.List<? extends IDebuggerBreakpoint>
Retrieve a list of execution breakpoints.Get the default thread.Retrieve an VM object representing the memory of the target.List<? extends IDebuggerModule>
Get the list of modules or libraries that are relevant to the target.Retrieve a list of code units that could potentially be managed by this debugger.IProcessor<? extends IInstruction>
getSuspendPolicy
(DebuggerEventType eventType) Get the suspend policy.Retrieve the optional target application.Provide an optional target enumerator.Retrieve information about the target being debugged.getThreadById
(long threadId) Get a thread by its identifier.List<? extends IDebuggerThread>
Get a list of threads running on the target.boolean
Non blocking method that checks a default thread is set.boolean
Determine whether or not this debugger is attached to a target.boolean
isPaused()
Determine if the target is paused.boolean
pause()
Pause the target.int
readMemory
(long memoryAddress, int size, byte[] dst, int dstOffset) Read from memory.boolean
registerDebuggee
(ICodeUnit unit) boolean
restart()
Restart the target (if possible).boolean
run()
Run or resume execution of the target.setBreakpoint
(long memoryAddress) Same assetBreakpoint(memoryAddress, 0)
.setBreakpoint
(long memoryAddress, int processorMode) Set a breakpoint at the explicit memory address.default IDebuggerBreakpoint
setBreakpoint
(String address, ICodeUnit unit) Set a general standard breakpoint at the given address.setBreakpoint
(String address, ICodeUnit unit, int flags) Set a general breakpoint at the given address.boolean
setDefaultThread
(long threadId) Set the default thread.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.boolean
Kill the target (if possible).boolean
unregisterDebuggee
(ICodeUnit unit) int
writeMemory
(long memoryAddress, int size, byte[] src, int srcOffset) Write to memory.Methods inherited from interface com.pnfsoftware.jeb.core.units.IAddressableUnit
getAddressLabel, getAddressLabels, getAddressOfItem, getCanonicalAddress, getItemAtAddress, getItemObject, getRelatedItems, getWellKnownAddresses, isValidAddress
Methods inherited from interface com.pnfsoftware.jeb.util.events.IEventSource
addListener, countListeners, getListeners, getParentSource, insertListener, notifyListeners, removeListener, setParentSource
Methods inherited from interface com.pnfsoftware.jeb.core.units.IInteractiveUnit
addressToLocation, canExecuteAction, executeAction, executeAction, getAddressActions, getCommentManager, getFullComment, getFullComments, getGlobalActions, getInlineComment, getInlineComments, getItemActions, getMetadataManager, locationToAddress, prepareExecution, setInlineComment
Methods inherited from interface com.pnfsoftware.jeb.core.units.IUnit
addChild, addChild, canBePersisted, dispose, generateQuickState, getChildren, getContributions, getCreationTimestamp, getDescription, getExtraInputs, getFormatter, getFormatType, getIconData, getInput, getInterpreters, getLock, getName, getNotes, getNotificationManager, getParent, getParentArtifact, getParentProject, getPropertyDefinitionManager, getPropertyManager, getRealName, getStatus, getUid, getUnitProcessor, initializePropertyObjects, isDisposed, isProcessed, isStale, isTransientChild, notifyGenericChange, postDeserialization, process, removeChild, setName, setNotes, setParent, setRealName, setUnitProcessor
Methods inherited from interface com.pnfsoftware.jeb.core.IUserDataSupport
clearAllData, getAllData, getData, setData
-
Method Details
-
getTargetEnumerator
IDebuggerTargetEnumerator getTargetEnumerator()Provide an optional target enumerator.- Returns:
-
canPerformOperation
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
-- Returns:
-
setSuspendPolicy
Set the suspend policy, that is what threads are/are not paused when a breakpoint-like event is reported to the debugger.- Parameters:
eventType
-suspendPolicy
-- Returns:
-
getSuspendPolicy
Get the suspend policy.- Parameters:
eventType
-- Returns:
-
getModules
List<? extends IDebuggerModule> getModules()Get the list of modules or libraries that are relevant to the target.- Returns:
-
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 isattached
to a target. Note that a potential debuggee may not have been processed.- Returns:
-
registerDebuggee
- Parameters:
unit
-- Returns:
-
unregisterDebuggee
- Parameters:
unit
-- Returns:
-
getTargetApplication
IUnit getTargetApplication()Retrieve the optional target application.- Returns:
-
isAttached
boolean isAttached()Determine whether or not this debugger is attached to a target. Unless attached, most operations are likely to fail.- Returns:
-
attach
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:
-
detach
boolean detach()Detach from the target (if possible).- Returns:
-
getTargetInformation
IDebuggerTargetInformation getTargetInformation()Retrieve information about the target being debugged.- Returns:
-
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:
-
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
Get a thread by its identifier.- Returns:
-
setDefaultThread
boolean setDefaultThread(long threadId) Set the default thread.- Parameters:
threadId
-- 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:
-
hasDefaultThread
boolean hasDefaultThread()Non blocking method that checks a default thread is set. -
setBreakpoint
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 unitsunit
- code unit relevant to the addressflags
- optional, or a combination ofIDebuggerBreakpoint.BREAK_ON_xxx
flags- Returns:
- a breakpoint object, representing a new or existing breakpoint; null on error
-
setBreakpoint
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 unitsunit
- code unit relevant to the address- Returns:
- a breakpoint object, representing a new or existing breakpoint; null on error
-
getBreakpoint
Get the execution breakpoint set at the given address.- Parameters:
address
-unit
-- 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
Remove an execution breakpoint.- Parameters:
breakpoint
-- Returns:
-
clearBreakpoints
boolean clearBreakpoints()Remove all execution breakpoints.- Returns:
-
setBreakpoint
Same assetBreakpoint(memoryAddress, 0)
. -
setBreakpoint
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 addressprocessorMode
- aprocessor
mode (seeIProcessor.MODE_xxx
constant) specifying the breakpoint. Leave toIProcessor.MODE_DEFAULT
is unknown.- Returns:
- the breakpoint or null on error or if not implemented
-
getBreakpoint
Get the breakpoints set at the explicit memory address.- Parameters:
memoryAddress
-- 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:
-
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
-size
-dst
-dstOffset
-- 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
-size
-src
-srcOffset
-- Returns:
- number of bytes written, -1 on error
-
convertToUnitAddress
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 nothandled by this debugger
.- Parameters:
address
-- Returns:
-
convertSymbolicAddressToMemoryToAddress
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 nameunit
- optional- Returns:
- the physical address associated with the symbol, 0 on error
-
getProcessor
IProcessor<? extends IInstruction> getProcessor()
-