src/mem/ruby/README.debugging

   1 # ------ Debugging the Ruby Tester ------
   2
   3 You can compile Ruby with debugging turned on.
   4
   5 cd ruby
   6 [vim or emacs] Makefile
   7
   8 Change OPT_FLAGS to "-g -O0" (the first OPT_FLAGS line). Make
   9 sure all the other OPT_FLAGS lines are commented out.
  10
  11 Change DEBUG_FLAGS to "-DRUBY_DEBUG=true". (Just uncomment the
  12 first DEBUG_FLAGS line, and comment out the second DEBUG_FLAGS
  13 line.)
  14
  15 You can choose which component or components to debug, and the
  16 level of verbosity. For example,
  17
  18 "x86-linux/generated/MOSI_SMP_bcast/bin/tester.exec -l 100000 -v med -c n"
  19
  20 gives you debugging information about the network component at
  21 the medium verbosity level. -v selects the verbosity, which may
  22 be low, med, high, or none. -c selects the component or
  23 components.
  24
  25 "x86-linux/generated/MOSI_SMP_bcast/bin/tester.exec -l 100000 -v med -c nSt"
  26
  27 debugs the network, the sequencer, and the tester.
  28
  29 For a list of the components you can debug, just run the tester with
  30 no arguments, and it will display a list of valid components. The
  31 components are defined in ruby/common/Debug.def.
  32
  33 The protocol debug trace is especially useful for debugging cache coherence protocols.  This must be enabled at compile-time by ensuring that PROTOCOL_DEBUG_TRACE is set to true for rubyconfig.defaults (if running in Simics) or tester.defaults.  You must specify the time to start tracing.  The following starts the protocol trace immediately (at time 1)
  34
  35 "x86-linux/generated/MOSI_SMP_bcast/bin/tester.exec -l 100000 -s 1"
  36
  37 Also, if something seems to be wrong and you're not sure where to
  38 start looking, it may help to run the tester for a longer time,
  39 e.g.
  40
  41 "x86-linux/generated/MOSI_SMP_bcast/bin/tester.exec -l 500000"
  42
  43 This may help because some problems eventually show up as
  44 deadlock, but the tester has to run for a long time before a
  45 deadlock is detected.
  46
  47 Once your simulator has succeeded on the tester for a certain
  48 number of cycles, say 1000000, you may want to set the
  49 RANDOMIZATION variable in ruby/config/tester.defaults to "true"
  50 for more thorough testing.  However, RANDOMIZATION may not work in
  51 all situations because it overrides some of the ordering in the
  52 network and may break your simulator in ways you don't like.  For
  53 example, messages are added to MessageBuffers with random
  54 latency.
  55
  56 By default the tester driver is a generator that issues random store
  57 and load requests. This driver does a good job of stressing the
  58 cache coherency protocol by issuing racy store requests from multiple
  59 processors to a cache line then checks the stores with a single load.
  60
  61 Other tester drivers are available.  By setting the g_SYNTHETIC_DRIVER
  62 to true in ruby/config/tester.defaults, you enable a tester that generates
  63 racy lock requests for a number of locks indicated by g_synthetic_locks.
  64
  65 Another tester driver is a series of non-racy deterministic testers.  By
  66 setting the g_DETERMINISTIC_DRIVER in ruby/config/tester.defaults to true,
  67 you enable the deterministic tester.  The deterministic tester can do
  68 different types of deterministic tests as specified by g_SpecifiedGenerator
  69 string.  The deterministic tester works best when RANDOMIZATION is set to
  70 false.  To easily track the queues being used with the deterministic tester,
  71 use the following debug flags "-v low -c nq".
  72
  73 # ------ Debugging Ruby in Simics ------
  74
  75 When you're running Simics, the debugging components and
  76 verbosity levels are the same. However, the way you communicate
  77 with Ruby changes.
  78
  79 See the README.quickstart for information on compiling the Ruby
  80 module and loading it into Simics. Once you've got Simics
  81 running, with the Ruby module loaded, you can set up Ruby
  82 debugging.
  83
  84 To set the debugging verbosity level, run:
  85
  86 simics> ruby0.debug-verb med
  87
  88 To set the debugging components, run: (see common/Debug.def for complete list
  89                                        of component shortcuts)
  90
  91 simics> ruby0.debug-filter n
  92
  93 (NOTE: sometimes simics will interpret a single letter as a
  94 command; e.g. expanding "p" into "print". If simics gives you an
  95 error when setting the debug filter, try setting it like so:
  96 simics> ruby0.debug-filter "n")
  97
  98 This gives the same kind of debugging information as running the
  99 tester with "-v med -c n".
 100
 101 You can also send the debugging output to a file (may be a good
 102 idea, since there's a lot of it). To do this, run:
 103
 104 simics> ruby0.debug-output-file <filename>