Warning, /kdevelop/kdevelop/plugins/gdb/DESIGN.txt is written in an unsupported language. File is not indexed.
0001 0002 This document describes the design of KDevelop's debugger part. Note that it's 0003 a work in progress, and sometimes describes desired design, not the actual 0004 one. 0005 0006 == Components and lifecycle == 0007 0008 Debugger part consists of low-lever "controller" that handles talking 0009 with gdb and remembering what state gdb is in, a number of view widgets, showing 0010 the state of the program, and a number of places where user can click to 0011 affect the program. 0012 0013 What makes them all work together are "events" that controller sends 0014 to all interested parties. They are: 0015 0016 - Debugger exited. All view classes and actions become disabled and hidden 0017 - Program exited. All view classes that can't be used without program 0018 become disabled. 0019 - Debugger is busy executing a command. All actions become disabled. 0020 - Debugger is waiting for command. All actions becomes enabled. 0021 - Program state changed. All views flush all cached data and 0022 reload the content. 0023 - Current thread/stack frame changed. All views switch to showing that 0024 thread/frame. 0025 0026 The distinction between "program state change" and "thread/frame" changed is 0027 that the latter does not imply that any *data* changed, and so it's not 0028 necessary to clear already cached data for other threads. 0029 0030 == Command execution == 0031 0032 The controller has a queue of commands to send to gdb. A command typically 0033 has a callback (pair of QObject* and a member pointer) to be called when 0034 command is done. 0035 0036 When the queue is non-empty, and debugger is not busy executing the previous 0037 command, the controller will send the command from the queue top to the gdb. 0038 The command being executed is remembed in the currentCmd_ member variable. 0039 Gdb will reply with a number of "out-of-band" responses, followed by one 0040 "done" or "error" response. 0041 0042 The "done"/"error" response, when using MI interface, is a tree-line structure 0043 that's parsed with into GDBMI::ResultRecord structure, that is then passed 0044 to callback associated with the current command. Say, for "get me value of 0045 expression" command, MI response includes textual "value" field that can be 0046 used by any part of GUI to show the value. After callback is called, 0047 controller deletes the current command and then tries to execute next one from 0048 the queue, if there's one. 0049 0050 The commands related to running program (continue/step/etc) are handled in 0051 a bit special way. Instead of calling any callbacks, controller performs 0052 predefined set of steps: 0053 0054 - Decide what's the reason for stop, and maybe do something special 0055 0056 - For stop on shared lib load, just continue 0057 0058 - For stop on breakpoint, run the breakpoint commands if any. 0059 0060 - Set a flag that program state might have changed, and must be reloaded 0061 0062 - Since hitting tracepoint adds extra commands, including possibly 0063 "continue", we don't start reloading widgets immediately, instead 0064 we wait for all commands currently in queue to get executed. 0065 0066 - Once there are no commands in queue, and "reload_program_state" flag is 0067 set, we raise the 'program_state_changed' event. All widgets react to 0068 that by queueing commands for reloading their state. 0069 0070 0071 0072 0073 0074 0075 0076 0077 0078 0079 0080 0081 0082 Note that all commands are executed in the order they were queued, so if you 0083 add several commands at the same time, they are executed "automically". Each 0084 one sees the gdb state that the previous one has left it in. 0085 0086 The MI protocol is stateful, that is there are things like current thread 0087 and current stack that affect the meaning of commands. Take care to never 0088 switch such "current" variables unless it's explicitly asked by the user. 0089 This means that if you have to switch thread/frame, always switch it back 0090 as the last command in a sequences. 0091 0092 0093 == Breakpoints handling == 0094 0095 Whenever a new breakpoint is added, or an existing breakpoint is modified, 0096 we immediately try to send the proper commands to gdb. Note that we 0097 don't try to check which properties of breakpoint were modified, we 0098 just send all breakpoint data. 0099 0100 This is not always possible, because debugger might be busy, or just 0101 not started yet. In this case, we set 'pending' flag for breakpoint. Each time 0102 the debugger becomes free, we try to send the pending breakpoint again. 0103 0104 0105 0106 0107 0108 0109 0110 0111 0112 0113