diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 121 |
1 files changed, 104 insertions, 17 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 94852ec4dc1..17fc7d63795 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -139,6 +139,7 @@ software in general. We will miss him. * Stack:: Examining the stack * Source:: Examining source files * Data:: Examining data +* Optimized Code:: Debugging optimized code * Macros:: Preprocessor Macros * Tracepoints:: Debugging remote targets non-intrusively * Overlays:: Debugging programs that use overlays @@ -1808,7 +1809,7 @@ To request debugging information, specify the @samp{-g} option when you run the compiler. Programs that are to be shipped to your customers are compiled with -optimizations, using the @samp{-O} compiler option. However, many +optimizations, using the @samp{-O} compiler option. However, some compilers are unable to handle the @samp{-g} and @samp{-O} options together. Using those compilers, you cannot generate optimized executables containing debugging information. @@ -1817,22 +1818,7 @@ executables containing debugging information. without @samp{-O}, making it possible to debug optimized code. We recommend that you @emph{always} use @samp{-g} whenever you compile a program. You may think your program is correct, but there is no sense -in pushing your luck. - -@cindex optimized code, debugging -@cindex debugging optimized code -When you debug a program compiled with @samp{-g -O}, remember that the -optimizer is rearranging your code; the debugger shows you what is -really there. Do not be too surprised when the execution path does not -exactly match your source file! An extreme example: if you define a -variable, but never use it, @value{GDBN} never sees that -variable---because the compiler optimizes it out of existence. - -Some things do not work as well with @samp{-g -O} as with just -@samp{-g}, particularly on machines with instruction scheduling. If in -doubt, recompile with @samp{-g} alone, and if this fixes the problem, -please report it to us as a bug (including a test case!). -@xref{Variables}, for more information about debugging optimized code. +in pushing your luck. For more information, see @ref{Optimized Code}. Older versions of the @sc{gnu} C compiler permitted a variant option @w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this @@ -8538,6 +8524,107 @@ $1 = 1 $2 = (void *) 0x8049560 @end smallexample +@node Optimized Code +@chapter Debugging Optimized Code +@cindex optimized code, debugging +@cindex debugging optimized code + +Almost all compilers support optimization. With optimization +disabled, the compiler generates assembly code that corresponds +directly to your source code, in a simplistic way. As the compiler +applies more powerful optimizations, the generated assembly code +diverges from your original source code. With help from debugging +information generated by the compiler, @value{GDBN} can map from +the running program back to constructs from your original source. + +@value{GDBN} is more accurate with optimization disabled. If you +can recompile without optimization, it is easier to follow the +progress of your program during debugging. But, there are many cases +where you may need to debug an optimized version. + +When you debug a program compiled with @samp{-g -O}, remember that the +optimizer has rearranged your code; the debugger shows you what is +really there. Do not be too surprised when the execution path does not +exactly match your source file! An extreme example: if you define a +variable, but never use it, @value{GDBN} never sees that +variable---because the compiler optimizes it out of existence. + +Some things do not work as well with @samp{-g -O} as with just +@samp{-g}, particularly on machines with instruction scheduling. If in +doubt, recompile with @samp{-g} alone, and if this fixes the problem, +please report it to us as a bug (including a test case!). +@xref{Variables}, for more information about debugging optimized code. + +@menu +* Inline Functions:: How @value{GDBN} presents inlining +@end menu + +@node Inline Functions +@section Inline Functions +@cindex inline functions, debugging + +@dfn{Inlining} is an optimization that inserts a copy of the function +body directly at each call site, instead of jumping to a shared +routine. @value{GDBN} displays inlined functions just like +non-inlined functions. They appear in backtraces. You can view their +arguments and local variables, step into them with @code{step}, skip +them with @code{next}, and escape from them with @code{finish}. +You can check whether a function was inlined by using the +@code{info frame} command. + +For @value{GDBN} to support inlined functions, the compiler must +record information about inlining in the debug information --- +@value{NGCC} using the @sc{dwarf 2} format does this, and several +other compilers do also. @value{GDBN} only supports inlined functions +when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1 +do not emit two required attributes (@samp{DW_AT_call_file} and +@samp{DW_AT_call_line}); @value{GDBN} does not display inlined +function calls with earlier versions of @value{NGCC}. It instead +displays the arguments and local variables of inlined functions as +local variables in the caller. + +The body of an inlined function is directly included at its call site; +unlike a non-inlined function, there are no instructions devoted to +the call. @value{GDBN} still pretends that the call site and the +start of the inlined function are different instructions. Stepping to +the call site shows the call site, and then stepping again shows +the first line of the inlined function, even though no additional +instructions are executed. + +This makes source-level debugging much clearer; you can see both the +context of the call and then the effect of the call. Only stepping by +a single instruction using @code{stepi} or @code{nexti} does not do +this; single instruction steps always show the inlined body. + +There are some ways that @value{GDBN} does not pretend that inlined +function calls are the same as normal calls: + +@itemize @bullet +@item +You cannot set breakpoints on inlined functions. @value{GDBN} +either reports that there is no symbol with that name, or else sets the +breakpoint only on non-inlined copies of the function. This limitation +will be removed in a future version of @value{GDBN}; until then, +set a breakpoint by line number on the first line of the inlined +function instead. + +@item +Setting breakpoints at the call site of an inlined function may not +work, because the call site does not contain any code. @value{GDBN} +may incorrectly move the breakpoint to the next line of the enclosing +function, after the call. This limitation will be removed in a future +version of @value{GDBN}; until then, set a breakpoint on an earlier line +or inside the inlined function instead. + +@item +@value{GDBN} cannot locate the return value of inlined calls after +using the @code{finish} command. This is a limitation of compiler-generated +debugging information; after @code{finish}, you can step to the next line +and print a variable where your program stored the return value. + +@end itemize + + @node Macros @chapter C Preprocessor Macros |