gcc/doc/gccint/testsuites/support-for-testing-rtl-passes.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _rtl-tests:
   7
   8 Support for testing RTL passes
   9 ******************************
  10
  11 As of gcc 7, C functions can be tagged with ``__RTL`` to indicate that the
  12 function body will be RTL, rather than C.  For example:
  13
  14 .. code-block:: c++
  15
  16   double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
  17   {
  18     (function "test"
  19        [...snip; various directives go in here...]
  20     ) ;; function "test"
  21   }
  22
  23 The ``startwith`` argument indicates at which pass to begin.
  24
  25 The parser expects the RTL body to be in the format emitted by this
  26 dumping function:
  27
  28 .. code-block:: c++
  29
  30   DEBUG_FUNCTION void
  31   print_rtx_function (FILE *outfile, function *fn, bool compact);
  32
  33 when "compact" is true.  So you can capture RTL in the correct format
  34 from the debugger using:
  35
  36 .. code-block:: c++
  37
  38   (gdb) print_rtx_function (stderr, cfun, true);
  39
  40 and copy and paste the output into the body of the C function.
  41
  42 Example DejaGnu tests of RTL can be seen in the source tree under
  43 :samp:`gcc/testsuite/gcc.dg/rtl`.
  44
  45 The ``__RTL`` parser is not integrated with the C tokenizer or
  46 preprocessor, and works simply by reading the relevant lines within
  47 the braces.  In particular, the RTL body must be on separate lines from
  48 the enclosing braces, and the preprocessor is not usable within it.