This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc
- From: David Malcolm <dmalcolm at redhat dot com>
- To: gcc-patches at gcc dot gnu dot org
- Cc: David Malcolm <dmalcolm at redhat dot com>
- Date: Thu, 26 Jan 2017 11:52:42 -0500
- Subject: [PATCH] docs: Add __GIMPLE and __RTL to the "Internals" doc
- Authentication-results: sourceware.org; auth=none
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