docs/debug.pod

   1 # Copyright (C) 2001-2009, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/debug.pod - Debugging Parrot
   7
   8 =head1 ABSTRACT
   9
  10 This document describes how to debug various parts of Parrot.
  11
  12 =head1 VERSION
  13
  14 $Revision $
  15
  16 =head1 THE PARROT BINARY
  17
  18 =head2 Using a debugger
  19
  20 Per default the C<parrot> binary is being built with debugging symbols. This
  21 means that you can run C<parrot> under an debugger like C<gdb>.
  22
  23 Debugging support can be explicitly enabled with:
  24
  25     shell> perl Configure.pl --debugging
  26     shell> make
  27
  28 For testing it might be a good idea to make test runs without debug support. So
  29 debugging can also be turned off with:
  30
  31   shell> perl Configure.pl --debugging=0
  32   shell> make
  33
  34 =head2 Using a memory checker
  35
  36 You could, and should, also run the tests with a memory checker such as
  37 C<valgrind>.  You can enable C<valgrind>, by running:
  38
  39   shell> make test VALGRIND="valgrind --log-file=/tmp/grind"
  40
  41 Another possibility is to use Electric Fence, or ...
  42
  43 =head2 MEMORY MANAGEMENT
  44
  45 Some of the more frequent and exasperating C<parrot> bugs are related to memory
  46 management in general, and garbage collection in particular.
  47
  48 Infant mortality
  49
  50 See F<docs/dev/infant.pod> for details of one frequent problem: infant
  51 mortality. Infant mortality is when you create a Parrot object, but the garbage
  52 collector runs before you put it into a Parrot register or in something else
  53 that is itself within a Parrot register.
  54
  55 To help in resolving these issues, the parrot binary accepts a C<--gc-debug>
  56 flag. This flag makes garbage collection occur as frequently as possible, which
  57 maximizes the probability that any newborn objects will run afoul of the
  58 garbage collector.
  59
  60 Within the C<--gc-debug> mode, there is another tool to help narrow down the
  61 problem. You can edit F<include/parrot/gc_api.h> and C<#define> the C<GC_VERBOSE> flag to
  62 1.  After recompiling C<parrot>, the garbage collector will perform additional
  63 checks. After the garbage collector has traced all objects to find which ones
  64 are still alive, it will scan through all of the dead objects to see if any of
  65 them believe they are alive (which will happen for infants, since they come
  66 into existence marked live.) If it finds any, it will print them out.
  67 You can then re-run the program with a breakpoint set on the routine that
  68 allocated the object (e.g. C<get_free_object> in F<src/gc/mark_sweep.c>).
  69 You'll probably want to make the breakpoint conditional on the object having
  70 the version number that was reported, because the same memory location will
  71 probably hold many different objects over the lifetime of the program.
  72
  73 =head1 PIR AND PASM CODE
  74
  75 Let's say you have written (or generated) a huge .pasm or .pir file.  It's not
  76 working. You'd like some help in figuring out why.
  77
  78 =head2 parrot_debugger
  79
  80 One possible tool is C<parrot_debugger>, the Parrot Debugger.
  81 See F<docs/debugger.pod> for details on it.
  82
  83 =head1 PIR CODE GENERATION
  84
  85 The C<parrot> binary has a bunch of debugging flags for spewing out information
  86 about various aspects of its processing. See L<running.pod> for a
  87 list of flags. Or have a look at the information provided by:
  88
  89   shell> parrot --help
  90
  91 or
  92
  93   shell> parrot --help-debug
  94
  95
  96 =head1 BACKTRACING
  97
  98 =head2 auto-magical
  99
 100 If Parrot is built on a system with GNU libc it is capable of automatically
 101 generating a backtrace on C<stderr> for debugging purposes.  Currently these
 102 automatically backtraces are only generated by assertion failures but in the
 103 future they also be produced by other bad events (for example, C<SEGV>).
 104
 105 Here is an example of a what a backtrace might look like:
 106
 107     Backtrace - Obtained 15 stack frames (max trace depth is 32).
 108       (unknown)
 109         Parrot_confess
 110           Parrot_str_new_COW
 111             Parrot_String_get_string
 112               Parrot_set_s_p
 113                 (unknown)
 114                   (unknown)
 115                     (unknown)
 116                       (unknown)
 117                         Parrot_runops_fromc_args
 118                           Parrot_runcode
 119                             (unknown)
 120                               imcc_run
 121                                 (unknown)
 122                                   __libc_start_main
 123                                     (unknown)
 124
 125 It must be noted that glibc's backtraces are not without limitation.  It's
 126 method depends completely on information that is available at run time.
 127
 128 =over
 129
 130 =item * Functions marked as C<static> can only be identified by address as they
 131 have no "symbol name" for dynamic linking in the executable's symbol table.
 132 Static functions will appears as C<(unknown)>.
 133
 134 =item * There must be some means available for walking the stack at runtime.
 135 On x86(-64)? the "stack pointer" must be in C<[re]sp> register.  For example,
 136 this C<gcc> compilation flag would break backtracing (except for functions
 137 that do dynamic allocation on the stack as this optimization can no be allied
 138 to them).  C<perl Configure.pl --ccflags=-fomit-frame-pointer>
 139
 140 =item * Some platforms may require extra linker flags in order to get all of
 141 the required symbols exported in the symbol table.  C<Configure.pl
 142 --ccflags=-rdynamic>
 143
 144 =item * Any debugging information embedded in the object is not accessible.  So
 145 file and line number can not be included as part of the backtrace information.
 146
 147 =item * Be warned that signals may cause incorrect backtraces!
 148
 149 =back
 150
 151 =head2 gdb
 152
 153 On systems not equipped with libc, one will need to use an external debugger to
 154 get backtrace information.   This method is actually more capable then the
 155 L<auto-magical> approach as most debuggers will use debugging information if
 156 it's available in the object code (for example, if parrot was built with
 157 C<-g>).
 158
 159 Since the C<Parrot_confess> symbol is I<always> compiled into parrot it can be
 160 used as a break point to obtain a backtrace.  Here is an example of doing this
 161 with gdb and a version of parrot compiled with C<gcc> and the C<-g> flag.
 162
 163     $ gdb parrot
 164     GNU gdb 6.6
 165     Copyright (C) 2006 Free Software Foundation, Inc.
 166     GDB is free software, covered by the GNU General Public License, and you are
 167     welcome to change it and/or distribute copies of it under certain conditions.
 168     Type "show copying" to see the conditions.
 169     There is absolutely no warranty for GDB.  Type "show warranty" for details.
 170     This GDB was configured as "i686-pc-linux-gnu"...
 171     Using host libthread_db library "/lib/libthread_db.so.1".
 172     (gdb) b main
 173     Breakpoint 1 at 0x80488a0: file src/main.c, line 38.
 174     (gdb) r foo.pir
 175     Starting program: /home/moanui/jhoblitt/parrot/parrot foo.pir
 176     Failed to read a valid object file image from memory.
 177     [Thread debugging using libthread_db enabled]
 178     [New Thread -1213900128 (LWP 23148)]
 179     [Switching to Thread -1213900128 (LWP 23148)]
 180
 181     Breakpoint 1, main (argc=-400292727, argv=0x159a0) at src/main.c:38
 182     38      {
 183     (gdb) b Parrot_confess
 184     Breakpoint 2 at 0xb7c542a0: file src/exceptions.c, line 767.
 185     (gdb) c
 186     Continuing.
 187     [New Thread -1214039152 (LWP 23151)]
 188     [New Thread -1222431856 (LWP 23152)]
 189     1..1
 190
 191     Breakpoint 2, Parrot_confess (cond=0xb7eeda65 "s",
 192         file=0xb7eeda58 "src/string.c", line=129) at src/exceptions.c:767
 193     warning: Source file is more recent than executable.
 194     767     {
 195     (gdb) bt full
 196     #0  Parrot_confess (cond=0xb7eeda65 "s", file=0xb7eeda58 "src/string.c",
 197         line=129) at src/exceptions.c:767
 198     No locals.
 199     #1  0xb7c433b1 in Parrot_str_new_COW (interp=0x804e008, s=0x0)
 200         at src/string.c:129
 201             d = (STRING *) 0x81c21b8
 202             __PRETTY_FUNCTION__ = "Parrot_str_new_COW"
 203     #2  0xb7e40db3 in Parrot_String_get_string (interp=0x804e008, pmc=0x81c8578)
 204         at src/pmc/string.c:310
 205     No locals.
 206     #3  0xb7cc7d41 in Parrot_set_s_p (cur_opcode=0x825d470, interp=0x804e008)
 207         at src/ops/set.ops:159
 208     No locals.
 209     #4  0xb7c9da32 in runops_slow_core (interp=0x804e008, pc=0x825d470)
 210         at src/runcore/cores.c:184
 211     No locals.
 212     #5  0xb7c67acf in runops_int (interp=0x804e008, offset=0)
 213         at src/interp/interpreter.c:816
 214             pc = (opcode_t * const) 0x8239730
 215             lo_var_ptr = 134537224
 216             core = (opcode_t *(*)(Parrot_Interp,
 217         opcode_t *)) 0xb7c9d940 <runops_slow_core at src/runcore/cores.c:169>
 218     #6  0xb7c6854e in runops (interp=0x804e008, offs=0) at src/call/ops.c:100
 219             offset = 0
 220             old_runloop_id = 0
 221             our_runloop_level = 1
 222             our_runloop_id = 1
 223     #7  0xb7c687da in runops_args (interp=0x804e008, sub=0x8204d58, obj=0x80912d8,
 224         meth_unused=0x0, sig=0xb7eefca6 "vP",
 225         ap=0xbfec614c "@M \bï¿½bï¿½ï¿½Pï¿½\222K\230ï¿½\004\b@\236\"\b@M \bXM
 226             \b\004ï¿½ï¿½ï¿½ï¿½tï¿½ï¿½\bï¿½\004\b\001") at src/call/ops.c:216
 227             offset = 0
 228             dest = (opcode_t *) 0x8239730
 229             ctx = (Parrot_Context *) 0x822a3b0
 230             new_sig = ""
 231             sig_p = 0xb7eefca7 "P"
 232             old_ctx = (Parrot_Context * const) 0x804e298
 233     #8  0xb7c688fb in Parrot_runops_fromc_args (interp=0x804e008, sub=0x8204d58,
 234         sig=0xb7eefca6 "vP") at src/call/ops.c:293
 235             args = 0xbfec614c "@M \bï¿½bï¿½ï¿½Pï¿½\222K\230ï¿½\004\b@\236\"\b@M
 236                 \bXM \b\004ï¿½ï¿½ï¿½ï¿½tï¿½ï¿½\bï¿½\004\b\001"
 237             ctx = (Parrot_Context *) 0xb7fa1548
 238     #9  0xb7c50c51 in Parrot_runcode (interp=0x804e008, argc=1, argv=0xbfec62e8)
 239         at src/embed.c:783
 240             userargv = (PMC *) 0x8204d40
 241             main_sub = (PMC *) 0x8204d58
 242     #10 0xb7ed74a1 in imcc_run_pbc (interp=0x804e008, obj_file=0, output_file=0x0,
 243         argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:614
 244     No locals.
 245     #11 0xb7ed7d90 in imcc_run (interp=0x804e008, sourcefile=0xbfec6e0a "foo.pir",
 246         argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:815
 247             obj_file = 0
 248             yyscanner = (yyscan_t) 0x822a090
 249             output_file = 0x0
 250     #12 0x080489b7 in main (argc=136704448, argv=0x825f220) at src/main.c:62
 251             sourcefile = 0xbfec6e0a "foo.pir"
 252             interp = (Interp *) 0x804e008
 253             executable_name = (STRING *) 0x821b8e4
 254             executable_name_pmc = (PMC *) 0x8204d70
 255             status = 1267896320
 256     (gdb)