From 2712de789246fe33190a41d2a8d7d652027a34b8 Mon Sep 17 00:00:00 2001 From: David Malcolm Date: Tue, 9 Dec 2014 20:46:33 +0000 Subject: [PATCH] PR jit/63854: Document how to run the jit testsuite under valgrind gcc/jit/ChangeLog: PR jit/63854 * docs/internals/index.rst (Running under valgrind): New subsection. (docs/_build/texinfo/libgccjit.texi): Regenerate. From-SVN: r218538 --- gcc/jit/ChangeLog | 7 ++ gcc/jit/docs/_build/texinfo/libgccjit.texi | 77 +++++++++++++++++++--- gcc/jit/docs/internals/index.rst | 45 +++++++++++++ 3 files changed, 119 insertions(+), 10 deletions(-) diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog index 9a95c79fef2..a346b642546 100644 --- a/gcc/jit/ChangeLog +++ b/gcc/jit/ChangeLog @@ -1,3 +1,10 @@ +2014-12-09 David Malcolm + + PR jit/63854 + * docs/internals/index.rst (Running under valgrind): New + subsection. + (docs/_build/texinfo/libgccjit.texi): Regenerate. + 2014-12-09 David Malcolm PR jit/64206 diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi index 6b0a1892ba7..e2afcb50b2c 100644 --- a/gcc/jit/docs/_build/texinfo/libgccjit.texi +++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi @@ -197,6 +197,10 @@ Internals * Environment variables:: * Overview of code structure:: +Running the test suite + +* Running under valgrind:: + @end detailmenu @end menu @@ -6548,8 +6552,61 @@ and once a test has been compiled, you can debug it directly: @noindent +@menu +* Running under valgrind:: + +@end menu + +@node Running under valgrind,,,Running the test suite +@anchor{internals/index running-under-valgrind}@anchor{c9} +@subsection Running under valgrind + + +The jit testsuite detects if RUN_UNDER_VALGRIND is present in the +environment (with any value). If it is present, it runs the test client +code under valgrind@footnote{http://valgrind.org}, +specifcally, the default +memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html} +tool with +--leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}. + +It automatically parses the output from valgrind, injecting XFAIL results if +any issues are found, or PASS results if the output is clean. The output +is saved to @code{TESTNAME.exe.valgrind.txt}. + +For example, the following invocation verbosely runs the testcase +@code{test-sum-of-squares.c} under valgrind, showing an issue: + +@example +$ RUN_UNDER_VALGRIND= \ + make check-jit \ + RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c" + +(...verbose log contains detailed valgrind errors, if any...) + + === jit Summary === + +# of expected passes 28 +# of expected failures 2 + +$ less testsuite/jit/jit.sum +(...other results...) +XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks +XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1 +(...other results...) + +$ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt +(...shows full valgrind report for this test case...) +@end example + +@noindent + +When running under valgrind, it's best to have configured gcc with +@code{--enable-valgrind-annotations}, which automatically suppresses +various known false positives. + @node Environment variables,Overview of code structure,Running the test suite,Internals -@anchor{internals/index environment-variables}@anchor{c9} +@anchor{internals/index environment-variables}@anchor{ca} @section Environment variables @@ -6557,7 +6614,7 @@ When running client code against a locally-built libgccjit, three environment variables need to be set up: @geindex environment variable; LD_LIBRARY_PATH -@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{ca} +@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{cb} @deffn {Environment Variable} LD_LIBRARY_PATH @quotation @@ -6579,7 +6636,7 @@ libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), @end deffn @geindex environment variable; PATH -@anchor{internals/index envvar-PATH}@anchor{cb} +@anchor{internals/index envvar-PATH}@anchor{cc} @deffn {Environment Variable} PATH The library uses a driver executable for converting from .s assembler @@ -6598,7 +6655,7 @@ of development. @end deffn @geindex environment variable; LIBRARY_PATH -@anchor{internals/index envvar-LIBRARY_PATH}@anchor{cc} +@anchor{internals/index envvar-LIBRARY_PATH}@anchor{cd} @deffn {Environment Variable} LIBRARY_PATH The driver executable invokes the linker, and the latter needs to locate @@ -6634,7 +6691,7 @@ hello world @noindent @node Overview of code structure,,Environment variables,Internals -@anchor{internals/index overview-of-code-structure}@anchor{cd} +@anchor{internals/index overview-of-code-structure}@anchor{ce} @section Overview of code structure @@ -6733,11 +6790,11 @@ Client Code . Generated . libgccjit.so ──────────────────────────> . . . . │ start of recording::context::compile () . . │ . . - . . │ ACQUIRE MUTEX . - . . │ . . . . │ start of playback::context::compile () . . │ (create tempdir) . . . │ . . + . . │ ACQUIRE MUTEX . + . . │ . . . . V───────────────────────> toplev::main (for now) . . . . │ . . . . (various code) @@ -6791,6 +6848,8 @@ Client Code . Generated . libgccjit.so . . │ . . . . │ Load DSO (dlopen "fake.so") . . │ . . + . . │ RELEASE MUTEX . + . . │ . . . . │ end of playback::context::compile () . . │ . . . . │ playback::context dtor @@ -6800,8 +6859,6 @@ Client Code . Generated . libgccjit.so . . │ filesystem at this point) . . <── . . . . │ . . - . . │ RELEASE MUTEX . - . . │ . . . . │ end of recording::context::compile () <─────────────────────────── . . │ . . . . @@ -6905,7 +6962,7 @@ the APIs are not yet set in stone, and they shouldn't be used in production yet. @node Indices and tables,Index,Internals,Top -@anchor{index indices-and-tables}@anchor{ce} +@anchor{index indices-and-tables}@anchor{cf} @unnumbered Indices and tables diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst index 80626e4a10b..1d46818d397 100644 --- a/gcc/jit/docs/internals/index.rst +++ b/gcc/jit/docs/internals/index.rst @@ -118,6 +118,51 @@ and once a test has been compiled, you can debug it directly: gdb --args \ testsuite/jit/test-factorial.exe +Running under valgrind +********************** + +The jit testsuite detects if RUN_UNDER_VALGRIND is present in the +environment (with any value). If it is present, it runs the test client +code under `valgrind `_, +specifcally, the default +`memcheck `_ +tool with +`--leak-check=full +`_. + +It automatically parses the output from valgrind, injecting XFAIL results if +any issues are found, or PASS results if the output is clean. The output +is saved to ``TESTNAME.exe.valgrind.txt``. + +For example, the following invocation verbosely runs the testcase +``test-sum-of-squares.c`` under valgrind, showing an issue: + +.. code-block:: console + + $ RUN_UNDER_VALGRIND= \ + make check-jit \ + RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c" + + (...verbose log contains detailed valgrind errors, if any...) + + === jit Summary === + + # of expected passes 28 + # of expected failures 2 + + $ less testsuite/jit/jit.sum + (...other results...) + XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks + XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1 + (...other results...) + + $ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt + (...shows full valgrind report for this test case...) + +When running under valgrind, it's best to have configured gcc with +:option:`--enable-valgrind-annotations`, which automatically suppresses +various known false positives. + Environment variables --------------------- When running client code against a locally-built libgccjit, three -- 2.30.2