utils/debugNCG/README

   1
   2 This program is to assist in debugging GHC's native code generator.
   3
   4 Finding out which particular code block the native code block has
   5 mis-compiled is like finding a needle in a haystack.  This program
   6 solves that problem.  Given an assembly file created by the NCG (call
   7 it Foo.s-nat) and one created by gcc (Foo.s-gcc), then
   8
   9    diff_gcc_nat Foo.s
  10
  11 will pair up corresponding code blocks, wrap each one in an #if and
  12 spew the entire result out to stdout, along with a load of #defines at
  13 the top, which you can use to switch between the gcc and ncg versions
  14 of each code block.  Pipe this into a .S file (I use the name
  15 synth.S).  Then you can used the #defines to do a binary search to
  16 quickly arrive at the code block(s) which have been mis-compiled.
  17
  18 Note that the .S suffix tells ghc that this assembly file needs to be
  19 cpp'd; so you should be sure to use .S and not .s.
  20
  21 The pattern matching can cope with the fact that the code blocks are
  22 in different orders in the two files.  The result synth.S is ordered
  23 by in the order of the -nat input; the -gcc input is searched for the
  24 corresponding stuff.  The search relies on spotting artefacts like
  25 section changes, so is fragile and susceptible to minor changes in the
  26 gcc's assembly output.  If that happens, it's well worth the effort
  27 fixing this program, rather than trying to infer what's wrong with the
  28 NCG directly from the -nat input.
  29
  30 This is only known to work on x86 linux, sparc-solaris (and possibly
  31 cygwin).  No idea if the same matching heuristics will work on other
  32 archs -- if not, we need to have multiple versions of this program, on
  33 a per-arch basis.
  34
  35 One other IMPORTANT thing: you *must* enable stg-split-markers in the
  36 native code generator output, otherwise this won't work at all --
  37 since it won't be able to find out where the code blocks start and
  38 end.  Enable these markers by compiling ghc (or at least
  39 ghc/compiler/nativeGen/AsmCodeGen.lhs, function nativeCodeGen) with
  40 -DDEBUG_NCG enabled.
  41
  42 Matching is simple but inefficient; diff-ing a large module could take
  43 a minute or two.
  44
  45 JRS, 29 June 2000
  46