optimize chkp after ldb
[charm.git] / doc / debugger / using.tex
1 %% Section: Using the debugger
2
3 Once the debugger's GUI loads, the programmer triggers the program execution by
4 clicking the \textit{Start} button. When starting by command line, the
5 application is automatically started. The program starts off displaying the user
6 and system entry points as a list of check boxes, freezing at the onset. The
7 user could choose to set breakpoints by clicking on the corresponding entry
8 points and kick off execution by clicking the \textit{Continue} Button. Figure
9 \ref{snapshot3} shows a snapshot of the debugger when a breakpoint is reached. 
10 The program freezes when a breakpoint is reached.
11
12  
13 Clicking the \textit{Freeze} button during the execution of the program freezes
14 execution, while \textit{Continue} button resumes execution. \textit{Quit}
15 button can be used to abort execution at any point of time. Entities (for
16 instance, array elements) and their contents on any processor can be viewed at
17 any point in time during execution as illustrated in Figure \ref{arrayelement}.
18
19 \begin{figure}[]
20 \includegraphics[scale=0.5, height=4in,width=3in]{figs/arrayelement}
21 \caption{Freezing program execution and viewing the contents of an array element using the Parallel Debugger}
22 \label{arrayelement}
23 \end{figure} 
24
25 Specific individual processes of the \charmpp{} program can be attached to instances of \textit{gdb} 
26 as shown in Figure \ref{gdb}. The programmer chooses which PEs to connect \textit{gdb} processes to via the checkboxes on the right side.
27 \emph{Note!} While the program is suspended in gdb for step debugging, the high-level features such as object inspection will not work.
28
29 \begin{figure}[ht!]
30 \centering
31 \includegraphics[width=6in]{figs/snapshot4-crop}
32 \caption{Parallel debugger showing instances of \textit{gdb}
33 open for the selected processor elements}
34 \label{gdb}
35 \end{figure}
36
37 \charmpp{} objects can be examined via  the \textit{View Entities on PE : Display} \ selector.  It allows the user to choose from  \textit{Charm Objects, Array Elements, Messages in Queue, Readonly Variables, Readonly Messages, Entry Points, Chare Types, Message Types and Mainchares}.  The right sideselector sets the PE upon which the request for display will be made. The user may then click on the \textit{Entity} to see the details. 
38
39 % The programmer can implement the function \texttt{pupCpdData(PUP::er
40 % \&)} for an array element and thereby control the information
41 % displayed by the debugger by choosing the data to be displayed and by
42 % inserting appropriate comments. An example is illustrated in Figure
43 % \ref{instr}.
44
45 % \begin{verbatim}
46 % // MyArray is a chare array where each array
47 % // element has a member variable data, 
48 % // which is an integer array
49
50 % void MyArray::pupCpdData(PUP::er &p) {
51 %   p.comment("contents of integer array: data");
52 %   p|data;  }
53 % \end{verbatim}
54
55 \subsubsection{Memory View}
56 \label{sec:memory}
57
58 The menu option Action~$\rightarrow$~Memory allows the user to display the
59 entire memory layout of a secific processor. An example is shown in
60 figure~\ref{fig:memory}. This layout is colored and the colors have the
61 following meaning:
62
63 \begin{figure}[ht!]
64 \centering
65 \includegraphics[scale=0.5]{figs/memoryView}
66 \caption{Main memory view}
67 \label{fig:memory}
68 \end{figure}
69
70 \begin{description}
71
72 \item[red] memory allocated by the \charmpp{} Runtime System;
73
74 \item[blue] memory allocatded directly by the user in its code;
75
76 \item[pink] memory used by messages;
77
78 \item[orange] memory allocated to a chare element;
79
80 \item[black] memory not allocated;
81
82 \item[gray] a big jump in memory addresses due to the memory pooling system, it represent a large portion of virtual space not used between two differnt zones of used virtual space address;
83
84 \item[yellow] the currently selected memory slot;
85
86 \end{description}
87
88 Currently it is not possible to change this color association. The bottom part
89 of the view shows the stack trace at the moment when the highlighted (yellow)
90 memory slot was allocated. By left clicking on a particular slot, this slot is
91 fixed in highlight mode. This allows a more accurate inspection of its stack
92 trace when this is large and does not fit the window.
93
94 Info~$\rightarrow$Show~Statistics will display a small information box like the
95 one in Figure~\ref{fig:memory-stat}.
96
97 \begin{figure}[ht!]
98 \centering
99 \includegraphics[scale=0.5]{figs/memoryStatistics}
100 \caption{Information box display memory statistics}
101 \label{fig:memory-stat}
102 \end{figure}
103
104 A useful tool of this view is the memroy leak search. This is located in the
105 menu Action~$\rightarrow$~Search~Leaks. The processor under inspection runs a
106 reacheability test on every memory slot allocated to find if there is a pointer
107 to it. If there is none, the slot is partially colored in green, to indicate its
108 status of leak. The user can the inspect further these slots. 
109 Figure~\ref{fig:memory-leak} shows some leaks being detected.
110
111 \begin{figure}[ht!]
112 \centering
113 \includegraphics[scale=0.5]{figs/memoryLeaking}
114 \caption{Memory view after running the Search Leaks tool}
115 \label{fig:memory-leak}
116 \end{figure}
117
118 If the memory window is kept open while the application is unfrozen and makes
119 progress, the loaded image will become obsolete. To cope with this, the
120 ``Update'' button will refresh the view to the current allocation status. All
121 the leaks that had been already found as such, will still be partially colored
122 in green, while the newly allocated slots will not, even if leaking. To update
123 the leak status, re-run the Search Leaks tool.
124
125 Finally, when a specific slot is highlighted, the menu
126 Action~$\rightarrow$~Inspect opens a new window displaying the content of the
127 memory in that slot, as interpreted by the debugger (see next subsection for
128 more details on this).
129
130 \subsubsection{Inspector framework}
131 \label{sec:inspector}
132
133 Without any code rewriting of the application, CharmDebug is capable of loading
134 a raw area of memory and parse it with a given type name. The result (as shown
135 in Fig.~\ref{fig:inspect}), is a browseable tree. The initial type of a memory
136 area is given by its virtual table pointer (\charmpp{} objects are virtual and
137 therefore loadbable). In the case of memory slots not containing classes with
138 virtual methods, no display will be possible.
139
140 \begin{figure}[ht!]
141 \centering
142 \includegraphics[scale=0.5]{figs/memoryInspector}
143 \caption{Raw memory parsed and displayed as a tree}
144 \label{fig:inspect}
145 \end{figure}
146
147 When the view is open and is displaying a type, by right clicking on a leaf
148 containing a pointer to another memory location, a popup menu will allow the
149 user to ask for its dereference (shown in Fig.~\ref{fig:inspect}). In this case,
150 CharmDebug will load this raw data as well and parse it with the given type name
151 of the pointer. This dereference will be inlined and the leaf will become an
152 internal node of the browse tree.
153