On Thu, Jan 26, 2017 at 5:52 PM, David Malcolm <dmalc...@redhat.com> wrote:
> The "internals" documentation has a "Testsuites" chapter; this patch
> adds some notes to it, describing the __GIMPLE and __RTL extensions
> to the C frontend.
>
> Builds; passed visual inspection of .info, .html, .pdf. and .dvi.
>
> OK for trunk?
>
> gcc/ChangeLog:
> * doc/sourcebuild.texi (Testsuites): Add "GIMPLE Tests" and
> "RTL Tests" to menu.
> (GIMPLE Tests): New node.
> (RTL Tests): New node.
> ---
> gcc/doc/sourcebuild.texi | 89
> ++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 89 insertions(+)
>
> diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
> index 292a3c7..6c047288 100644
> --- a/gcc/doc/sourcebuild.texi
> +++ b/gcc/doc/sourcebuild.texi
> @@ -863,6 +863,8 @@ here; FIXME: document the others.
> * profopt Testing:: Support for testing profile-directed optimizations.
> * compat Testing:: Support for testing binary compatibility.
> * Torture Tests:: Support for torture testing using multiple options.
> +* GIMPLE Tests:: Support for testing GIMPLE passes.
> +* RTL Tests:: Support for testing RTL passes.
> @end menu
>
> @node Test Idioms
> @@ -2931,3 +2933,90 @@ set ADDITIONAL_TORTURE_OPTIONS [list \
> @{ -O2 -ftree-loop-linear @} \
> @{ -O2 -fpeel-loops @} ]
> @end smallexample
> +
> +@node GIMPLE Tests
> +@section Support for testing GIMPLE passes
> +
> +As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
> +that the function body will be RTL, rather than C. The compiler requires the
GIMPLE, not RTL
> +option @option{-fgimple} to enable this functionality. For example:
> +
> +@smallexample
> +/* @{ dg-do compile @} */
> +/* @{ dg-options "-O -fgimple" @} */
> +
> +void __GIMPLE (startwith ("dse2")) foo ()
> +@{
> + int a;
> +
> +bb_2:
> + if (a > 4)
> + goto bb_3;
> + else
> + goto bb_4;
> +
> +bb_3:
> + a_2 = 10;
> + goto bb_5;
> +
> +bb_4:
> + a_3 = 20;
> +
> +bb_5:
> + a_1 = __PHI (bb_3: a_2, bb_4: a_3);
> + a_4 = a_1 + 4;
> +
> + return;
> +@}
> +@end smallexample
> +
> +The @code{startwith} argument indicates at which pass to begin.
> +
> +Example DejaGnu tests of RTL can be seen in the source tree at
> +@file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
> +
> +The @code{__GIMPLE} parser is integrated with the C tokenizer and
> +preprocessor, so it should be possible to use macros to build out
> +test coverage.
Can you add a sentence "A dump modifier -gimple exists to make tree dumps
look more closely to valid GIMPLE input." or something along this line?
Ok with these changes (and thanks for finding a proper place for some docs)
Richard.
> +
> +@node RTL Tests
> +@section Support for testing RTL passes
> +
> +As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
> +function body will be RTL, rather than C. For example:
> +
> +@smallexample
> +double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
> +@{
> + (function "test"
> + [...snip; various directives go in here...]
> + ) ;; function "test"
> +@}
> +@end smallexample
> +
> +The @code{startwith} argument indicates at which pass to begin.
> +
> +The parser expects the RTL body to be in the format emitted by this
> +dumping function:
> +
> +@smallexample
> +DEBUG_FUNCTION void
> +print_rtx_function (FILE *outfile, function *fn, bool compact);
> +@end smallexample
> +
> +when "compact" is true. So you can capture RTL in the correct format
> +from the debugger using:
> +
> +@smallexample
> +(gdb) print_rtx_function (stderr, cfun, true);
> +@end smallexample
> +
> +and copy and paste the output into the body of the C function.
> +
> +Example DejaGnu tests of RTL can be seen in the source tree under
> +@file{gcc/testsuite/gcc.dg/rtl}.
> +
> +The @code{__RTL} parser is not integrated with the C tokenizer or
> +preprocessor, and works simply by reading the relevant lines within
> +the braces. In particular, the RTL body must be on separate lines from
> +the enclosing braces, and the preprocessor is not usable within it.
> --
> 1.8.5.3
>
