[PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc

[PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc

[David Malcolm]

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
+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.
+
+@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

Re: [PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc

[Richard Biener]

On Thu, Jan 26, 2017 at 5:52 PM, David Malcolm <dmalcolm@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
>

Re: [PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc

[David Malcolm]

On Fri, 2017-01-27 at 13:20 +0100, Richard Biener wrote:
> On Thu, Jan 26, 2017 at 5:52 PM, David Malcolm <dmalcolm@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

Oops; fixed.

> > +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

(s/RTL/GIMPLE/ here as well)

> > +@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?

I wrote:

+Use the dump modifier @code{-gimple} (e.g. @option{-fdump-tree-all-gimple})
+to make tree dumps more closely follow the format accepted by the GIMPLE
+parser.


> Ok with these changes (and thanks for finding a proper place for some
> docs)

Thanks; committed to trunk as r244977.

[...snip...]