Reorganisation of the source tree

[ghc-hetmet.git] / utils / debugNCG / README

diff --git a/utils/debugNCG/README b/utils/debugNCG/README
new file mode 100644 (file)
index 0000000..90eb219
--- /dev/null
+++ b/utils/debugNCG/README
@@ -0,0 +1,46 @@
+
+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
+