This program is to assist in debugging GHC's native code generator.

Finding out which particular code block the native code block has
mis-compiled is like finding a needle in a haystack.  This program
solves that problem.  Given an assembly file created by the NCG (call
it Foo.s-nat) and one created by gcc (Foo.s-gcc), then

   diff_gcc_nat Foo.s

will pair up corresponding code blocks, wrap each one in an #if and
spew the entire result out to stdout, along with a load of #defines at
the top, which you can use to switch between the gcc and ncg versions
of each code block.  Pipe this into a .S file (I use the name
synth.S).  Then you can used the #defines to do a binary search to
quickly arrive at the code block(s) which have been mis-compiled.

Note that the .S suffix tells ghc that this assembly file needs to be
cpp'd; so you should be sure to use .S and not .s.

The pattern matching can cope with the fact that the code blocks are
in different orders in the two files.  The result synth.S is ordered
by in the order of the -nat input; the -gcc input is searched for the
corresponding stuff.  The search relies on spotting artefacts like
section changes, so is fragile and susceptible to minor changes in the
gcc's assembly output.  If that happens, it's well worth the effort
fixing this program, rather than trying to infer what's wrong with the
NCG directly from the -nat input.

This is only known to work on x86 linux, sparc-solaris (and possibly
cygwin).  No idea if the same matching heuristics will work on other
archs -- if not, we need to have multiple versions of this program, on
a per-arch basis.

One other IMPORTANT thing: you *must* enable stg-split-markers in the
native code generator output, otherwise this won't work at all --
since it won't be able to find out where the code blocks start and
end.  Enable these markers by compiling ghc (or at least
ghc/compiler/nativeGen/AsmCodeGen.lhs, function nativeCodeGen) with
-DDEBUG_NCG enabled.

Matching is simple but inefficient; diff-ing a large module could take
a minute or two.

JRS, 29 June 2000