users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[ghc.git] / docs / users_guide / debug-info.rst
1 Debugging compiled programs
2 ===========================
3
4 Since the 7.10 release GHC can emit a debugging information to help debugging
5 tools understand the code that GHC produces. This debugging information is
6 useable by most UNIX debugging tools.
7
8 .. ghc-flag:: -g
9               -g⟨n⟩
10     :shortdesc: Produce DWARF debug information in compiled object files.
11         ⟨n⟩ can be 0, 1, or 2, with higher numbers producing richer
12         output. If ⟨n⟩ is omitted level 2 is assumed.
13     :type: dynamic
14     :category: debugging
15
16     :since: 7.10, numeric levels since 8.0
17
18     Emit debug information in object code. Currently only DWARF debug
19     information is supported on x86-64 and i386. Currently debug levels 0
20     through 3 are accepted, with 0 disabling debug information production.
21     Levels 1 through 3 are functionally equivalent.
22
23
24 Tutorial
25 --------
26
27 Let's consider a simple example,
28
29 .. code-block:: hs
30    :linenos:
31
32     -- fib.hs
33     fib :: Int -> Int
34     fib 0 = 0
35     fib 1 = 1
36     fib n = fib (n-1) + fib (n-2)
37
38     main :: IO ()
39     main = print $ fib 50
40
41 Let's first see how execution flows through this program. We start by telling
42 GHC that we want debug information,
43
44 .. code-block:: sh
45
46     $ ghc -g -rtsopts fib.hs
47
48 Here we used the ``-g`` option to inform GHC that it should add debugging
49 information in the produced binary. There are three levels of debugging
50 output: ``-g0`` (no debugging information, the default), ``-g1`` (sufficient for
51 basic backtraces), ``-g2`` (or just ``-g`` for short; emitting everything GHC knows).
52 Note that this debugging information does not affect the optimizations performed
53 by GHC.
54
55 .. tip::
56    Under Mac OS X debug information is kept apart from the executable. After
57    compiling the executable you'll need to use the ``dsymutil`` utility to
58    extract the debugging information and place them in the debug archive,
59
60    .. code-block:: sh
61
62       $ dsymutil fib
63
64    This should produce a file named ``fib.dSYM``.
65
66 Now let's have a look at the flow of control. For this we can just start our
67 program under ``gdb`` (or an equivalent debugger) as we would any other native
68 executable,
69
70 .. code-block:: none
71
72     $ gdb --args ./Fib +RTS -V0
73     Reading symbols from Fib...done.
74     (gdb) run
75     Starting program: /opt/exp/ghc/ghc-dwarf/Fib
76     [Thread debugging using libthread_db enabled]
77     Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
78     ^C
79     Program received signal SIGINT, Interrupt.
80     0x000000000064fc7c in cfy4_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:424
81     424     minusInteger x y = inline plusInteger x (inline negateInteger y)
82     (gdb)
83
84 Here we have used the runtime system's ``-V0`` option to disable the RTS's
85 periodic timer which may interfere with our debugging session. Upon breaking
86 into the program ``gdb`` shows us a location in our source program corresponding
87 to the current point of execution.
88
89 Moreover, we can ask ``gdb`` to tell us the flow of execution that lead us to
90 this point in the program,
91
92 .. code-block:: none
93
94    (gdb) bt
95    #0  0x000000000064fc7c in cfy4_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:424
96    #1  0x00000000006eb0c0 in ?? ()
97    #2  0x000000000064301c in cbuV_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:323
98    #3  0x000000000064311b in integerzmgmp_GHCziIntegerziType_eqInteger_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:312
99    #4  0x0000000000406eca in roz_info () at Fib.hs:2
100    #5  0x00000000006eb0c0 in ?? ()
101    #6  0x000000000064f075 in cfru_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:412
102    #7  0x00000000006eb0c0 in ?? ()
103    #8  0x000000000064f075 in cfru_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:412
104    #9  0x00000000006eb0c0 in ?? ()
105    #10 0x000000000064eefe in integerzmgmp_GHCziIntegerziType_plusInteger_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:393
106    ...
107    #64 0x0000000000643ac8 in integerzmgmp_GHCziIntegerziType_ltIntegerzh_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:343
108    #65 0x00000000004effcc in base_GHCziShow_zdwintegerToString_info () at libraries/base/GHC/Show.hs:443
109    #66 0x00000000004f0795 in base_GHCziShow_zdfShowIntegerzuzdcshow_info () at libraries/base/GHC/Show.hs:145
110    #67 0x000000000048892b in cdGW_info () at libraries/base/GHC/IO/Handle/Text.hs:595
111    #68 0x0000000000419cb2 in base_GHCziBase_thenIO1_info () at libraries/base/GHC/Base.hs:1072
112
113
114 .. hint::
115
116     Here we notice the first bit of the stack trace has many unidentified stack
117     frames at address ``0x006eb0c0``. If we ask ``gdb`` about this location, we
118     find that these frames are actually STG update closures,
119
120     .. code-block:: none
121
122         (gdb) print/a 0x006eb0c0
123         $1 = 0x6eb0c0 <stg_upd_frame_info>
124
125     The reason ``gdb`` doesn't show this symbol name in the backtrace output is an
126     infidelity in its interpretation of debug information, which assumes an
127     invariant preserved in C but not Haskell programs. Unfortunately it is
128     necessary to work around this manually until this behivior is fixed
129     upstream.
130
131 .. note::
132
133     Because of the aggressive optimization that GHC performs to the programs it
134     compiles it is quite difficult to pin-point exactly which point in the source
135     program a given machine instruction should be attributed to. In fact,
136     internally GHC associates each instruction with a **set** of source
137     locations. When emitting the standard debug information used by ``gdb`` and
138     other language-agnostic debugging tools, GHC is forced to heuristically
139     choose one location from among this set.
140
141     For this reason we should be cautious when interpretting the source locations
142     provided by GDB. While these locations will usually be in some sense
143     "correct", they aren't always useful. This is why profiling tools targetting
144     Haskell should supplement the standard source location information with
145     GHC-specific annotations (emitted with ``-g2``) when assigning costs.
146
147 Indeed, we can even set breakpoints,
148
149 .. code-block:: none
150
151     (gdb) break fib.hs:4
152     Breakpoint 1 at 0x406c60: fib.hs:4. (5 locations)
153     (gdb) run
154     Starting program: /opt/exp/ghc/ghc-dwarf/Fib
155
156     Breakpoint 1, c1RV_info () at Fib.hs:4
157     4        fib n = fib (n-1) + fib (n-2)
158     (gdb) bt
159     #0  c1RV_info () at Fib.hs:4
160     #1  0x00000000006eb0c0 in ?? ()
161     #2  0x0000000000643ac8 in integerzmgmp_GHCziIntegerziType_ltIntegerzh_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:343
162     #3  0x00000000004effcc in base_GHCziShow_zdwintegerToString_info () at libraries/base/GHC/Show.hs:443
163     #4  0x00000000004f0795 in base_GHCziShow_zdfShowIntegerzuzdcshow_info () at libraries/base/GHC/Show.hs:145
164     #5  0x000000000048892b in cdGW_info () at libraries/base/GHC/IO/Handle/Text.hs:595
165     #6  0x0000000000419cb2 in base_GHCziBase_thenIO1_info () at libraries/base/GHC/Base.hs:1072
166     #7  0x00000000006ebcb0 in ?? () at rts/Exception.cmm:332
167     #8  0x00000000006e7320 in ?? ()
168     (gdb)
169
170 Due to the nature of GHC's heap and the heavy optimization that it performs, it
171 is quite difficult to probe the values of bindings at runtime. In this way, the
172 debugging experience of a Haskell program with DWARF support is still a bit
173 impoverished compared to typical imperative debuggers.
174
175 Requesting a stack trace from Haskell code
176 ------------------------------------------
177
178 GHC's runtime system has built-in support for collecting stack trace information
179 from a running Haskell program. This currently requires that the ``libdw``
180 library from the ``elfutils`` package is available. Of course, the backtrace
181 will be of little use unless debug information is available in the executable
182 and its dependent libraries.
183
184 Stack trace functionality is exposed for use by Haskell programs in the
185 :base-ref:`GHC.ExecutionStack.` module. See the Haddock
186 documentation in this module for details regarding usage.
187
188 Requesting a stack trace with ``SIGUSR2``
189 -----------------------------------------
190
191 On POSIX-compatible platforms GHC's runtime system (when built with ``libdw``
192 support) will produce a stack trace on ``stderr`` when a ``SIGUSR2`` signal is
193 received. For instance (using the same ``fib.hs`` as above),
194
195 .. code-block:: sh
196
197     $ ./fib  &  killall -SIGUSR2 fib
198     0x7f3176b15dd8    dwfl_thread_getframes (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
199     0x7f3176b1582f    (null) (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
200     0x7f3176b15b57    dwfl_getthreads (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
201     0x7f3176b16150    dwfl_getthread_frames (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
202           0x6dc857    libdwGetBacktrace (rts/Libdw.c:248.0)
203           0x6e6126    backtrace_handler (rts/posix/Signals.c:541.0)
204     0x7f317677017f    (null) (/lib/x86_64-linux-gnu/libc-2.19.so)
205           0x642e1c    integerzmgmp_GHCziIntegerziType_eqIntegerzh_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:320.1)
206           0x643023    integerzmgmp_GHCziIntegerziType_eqInteger_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:312.1)
207           0x406eca    roz_info (/opt/exp/ghc/ghc-dwarf//Fib.hs:2.1)
208           0x6eafc0    stg_upd_frame_info (rts/Updates.cmm:31.1)
209           0x64ee06    integerzmgmp_GHCziIntegerziType_plusInteger_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:393.1)
210           0x6eafc0    stg_upd_frame_info (rts/Updates.cmm:31.1)
211     ...
212           0x6439d0    integerzmgmp_GHCziIntegerziType_ltIntegerzh_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:343.1)
213           0x4efed4    base_GHCziShow_zdwintegerToString_info (libraries/base/GHC/Show.hs:442.1)
214           0x4f069d    base_GHCziShow_zdfShowIntegerzuzdcshow_info (libraries/base/GHC/Show.hs:145.5)
215           0x488833    base_GHCziIOziHandleziText_zdwa8_info (libraries/base/GHC/IO/Handle/Text.hs:582.1)
216           0x6ebbb0    stg_catch_frame_info (rts/Exception.cmm:370.1)
217           0x6e7220    stg_stop_thread_info (rts/StgStartup.cmm:42.1)
218
219
220 Implementor's notes: DWARF annotations
221 --------------------------------------
222
223 .. note::
224    Most users don't need to worry about the details described in this section.
225    This discussion is primarily targeted at tooling authors who need to
226    interpret the GHC-specific DWARF annotations contained in compiled binaries.
227
228 When invoked with the ``-g`` flag GHC will produce standard `DWARF v4
229 <http://dwarfstd.org/>`__ debugging information. This format is used by nearly
230 all POSIX-compliant targets and can be used by debugging and performance tools
231 (e.g. ``gdb``, ``lldb``, and ``perf``) to understand the structure of
232 GHC-compiled programs.
233
234 In particular GHC produces the following DWARF sections,
235
236 ``.debug_info``
237   Debug information entities (DIEs) describing all of the basic blocks in the
238   compiled program.
239
240 ``.debug_line``
241   Line number information necessary to map instruction addresses to line numbers
242   in the source program.
243
244   Note that the line information in this section is not nearly as rich as the
245   information provided in ``.debug_info``. Whereas ``.debug_line`` requires that
246   each instruction is assigned exactly one source location, the DIEs in
247   ``.debug_info`` can be used to identify all relevant sources locations.
248
249 ``.debug_frames``
250   Call frame information (CFI) necessary for stack unwinding to produce a call
251   stack trace.
252
253 ``.debug_arange``
254   Address range information necessary for efficient lookup in debug information.
255
256
257 Debugging information entities
258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259
260 GHC may produce the following standard DIEs in the ``.debug_info`` section,
261
262 ``DW_TAG_compile_unit``
263   Represents a compilation unit (e.g. a Haskell module).
264
265 ``DW_TAG_subprogram``
266   Represents a C-- top-level basic block.
267
268 ``DW_TAG_lexical_block``
269   Represents a C-- basic block. Note that this is a slight departure from the
270   intended meaning of this DIE type as it does not necessarily reflect
271   lexical scope in the source program.
272
273 As GHC's compilation products don't map perfectly onto DWARF constructs,
274 GHC takes advantage of the extensibility of the DWARF standard to provide
275 additional information.
276
277 Unfortunately DWARF isn't expressive enough to fully describe the code
278 that GHC produces. This is most apparent in the case of line
279 information, where GHC is forced to choose some between a variety of
280 possible originating source locations. This limits the usefulness of
281 DWARF information with traditional statistical profiling tools. For
282 profiling it is recommended that one use the extended debugging
283 information. See the *Profiling* section below.
284
285 In addition to the usual DIEs specified by the DWARF specification, GHC
286 produces a variety of others using the vendor-extensibility regions of
287 the tag and attribute space.
288
289 ``DW_TAG_ghc_src_note``
290 ^^^^^^^^^^^^^^^^^^^^^^^
291
292 ``DW_TAG_ghc_src_note`` DIEs (tag 0x5b01) are found as children of
293 ``DW_TAG_lexical_block`` DIEs. They describe source spans which gave rise to the
294 block; formally these spans are causally responsible for produced code: changes
295 to code in the given span may change the code within the block; conversely
296 changes outside the span are guaranteed not to affect the code in the block.
297
298 Spans are described with the following attributes,
299
300 ``DW_AT_ghc_span_file`` (0x2b00, string)
301   the name of the source file
302
303 ``DW_AT_ghc_span_start_line`` (0x2b01, integer)
304   the line number of the beginning of the span
305
306 ``DW_AT_ghc_span_start_col`` (0x2b02, integer)
307   the column number of the beginning of the span
308
309 ``DW_AT_ghc_span_end_line`` (0x2b03, integer)
310   the line number of the end of the span
311
312 ``DW_AT_ghc_span_end_col`` (0x2b04, integer)
313   the column number of the end of the span
314
315
316 Further Reading
317 ---------------
318
319 For more information about the debug information produced by GHC see
320 Peter Wortmann's PhD thesis, `*Profiling Optimized Haskell: Causal
321 Analysis and Implementation* <http://etheses.whiterose.ac.uk/8321/>`__.