|
@@ -31,12 +29,14 @@
- Written by Chris Lattner and - Misha Brukman + |
- 
+ 
|
-
-
- If cc1 crashed, you found a problem with the front-end. +
- If cc1 or cc1plus crashed, you found a + problem with the front-end. Jump ahead to the section on front-end bugs.
- If gccas crashed, you found a bug in one
@@ -145,9 +147,9 @@ along with a brief description of the error it caused.
compilation, compile your test-case to a .s file with the
-save-temps option to llvm-gcc. Then run:
-
- gccas -debug-pass=Arguments < /dev/null -o - > /dev/null -
++gccas -debug-pass=Arguments < /dev/null -o - > /dev/null
+... which will print a list of arguments, indicating the list of passes that gccas runs. Once you have the input file and the list of @@ -168,10 +170,11 @@ compilation, gather all of the .o bytecode files and libraries that are being linked together (the "llvm-gcc -v" output should include the full list of objects linked). Then run:
-- llvm-as < /dev/null > null.bc - gccld -debug-pass=Arguments null.bc -
+
+llvm-as < /dev/null > null.bc
+
+gccld -debug-pass=Arguments null.bc +... which will print a list of arguments, indicating the list of passes that gccld runs. Once you have the input files and the list of @@ -192,19 +195,21 @@ files and a list of passes which crash when run on the specified input. In order to reduce the list of passes (which is probably large) and the input to something tractable, use the bugpoint tool as follows:
-- bugpoint <input files> <list of passes> -
+
+bugpoint <input files> <list of passes>
+bugpoint will print a bunch of output as it reduces the test-case, but it should eventually print something like this:
-- ... - Emitted bytecode to 'bugpoint-reduced-simplified.bc' - - *** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm -
+++...
+
+Emitted bytecode to 'bugpoint-reduced-simplified.bc'
+
+*** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm
+Once you complete this, please send the LLVM bytecode file and the command line to reproduce the problem to the llvmbugs mailing list.
@@ -225,13 +230,21 @@ from producing invalid LLVM code (i.e., code not in SSA form, using values before defining them, etc.) which the verifier will check for after a pass finishes its run. -To debug a miscompilation, you should choose which program you wish to run -the output through, e.g. C backend, the JIT, or LLC, and a selection of passes, -one of which may be causing the error, and run, for example:
+If it looks like the LLVM compiler is miscompiling a program, the very first +thing to check is to make sure it is not using undefined behavior. In +particular, check to see if the program valgrinds clean, passes purify, or some +other memory checker tool. Many of the "LLVM bugs" that we have chased down +ended up being bugs in the program being compiled, not LLVM.
-- bugpoint -run-cbe [... optimization passes ...] file-to-test.bc -
+Once you determine that the program itself is not buggy, you should choose +which code generator you wish to compile the program with (e.g. C backend, the +JIT, or LLC) and optionally a series of LLVM passes to run. For example:
+ +++bugpoint -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]
+bugpoint will try to narrow down your list of passes to the one pass that causes an error, and simplify the bytecode file as much as it can to assist @@ -258,15 +271,35 @@ Backend, and then link in the shared object it generates.
To debug the JIT:
+- bugpoint -run-jit -output=[correct output file] [bytecodefile] +bugpoint -run-jit -output=[correct output file] [bytecode file] \ + --tool-args -- [arguments to pass to lli] \ + --args -- [program arguments]
+Similarly, to debug the LLC, one would run:
++ +- bugpoint -run-llc -output=[correct output file] [bytecodefile] +bugpoint -run-llc -output=[correct output file] [bytecode file] \ + --tool-args -- [arguments to pass to llc] \ + --args -- [program arguments]
+Special note: if you are debugging MultiSource or SPEC tests that +already exist in the llvm/test hierarchy, there is an easier way to +debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which +will pass the program options specified in the Makefiles:
+ +++cd llvm/test/../../program
+
+make bugpoint-jit +At the end of a successful bugpoint run, you will be presented with two bytecode files: a safe file which can be compiled with the C @@ -278,41 +311,50 @@ the following:
-
-
- Regenerate the shared object from the safe bytecode file:
- -- llvm-dis -c safe.bc -o safe.c
- gcc -shared safe.c -o safe.so -
-
- - If debugging LLC, compile test bytecode native and link with the shared object:
- -- llc test.bc -o test.s -f
- gcc test.s safe.so -o test.llc
- ./test.llc [program options] -
-
-
If debugging the JIT, load the shared object and supply the test -bytecode:
- -- lli -load=safe.so test.bc [program options] -
+ - Regenerate the shared object from the safe bytecode file:
Regenerate the shared object from the safe bytecode file:
+ +++llc -march=c safe.bc -o safe.c
+
+gcc -shared safe.c -o safe.so +
+
+If debugging LLC, compile test bytecode native and link with the shared + object:
+ +++llc test.bc -o test.s -f
+
+gcc test.s safe.so -o test.llc
+./test.llc [program options] +
+
+If debugging the JIT, load the shared object and supply the test + bytecode:
+ ++lli -load=safe.so test.bc [program options]
+
