Refactor BranchLists.
[ghc.git] / 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