Commit 72518291 authored by Friedemann Kleint's avatar Friedemann Kleint
Browse files

Debugger: Add to API documentation.

Reviewed-by: hjk
parent 13ee1dd2
......@@ -85,6 +85,10 @@
\o \l{Locator}
\o Hooks for providing content for Locator.
\row
\o \l{Debugger}
\o Debugging functionality.
\endtable
*/
......@@ -140,7 +144,7 @@
\row
\o Add a mode.
\o Modes correspond to complete screens of controls, specialized for a task.
\o \l{Core::IMode}, \l{Core::BaseMode}
\o \l{Core::IMode}
\row
\o Add a new editor type.
......
......@@ -11,7 +11,8 @@ headerdirs = . \
../../src/libs/extensionsystem \
../../src/plugins/coreplugin \
../../src/plugins/find \
../../src/plugins/locator
../../src/plugins/locator \
../../src/plugins/debugger
sourcedirs = . \
../../src/libs/aggregation \
......@@ -19,7 +20,8 @@ sourcedirs = . \
../../src/libs/extensionsystem \
../../src/plugins/coreplugin \
../../src/plugins/find \
../../src/plugins/locator
../../src/plugins/locator \
../../src/plugins/debugger
headers.fileextesnions = "*.h"
sources.fileextensions = "*.cpp *.qdoc"
......
......@@ -138,125 +138,140 @@
# define STATE_DEBUG(s)
#endif
// Note: the Debugger process itself and any helper processes like
// gdbserver, the trk client etc are referred to as 'Engine',
// whereas the debugged process is referred to as 'Inferior'.
//
// Transitions marked by '---' are done in the individual engines.
// Transitions marked by '+-+' are done in the base DebuggerEngine.
// Transitions marked by '*' are done asynchronously.
// The GdbEngine->setupEngine() function is described in more detail below.
//
// The engines are responsible for local roll-back to the last
// acknowledged state before calling notify*Failed. I.e. before calling
// notifyEngineSetupFailed() any process started during setupEngine()
// so far must be terminated.
//
//
//
// DebuggerNotReady
// +
// EngineSetupRequested
// +
// (calls *Engine->setupEngine())
// | |
// | |
// {notify- {notify-
// Engine- Engine-
// SetupOk} SetupFailed}
// + +
// + `+-+-+> EngineSetupFailed
// + +
// + [calls RunControl->startFailed]
// + +
// + DebuggerFinished
// v
// EngineSetupOk
// +
// [calls RunControl->StartSuccessful]
// +
// InferiorSetupRequested
// +
// (calls *Engine->setupInferior())
// | |
// | |
// {notify- {notify-
// Inferior- Inferior-
// SetupOk} SetupFailed}
// + +
// + ` +-+-> InferiorSetupFailed +-+-+-+-+-+->.
// + +
// InferiorSetupOk +
// + +
// EngineRunRequested +
// + +
// (calls *Engine->runEngine()) +
// / | | \ +
// / | | \ +
// | (core) | (attach) | | +
// | | | | +
// {notify- {notifyER&- {notifyER&- {notify- +
// Inferior- Inferior- Inferior- EngineRun- +
// Unrunnable} StopOk} RunOk} Failed} +
// + + + + +
// InferiorUnrunnable + InferiorRunOk + +
// + + +
// InferiorStopOk EngineRunFailed +
// + v
// `-+-+-+-+-+-+-+-+-+-+-+>-+
// +
// +
// #Interrupt@InferiorRunOk# +
// + +
// InferiorStopRequested +
// #SpontaneousStop + +
// @InferiorRunOk# (calls *Engine-> +
// + interruptInferior()) +
// {notify- | | +
// Spontaneous- {notify- {notify- +
// Inferior- Inferior- Inferior- +
// StopOk} StopOk} StopFailed} +
// + + + +
// + + + +
// InferiorStopOk + +
// + + +
// + + +
// + + +
// #Stop@InferiorUnrunnable# + +
// #Creator Close Event# + +
// + + +
// InferiorShutdownRequested +
// + +
// (calls *Engine->shutdownInferior()) +
// | | +
// {notify- {notify- +
// Inferior- Inferior- +
// ShutdownOk} ShutdownFailed} +
// + + +
// + + +
// #Inferior exited# + + +
// | + + +
// {notifyInferior- + + +
// Exited} + + +
// + + + +
// InferiorExitOk + + +
// + + + +
// InferiorShutdownOk InferiorShutdownFailed +
// * * +
// EngineShutdownRequested +
// + +
// (calls *Engine->shutdownEngine()) <+-+-+-+-+-+-+-+-+-+-+-+-+-+'
// | |
// | |
// {notify- {notify-
// Engine- Engine-
// ShutdownOk} ShutdownFailed}
// + +
// EngineShutdownOk EngineShutdownFailed
// * *
// DebuggerFinished
//
/*!
\namespace Debugger
Debugger plugin namespace
*/
/*!
\namespace Debugger::Internal
Internal namespace of the Debugger plugin
*/
/*!
\class Debugger::DebuggerEngine
\brief Base class of a debugger engine.
Note: the Debugger process itself and any helper processes like
gdbserver, the trk client etc are referred to as 'Engine',
whereas the debugged process is referred to as 'Inferior'.
Transitions marked by '---' are done in the individual engines.
Transitions marked by '+-+' are done in the base DebuggerEngine.
Transitions marked by '*' are done asynchronously.
The GdbEngine->setupEngine() function is described in more detail below.
The engines are responsible for local roll-back to the last
acknowledged state before calling notify*Failed. I.e. before calling
notifyEngineSetupFailed() any process started during setupEngine()
so far must be terminated.
\code
DebuggerNotReady
progressmanager/progressmanager.cpp +
EngineSetupRequested
+
(calls *Engine->setupEngine())
| |
| |
{notify- {notify-
Engine- Engine-
SetupOk} SetupFailed}
+ +
+ `+-+-+> EngineSetupFailed
+ +
+ [calls RunControl->startFailed]
+ +
+ DebuggerFinished
v
EngineSetupOk
+
[calls RunControl->StartSuccessful]
+
InferiorSetupRequested
+
(calls *Engine->setupInferior())
| |
| |
{notify- {notify-
Inferior- Inferior-
SetupOk} SetupFailed}
+ +
+ ` +-+-> InferiorSetupFailed +-+-+-+-+-+->.
+ +
InferiorSetupOk +
+ +
EngineRunRequested +
+ +
(calls *Engine->runEngine()) +
/ | | \ +
/ | | \ +
| (core) | (attach) | | +
| | | | +
{notify- {notifyER&- {notifyER&- {notify- +
Inferior- Inferior- Inferior- EngineRun- +
Unrunnable} StopOk} RunOk} Failed} +
+ + + + +
InferiorUnrunnable + InferiorRunOk + +
+ + +
InferiorStopOk EngineRunFailed +
+ v
`-+-+-+-+-+-+-+-+-+-+-+>-+
+
+
#Interrupt@InferiorRunOk# +
+ +
InferiorStopRequested +
#SpontaneousStop + +
@InferiorRunOk# (calls *Engine-> +
+ interruptInferior()) +
{notify- | | +
Spontaneous- {notify- {notify- +
Inferior- Inferior- Inferior- +
StopOk} StopOk} StopFailed} +
+ + + +
+ + + +
InferiorStopOk + +
+ + +
+ + +
+ + +
#Stop@InferiorUnrunnable# + +
#Creator Close Event# + +
+ + +
InferiorShutdownRequested +
+ +
(calls *Engine->shutdownInferior()) +
| | +
{notify- {notify- +
Inferior- Inferior- +
ShutdownOk} ShutdownFailed} +
+ + +
+ + +
#Inferior exited# + + +
| + + +
{notifyInferior- + + +
Exited} + + +
+ + + +
InferiorExitOk + + +
+ + + +
InferiorShutdownOk InferiorShutdownFailed +
* * +
EngineShutdownRequested +
+ +
(calls *Engine->shutdownEngine()) <+-+-+-+-+-+-+-+-+-+-+-+-+-+'
| |
| |
{notify- {notify-
Engine- Engine-
ShutdownOk} ShutdownFailed}
+ +
EngineShutdownOk EngineShutdownFailed
* *
DebuggerFinished
\endcode */
/* Here is a matching graph as a GraphViz graph. View it using
* \code
......@@ -302,40 +317,44 @@ sg1: }
// Additional signalling: {notifyInferiorIll} {notifyEngineIll}
// GdbEngine specific startup. All happens in EngineSetupRequested state
//
// Transitions marked by '---' are done in the individual adapters.
// Transitions marked by '+-+' are done in the GdbEngine.
//
// GdbEngine::setupEngine()
// +
// (calls *Adapter->startAdapter())
// | |
// | `---> handleAdapterStartFailed()
// | +
// | {notifyEngineSetupFailed}
// |
// handleAdapterStarted()
// +
// {notifyEngineSetupOk}
//
//
//
// GdbEngine::setupInferior()
// +
// (calls *Adapter->prepareInferior())
// | |
// | `---> handlePrepareInferiorFailed()
// | +
// | {notifyInferiorSetupFailed}
// |
// handleInferiorPrepared()
// +
// {notifyInferiorSetupOk}
/*!
\class Debugger::Internal::GdbEngine
\brief Implementation of Debugger::Engine driving a gdb executable.
GdbEngine specific startup. All happens in EngineSetupRequested state:
Transitions marked by '---' are done in the individual adapters.
Transitions marked by '+-+' are done in the GdbEngine.
\code
GdbEngine::setupEngine()
+
(calls *Adapter->startAdapter())
| |
| `---> handleAdapterStartFailed()
| +
| {notifyEngineSetupFailed}
|
handleAdapterStarted()
+
{notifyEngineSetupOk}
GdbEngine::setupInferior()
+
(calls *Adapter->prepareInferior())
| |
| `---> handlePrepareInferiorFailed()
| +
| {notifyInferiorSetupFailed}
|
handleInferiorPrepared()
+
{notifyInferiorSetupOk}
\endcode */
using namespace Core;
using namespace Debugger::Constants;
......
......@@ -134,7 +134,7 @@ DisassemblerAgentPrivate::~DisassemblerAgentPrivate()
}
/*!
\class DisassemblerAgent
\class Debugger::Internal::DisassemblerAgent
Objects from this class are created in response to user actions in
the Gui for showing disassembled memory from the inferior. After creation
......
......@@ -2075,7 +2075,7 @@ void GdbEngine::handleExecuteReturn(const GdbResponse &response)
}
/*!
\fn void GdbEngine::setTokenBarrier()
\fn void Debugger::Internal::GdbEngine::setTokenBarrier()
\brief Discard the results of all pending watch-updating commands.
This method is called at the beginning of all step/next/finish etc.
......
......@@ -57,7 +57,7 @@ namespace Internal {
///////////////////////////////////////////////////////////////////////
/*!
\class MemoryAgent
\class Debugger::Internal::MemoryAgent
Objects form this class are created in response to user actions in
the Gui for showing raw memory from the inferior. After creation
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment