msgQ: some code doc and minor cleanup
[charm.git] / doc / debugger / manual.tex
1 \documentclass[10pt]{article}
2
3 \usepackage{../pplmanual}
4 \input{../pplmanual}
5
6 \makeindex
7
8 \title{\charmpp\\ Debugger Manual}
9 \version{0.2}
10 \credits{
11 By Filippo Gioachin, Rashmi Jyothi, Orion Lawlor, Eric Bohm
12 }
13 %%Rashmi didn't actually write the manual, but she wrote the debugger and I'm cutting and pasting much of this document from her thesis and the _Debugging Support for Charm++_ paper written by Rashmi and Orion. - Eric
14 %% After starting working on the debugger, and implemented the memory views, I revised the entire manual to be conform to the new implementation of CharmDebug. - Filippo
15 \begin{document}
16
17 \maketitle
18
19 \section{Introduction}
20 \label{sec:intro}
21 \input{intro}
22
23
24 \section{Building the \charmpp{} Debug Tool}
25
26 Every version of \charmpp{} is already provided with a compiled version
27 of the debugger, and is located under charm/java/bin/charmdebug. This
28 compiled version is built with java 1.4.2.
29
30 In case of necessity, to rebuild the debugger, checkout a fresh copy of charm
31 and then
32
33 \begin{verbatim}
34   cd charm/java;
35   ant clean;
36   ant;
37 \end{verbatim}
38
39 This will recreate charm/bin/charmdebug for your java version.
40
41
42 \section{Preparing the \charmpp Application for Debugging}
43
44 No instrumentation is required to use the \charmpp{} debugger.  Being
45 CCS based, you can use it to set and step through entry point
46 breakpoints and examine \charmpp{} structures on any \charmpp{}
47 application.
48
49 Nevertheless, for some features to be present some additional options might
50 be required at either compile or link time:
51
52 \begin{itemize}
53
54 \item In order to provide a symbol conversion of the assembly code executed
55 by the application, the \textit{-g} option is needed at compile time. This
56 conversion is needed to provide function names as well as source file names
57 and line numbers wherever useful. This is useful also to fully utilize gdb
58 (or any other serial debugger) on one or more processes.
59
60 \item Optimization options, with their nature of transforming the source code,
61 can produce a mismatch between the function displayed in the debugger (for
62 example in a stack trace) and the functions present in the source code. To
63 produce information coherent with source code, optimization is discouraged.
64
65 \item The link time option \textit{-memory charmdebug} is needed in
66 order to gather information regarding the memory of the application. This
67 includes both the Memory view (see \ref{sec:memory}) and the Inspector
68 framework (see \ref{sec:inspector}).
69
70 \end{itemize}
71
72 \subsection{Record Replay}
73
74 The \textit{Record Replay} feature is independant of the charmdebug
75 application.  It is a mechanism used to detect bugs that happen only
76 once in a while depending on the order in which messages are
77 processed. The program in consideration is first run in a record mode
78 which produces a trace. When the program is run in replay mode it uses
79 a previous trace gotten from a record run to ensure that messages are
80 processed in the same order as the recorded run. The idea is to make
81 use of a message-sequence number and a theorem says that the serial
82 numbers will be the same if the messages are processed in the same
83 order. \cite{rashmithesis}
84
85 \textit{Record Replay} tracing is automatically enabled for \charmpp{}
86 programs and requires nothing special to be done during compilation
87 (linking with the option ``\textit{-tracemode recordreplay}'' used to
88 be necessary).  At run time, the ``\textit{+record}'' option is used,
89 which records messages in order in a file for each processor.  The
90 same execution order can be replayed using the ``\textit{+replay}''
91 runtime option, which can be used at the same time as the other
92 debugging tools in \charmpp{}.
93
94 \emph{ Note! } If your \charmpp{} is built with {\tt CMK\_OPTIMIZE} on,
95 all tracing will be disabled. So, use an unoptimized \charmpp{} to do your
96 debugging.
97
98 \section{Running the Debugger}
99
100 \subsection{Charmdebug command line parameters}
101
102 \begin{description}
103
104 \item[{\tt -pes}] Number of PEs 
105
106 \item[{\tt +p}] Number of PEs 
107
108 \item[{\tt -host}] hostname of CCS server for application
109
110 \item[{\tt -user}] the username to use to connect to the hostname selected
111
112 \item[{\tt -port}] portnumber of CCS server for application
113
114 \item[{\tt -sshtunnel}] force the communication between client and server
115 (in particular the one for CCS) to be tunnelled through ssh. This allow the
116 bypass of firewalls.
117
118 \item[{\tt -display}] X Display
119
120 \end{description}
121
122 \subsection{Basic usage}
123
124 To run an application locally via the debugger on 4 pes with command line options for your pgm (e.g. opt1 opt2 ):
125
126 \begin{verbatim}
127   charmdebug pgm +p4 4 opt1 opt2
128 \end{verbatim}
129
130 If the application should be run in a remote cluster behind a firewall, the previous command line will become:
131
132 \begin{verbatim}
133   charmdebug -host cluster.inst.edu -user myname -sshtunnel pgm +p4 4 opt1 opt2
134 \end{verbatim}
135
136 Charmdebug can also be executed without any parameters.  The user can
137 then choose the application to launch and its command line parameters
138 from within the \texttt{File} menu as shown in Figure~\ref{menu}.
139
140 \begin{figure}[]
141 \includegraphics[scale=0.5, height=3in, width=3in]{figs/menu}
142 \caption{Using the menu to set parameters for the \charmpp{} program}
143 \label{menu}
144 \end{figure}
145
146
147 \emph{Note: charmdebug command line launching only works on net-*
148 builds of \charmpp{} }
149
150 To replay a previously recorded session:
151
152 \begin{verbatim}
153   charmdebug pgm +p4 opt1 opt2  +replay
154 \end{verbatim}
155
156 %%uncomment this when we fix the debugger so it works remotely
157
158 %% \subsection{Connecting to a running application}
159
160 %% To connect the debugger to a previously launched application.  The
161 %% application needs to have been launched with the ccs server feature
162 %% enabled.
163
164 %% \begin{verbatim}
165 %%   charmrun pgm ++server ++server-port 29999
166 %%   charmdebug pgm -port 29999
167 %% \end{verbatim}
168
169
170 %% \subsection{Connecting to a remote application}
171 %% \begin{verbatim}
172 %%   charmdebug pgm +p4 opt1 opt2   -host remotehost -port 29999
173 %% \end{verbatim}
174
175 %% To have your application freeze upon start so you can initiate flow
176 %% control via the debugger.
177 %% \begin{verbatim}
178 %%   charmdebug pgm +p4 opt1 opt2   -host remotehost -port 29999 +cpd
179 %% \end{verbatim}
180
181 \subsection{Charm Debugging Related Options}
182
183 When using the charm debugger to launch your application, it will automatically
184 set these to defaults appropriate for most situations.
185
186 \begin{description}
187
188 \item[{\tt +cpd}] Triggers application freeze at startup for debugger.
189
190 \item[{\tt ++charmdebug}] Triggers charmrun to provide some information about the
191 executable, as well as provide an interface to gdb for querying.
192
193 \item[{\tt +debugger}] Which debuggers to use.
194
195 \item[{\tt ++debug}] Run each node under gdb in an xterm window, prompting
196 the user to begin execution.
197
198 \item[{\tt ++debug-no-pause}] Run each node under gdb in an xterm window
199 immediately (i.e. without prompting the user to begin execution).
200
201  \emph{ Note: } If you're using the charm debugger it will probably be
202  best to control the sequential (i.e. gdb) debuggers from within its
203  GUI interface.
204  
205 \item[{\tt ++DebugDisplay}]          X Display for xterm
206
207 \item[{\tt ++server-port}]      Port to listen for CCS requests
208
209 \item[{\tt ++server}]           Enable client-server (CCS) mode
210
211 \item[{\tt +record}]           Use the recordreplay tracemode to record the exact event/message sequence for later use.  
212
213 \item[{\tt +replay}]           Force the use of recorded log of events/messages  to exactly reproduce a previous run.
214
215   The preceding pair of commands {\tt +record +replay} are used to
216   produce the ``instant replay'' feature.  This feature is valuable
217   for catching errors which only occur sporadically.  Such bugs which
218   arise from the nondeterminacy of parallel execution can be
219   fiendishly difficult to replicate in a debugging environment.
220   Typical usage is to keep running the application with +record until
221   the bug occurs.  Then run the application under the debugger with
222   the +replay option.
223
224 \end{description}
225
226 \subsection{Charmdebug limitations}
227
228 \subsubsection{Clusters}
229
230 Charmdebug is currently limited to applications started directly by the debugger
231 due to implementation peculiarities. It will be extended to support connection
232 to remote running applications in the near future. 
233 %%Behavior on a cluster can be
234 %%recorded and then replayed in a local run.
235
236 Due to the current implementation, the debugging tool is limited to net-*
237 versions. Other builds of \charmpp{} might have unexpected behaviour. In the near
238 future this will be extended at least to the mpi-* versions.
239
240 \subsubsection{Record Replay}
241 The \texttt{record replay} feature does not work well with spontaneous
242 events.  Load balancing is the most common form of spontaneous event
243 in that it occurs periodically with no other causal event. As per
244
245 \begin{figure}[]
246 \includegraphics[scale=0.5,height=4in, width=3in]{figs/snapshot3}
247 \caption{Parallel debugger when a break point is reached}
248 \label{snapshot3}
249 \end{figure}
250
251 As per Rashmi's thesis: \textit{ There are some unique issues for
252 replay in the context of Charm because it provides high-level support
253 for dynamic load balancing, quiescence detection and information
254 sharing. Many of the load balancing strategies in Charm have a
255 spontaneous component. The strategy periodically checks the sizes of
256 the queues on the local processor. A replay load balancing strategy
257 implements the known load redistribution. The behavior of the old
258 balancing strategy is therefore not replayed only its effect is. Since
259 minimal tracing is used by the replay mechanism the amount of
260 perturbation due to tracing is reduced. The replay mechanism is
261 proposed as a debugging support to replay asynchronous message arrival
262 orders.}
263
264 Moreover, if your application crashes without a clean shutdown, the log may be
265 lost with the application.
266
267 \subsection{Using the Debugger}
268 \label{sec:using}
269 \input{using}
270
271
272 \section{Debugger Implementation Details}
273 \label{sec:implementation}
274 \input{implementation}
275
276 \end{document}