ang.in' File ........................................... Each language subdirectory contains a `config-lang.in' file. In addition the main directory contains `c-config-lang.in', which contains limited information for the C language. This file is a shell script that may define some variables describing the language: `language' This definition must be present, and gives the name of the language for some purposes such as arguments to `--enable-languages'. `lang_requires' If defined, this variable lists (space-separated) language front ends other than C that this front end requires to be enabled (with the names given being their `language' settings). For example, the Java front end depends on the C++ front end, so sets `lang_requires=c++'. `subdir_requires' If defined, this variable lists (space-separated) front end directories other than C that this front end requires to be present. For example, the Objective-C++ front end uses source files from the C++ and Objective-C front ends, so sets `subdir_requires="cp objc"'. `target_libs' If defined, this variable lists (space-separated) targets in the top level `Makefile' to build the runtime libraries for this language, such as `target-libobjc'. `lang_dirs' If defined, this variable lists (space-separated) top level directories (parallel to `gcc'), apart from the runtime libraries, that should not be configured if this front end is not built. `build_by_default' If defined to `no', this language front end is not built unless enabled in a `--enable-languages' argument. Otherwise, front ends are built by default, subject to any special logic in `configure.ac' (as is present to disable the Ada front end if the Ada compiler is not already installed). `boot_language' If defined to `yes', this front end is built in stage 1 of the bootstrap. This is only relevant to front ends written in their own languages. `compilers' If defined, a space-separated list of compiler executables that will be run by the driver. The names here will each end with `\$(exeext)'. `outputs' If defined, a space-separated list of files that should be generated by `configure' substituting values in them. This mechanism can be used to create a file `LANGUAGE/Makefile' from `LANGUAGE/Makefile.in', but this is deprecated, building everything from the single `gcc/Makefile' is preferred. `gtfiles' If defined, a space-separated list of files that should be scanned by gengtype.c to generate the garbage collection tables and routines for this language. This excludes the files that are common to all front ends. *Note Type Information::.  File: gccint.info, Node: Back End, Prev: Front End, Up: gcc Directory 6.3.9 Anatomy of a Target Back End ---------------------------------- A back end for a target architecture in GCC has the following parts: * A directory `MACHINE' under `gcc/config', containing a machine description `MACHINE.md' file (*note Machine Descriptions: Machine Desc.), header files `MACHINE.h' and `MACHINE-protos.h' and a source file `MACHINE.c' (*note Target Description Macros and Functions: Target Macros.), possibly a target Makefile fragment `t-MACHINE' (*note The Target Makefile Fragment: Target Fragment.), and maybe some other files. The names of these files may be changed from the defaults given by explicit specifications in `config.gcc'. * If necessary, a file `MACHINE-modes.def' in the `MACHINE' directory, containing additional machine modes to represent condition codes. *Note Condition Code::, for further details. * An optional `MACHINE.opt' file in the `MACHINE' directory, containing a list of target-specific options. You can also add other option files using the `extra_options' variable in `config.gcc'. *Note Options::. * Entries in `config.gcc' (*note The `config.gcc' File: System Config.) for the systems with this target architecture. * Documentation in `gcc/doc/invoke.texi' for any command-line options supported by this target (*note Run-time Target Specification: Run-time Target.). This means both entries in the summary table of options and details of the individual options. * Documentation in `gcc/doc/extend.texi' for any target-specific attributes supported (*note Defining target-specific uses of `__attribute__': Target Attributes.), including where the same attribute is already supported on some targets, which are enumerated in the manual. * Documentation in `gcc/doc/extend.texi' for any target-specific pragmas supported. * Documentation in `gcc/doc/extend.texi' of any target-specific built-in functions supported. * Documentation in `gcc/doc/extend.texi' of any target-specific format checking styles supported. * Documentation in `gcc/doc/md.texi' of any target-specific constraint letters (*note Constraints for Particular Machines: Machine Constraints.). * A note in `gcc/doc/contrib.texi' under the person or people who contributed the target support. * Entries in `gcc/doc/install.texi' for all target triplets supported with this target architecture, giving details of any special notes about installation for this target, or saying that there are no special notes if there are none. * Possibly other support outside the `gcc' directory for runtime libraries. FIXME: reference docs for this. The libstdc++ porting manual needs to be installed as info for this to work, or to be a chapter of this manual. If the back end is added to the official GCC source repository, the following are also necessary: * An entry for the target architecture in `readings.html' on the GCC web site, with any relevant links. * Details of the properties of the back end and target architecture in `backends.html' on the GCC web site. * A news item about the contribution of support for that target architecture, in `index.html' on the GCC web site. * Normally, one or more maintainers of that target listed in `MAINTAINERS'. Some existing architectures may be unmaintained, but it would be unusual to add support for a target that does not have a maintainer when support is added.  File: gccint.info, Node: Testsuites, Prev: gcc Directory, Up: Source Tree 6.4 Testsuites ============== GCC contains several testsuites to help maintain compiler quality. Most of the runtime libraries and language front ends in GCC have testsuites. Currently only the C language testsuites are documented here; FIXME: document the others. * Menu: * Test Idioms:: Idioms used in testsuite code. * Test Directives:: Directives used within DejaGnu tests. * Ada Tests:: The Ada language testsuites. * C Tests:: The C language testsuites. * libgcj Tests:: The Java library testsuites. * gcov Testing:: Support for testing gcov. * profopt Testing:: Support for testing profile-directed optimizations. * compat Testing:: Support for testing binary compatibility. * Torture Tests:: Support for torture testing using multiple options.  File: gccint.info, Node: Test Idioms, Next: Test Directives, Up: Testsuites 6.4.1 Idioms Used in Testsuite Code ----------------------------------- In general, C testcases have a trailing `-N.c', starting with `-1.c', in case other testcases with similar names are added later. If the test is a test of some well-defined feature, it should have a name referring to that feature such as `FEATURE-1.c'. If it does not test a well-defined feature but just happens to exercise a bug somewhere in the compiler, and a bug report has been filed for this bug in the GCC bug database, `prBUG-NUMBER-1.c' is the appropriate form of name. Otherwise (for miscellaneous bugs not filed in the GCC bug database), and previously more generally, test cases are named after the date on which they were added. This allows people to tell at a glance whether a test failure is because of a recently found bug that has not yet been fixed, or whether it may be a regression, but does not give any other information about the bug or where discussion of it may be found. Some other language testsuites follow similar conventions. In the `gcc.dg' testsuite, it is often necessary to test that an error is indeed a hard error and not just a warning--for example, where it is a constraint violation in the C standard, which must become an error with `-pedantic-errors'. The following idiom, where the first line shown is line LINE of the file and the line that generates the error, is used for this: /* { dg-bogus "warning" "warning in place of error" } */ /* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */ It may be necessary to check that an expression is an integer constant expression and has a certain value. To check that `E' has value `V', an idiom similar to the following is used: char x[((E) == (V) ? 1 : -1)]; In `gcc.dg' tests, `__typeof__' is sometimes used to make assertions about the types of expressions. See, for example, `gcc.dg/c99-condexpr-1.c'. The more subtle uses depend on the exact rules for the types of conditional expressions in the C standard; see, for example, `gcc.dg/c99-intconst-1.c'. It is useful to be able to test that optimizations are being made properly. This cannot be done in all cases, but it can be done where the optimization will lead to code being optimized away (for example, where flow analysis or alias analysis should show that certain code cannot be called) or to functions not being called because they have been expanded as built-in functions. Such tests go in `gcc.c-torture/execute'. Where code should be optimized away, a call to a nonexistent function such as `link_failure ()' may be inserted; a definition #ifndef __OPTIMIZE__ void link_failure (void) { abort (); } #endif will also be needed so that linking still succeeds when the test is run without optimization. When all calls to a built-in function should have been optimized and no calls to the non-built-in version of the function should remain, that function may be defined as `static' to call `abort ()' (although redeclaring a function as static may not work on all targets). All testcases must be portable. Target-specific testcases must have appropriate code to avoid causing failures on unsupported systems; unfortunately, the mechanisms for this differ by directory. FIXME: discuss non-C testsuites here.  File: gccint.info, Node: Test Directives, Next: Ada Tests, Prev: Test Idioms, Up: Testsuites 6.4.2 Directives used within DejaGnu tests ------------------------------------------ Test directives appear within comments in a test source file and begin with `dg-'. Some of these are defined within DejaGnu and others are local to the GCC testsuite. The order in which test directives appear in a test can be important: directives local to GCC sometimes override information used by the DejaGnu directives, which know nothing about the GCC directives, so the DejaGnu directives must precede GCC directives. Several test directives include selectors which are usually preceded by the keyword `target' or `xfail'. A selector is: one or more target triplets, possibly including wildcard characters; a single effective-target keyword; or a logical expression. Depending on the context, the selector specifies whether a test is skipped and reported as unsupported or is expected to fail. Use `*-*-*' to match any target. Effective-target keywords are defined in `target-supports.exp' in the GCC testsuite. A selector expression appears within curly braces and uses a single logical operator: one of `!', `&&', or `||'. An operand is another selector expression, an effective-target keyword, a single target triplet, or a list of target triplets within quotes or curly braces. For example: { target { ! "hppa*-*-* ia64*-*-*" } } { target { powerpc*-*-* && lp64 } } { xfail { lp64 || vect_no_align } } `{ dg-do DO-WHAT-KEYWORD [{ target/xfail SELECTOR }] }' DO-WHAT-KEYWORD specifies how the test is compiled and whether it is executed. It is one of: `preprocess' Compile with `-E' to run only the preprocessor. `compile' Compile with `-S' to produce an assembly code file. `assemble' Compile with `-c' to produce a relocatable object file. `link' Compile, assemble, and link to produce an executable file. `run' Produce and run an executable file, which is expected to return an exit code of 0. The default is `compile'. That can be overridden for a set of tests by redefining `dg-do-what-default' within the `.exp' file for those tests. If the directive includes the optional `{ target SELECTOR }' then the test is skipped unless the target system is included in the list of target triplets or matches the effective-target keyword. If `do-what-keyword' is `run' and the directive includes the optional `{ xfail SELECTOR }' and the selector is met then the test is expected to fail. The `xfail' clause is ignored for other values of `do-what-keyword'; those tests can use directive `dg-xfail-if'. `{ dg-options OPTIONS [{ target SELECTOR }] }' This DejaGnu directive provides a list of compiler options, to be used if the target system matches SELECTOR, that replace the default options used for this set of tests. `{ dg-add-options FEATURE ... }' Add any compiler options that are needed to access certain features. This directive does nothing on targets that enable the features by default, or that don't provide them at all. It must come after all `dg-options' directives. The supported values of FEATURE are: `c99_runtime' The target's C99 runtime (both headers and libraries). `mips16_attribute' `mips16' function attributes. Only MIPS targets support this feature, and only then in certain modes. `{ dg-timeout N [{target SELECTOR }] }' Set the time limit for the compilation and for the execution of the test to the specified number of seconds. `{ dg-timeout-factor X [{ target SELECTOR }] }' Multiply the normal time limit for compilation and execution of the test by the specified floating-point factor. The normal timeout limit, in seconds, is found by searching the following in order: * the value defined by an earlier `dg-timeout' directive in the test * variable TOOL_TIMEOUT defined by the set of tests * GCC,TIMEOUT set in the target board * 300 `{ dg-skip-if COMMENT { SELECTOR } { INCLUDE-OPTS } { EXCLUDE-OPTS } }' Skip the test if the test system is included in SELECTOR and if each of the options in INCLUDE-OPTS is in the set of options with which the test would be compiled and if none of the options in EXCLUDE-OPTS is in the set of options with which the test would be compiled. Use `"*"' for an empty INCLUDE-OPTS list and `""' for an empty EXCLUDE-OPTS list. `{ dg-xfail-if COMMENT { SELECTOR } { INCLUDE-OPTS } { EXCLUDE-OPTS } }' Expect the test to fail if the conditions (which are the same as for `dg-skip-if') are met. `{ dg-require-SUPPORT args }' Skip the test if the target does not provide the required support; see `gcc-dg.exp' in the GCC testsuite for the actual directives. These directives must appear after any `dg-do' directive in the test and before any `dg-additional-sources' directive. They require at least one argument, which can be an empty string if the specific procedure does not examine the argument. `{ dg-require-effective-target KEYWORD }' Skip the test if the test target, including current multilib flags, is not covered by the effective-target keyword. This directive must appear after any `dg-do' directive in the test and before any `dg-additional-sources' directive. `{ dg-shouldfail COMMENT { SELECTOR } { INCLUDE-OPTS } { EXCLUDE-OPTS } }' Expect the test executable to return a nonzero exit status if the conditions (which are the same as for `dg-skip-if') are met. `{ dg-error REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] }]] }' This DejaGnu directive appears on a source line that is expected to get an error message, or else specifies the source line associated with the message. If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the `FAIL' message. The check does not look for the string `"error"' unless it is part of REGEXP. `{ dg-warning REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] }]] }' This DejaGnu directive appears on a source line that is expected to get a warning message, or else specifies the source line associated with the message. If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the `FAIL' message. The check does not look for the string `"warning"' unless it is part of REGEXP. `{ dg-message REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] }]] }' The line is expected to get a message other than an error or warning. If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the `FAIL' message. `{ dg-bogus REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] }]] }' This DejaGnu directive appears on a source line that should not get a message matching REGEXP, or else specifies the source line associated with the bogus message. It is usually used with `xfail' to indicate that the message is a known problem for a particular set of targets. `{ dg-excess-errors COMMENT [{ target/xfail SELECTOR }] }' This DejaGnu directive indicates that the test is expected to fail due to compiler messages that are not handled by `dg-error', `dg-warning' or `dg-bogus'. For this directive `xfail' has the same effect as `target'. `{ dg-output REGEXP [{ target/xfail SELECTOR }] }' This DejaGnu directive compares REGEXP to the combined output that the test executable writes to `stdout' and `stderr'. `{ dg-prune-output REGEXP }' Prune messages matching REGEXP from test output. `{ dg-additional-files "FILELIST" }' Specify additional files, other than source files, that must be copied to the system where the compiler runs. `{ dg-additional-sources "FILELIST" }' Specify additional source files to appear in the compile line following the main test file. `{ dg-final { LOCAL-DIRECTIVE } }' This DejaGnu directive is placed within a comment anywhere in the source file and is processed after the test has been compiled and run. Multiple `dg-final' commands are processed in the order in which they appear in the source file. The GCC testsuite defines the following directives to be used within `dg-final'. `cleanup-coverage-files' Removes coverage data files generated for this test. `cleanup-repo-files' Removes files generated for this test for `-frepo'. `cleanup-rtl-dump SUFFIX' Removes RTL dump files generated for this test. `cleanup-tree-dump SUFFIX' Removes tree dump files matching SUFFIX which were generated for this test. `cleanup-saved-temps' Removes files for the current test which were kept for `--save-temps'. `scan-file FILENAME REGEXP [{ target/xfail SELECTOR }]' Passes if REGEXP matches text in FILENAME. `scan-file-not FILENAME REGEXP [{ target/xfail SELECTOR }]' Passes if REGEXP does not match text in FILENAME. `scan-hidden SYMBOL [{ target/xfail SELECTOR }]' Passes if SYMBOL is defined as a hidden symbol in the test's assembly output. `scan-not-hidden SYMBOL [{ target/xfail SELECTOR }]' Passes if SYMBOL is not defined as a hidden symbol in the test's assembly output. `scan-assembler-times REGEX NUM [{ target/xfail SELECTOR }]' Passes if REGEX is matched exactly NUM times in the test's assembler output. `scan-assembler REGEX [{ target/xfail SELECTOR }]' Passes if REGEX matches text in the test's assembler output. `scan-assembler-not REGEX [{ target/xfail SELECTOR }]' Passes if REGEX does not match text in the test's assembler output. `scan-assembler-dem REGEX [{ target/xfail SELECTOR }]' Passes if REGEX matches text in the test's demangled assembler output. `scan-assembler-dem-not REGEX [{ target/xfail SELECTOR }]' Passes if REGEX does not match text in the test's demangled assembler output. `scan-tree-dump-times REGEX NUM SUFFIX [{ target/xfail SELECTOR }]' Passes if REGEX is found exactly NUM times in the dump file with suffix SUFFIX. `scan-tree-dump REGEX SUFFIX [{ target/xfail SELECTOR }]' Passes if REGEX matches text in the dump file with suffix SUFFIX. `scan-tree-dump-not REGEX SUFFIX [{ target/xfail SELECTOR }]' Passes if REGEX does not match text in the dump file with suffix SUFFIX. `scan-tree-dump-dem REGEX SUFFIX [{ target/xfail SELECTOR }]' Passes if REGEX matches demangled text in the dump file with suffix SUFFIX. `scan-tree-dump-dem-not REGEX SUFFIX [{ target/xfail SELECTOR }]' Passes if REGEX does not match demangled text in the dump file with suffix SUFFIX. `output-exists [{ target/xfail SELECTOR }]' Passes if compiler output file exists. `output-exists-not [{ target/xfail SELECTOR }]' Passes if compiler output file does not exist. `run-gcov SOURCEFILE' Check line counts in `gcov' tests. `run-gcov [branches] [calls] { OPTS SOURCEFILE }' Check branch and/or call counts, in addition to line counts, in `gcov' tests.  File: gccint.info, Node: Ada Tests, Next: C Tests, Prev: Test Directives, Up: Testsuites 6.4.3 Ada Language Testsuites ----------------------------- The Ada testsuite includes executable tests from the ACATS 2.5 testsuite, publicly available at `http://www.adaic.org/compilers/acats/2.5' These tests are integrated in the GCC testsuite in the `gcc/testsuite/ada/acats' directory, and enabled automatically when running `make check', assuming the Ada language has been enabled when configuring GCC. You can also run the Ada testsuite independently, using `make check-ada', or run a subset of the tests by specifying which chapter to run, e.g.: $ make check-ada CHAPTERS="c3 c9" The tests are organized by directory, each directory corresponding to a chapter of the Ada Reference Manual. So for example, c9 corresponds to chapter 9, which deals with tasking features of the language. There is also an extra chapter called `gcc' containing a template for creating new executable tests. The tests are run using two `sh' scripts: `run_acats' and `run_all.sh'. To run the tests using a simulator or a cross target, see the small customization section at the top of `run_all.sh'. These tests are run using the build tree: they can be run without doing a `make install'.  File: gccint.info, Node: C Tests, Next: libgcj Tests, Prev: Ada Tests, Up: Testsuites 6.4.4 C Language Testsuites --------------------------- GCC contains the following C language testsuites, in the `gcc/testsuite' directory: `gcc.dg' This contains tests of particular features of the C compiler, using the more modern `dg' harness. Correctness tests for various compiler features should go here if possible. Magic comments determine whether the file is preprocessed, compiled, linked or run. In these tests, error and warning message texts are compared against expected texts or regular expressions given in comments. These tests are run with the options `-ansi -pedantic' unless other options are given in the test. Except as noted below they are not run with multiple optimization options. `gcc.dg/compat' This subdirectory contains tests for binary compatibility using `compat.exp', which in turn uses the language-independent support (*note Support for testing binary compatibility: compat Testing.). `gcc.dg/cpp' This subdirectory contains tests of the preprocessor. `gcc.dg/debug' This subdirectory contains tests for debug formats. Tests in this subdirectory are run for each debug format that the compiler supports. `gcc.dg/format' This subdirectory contains tests of the `-Wformat' format checking. Tests in this directory are run with and without `-DWIDE'. `gcc.dg/noncompile' This subdirectory contains tests of code that should not compile and does not need any special compilation options. They are run with multiple optimization options, since sometimes invalid code crashes the compiler with optimization. `gcc.dg/special' FIXME: describe this. `gcc.c-torture' This contains particular code fragments which have historically broken easily. These tests are run with multiple optimization options, so tests for features which only break at some optimization levels belong here. This also contains tests to check that certain optimizations occur. It might be worthwhile to separate the correctness tests cleanly from the code quality tests, but it hasn't been done yet. `gcc.c-torture/compat' FIXME: describe this. This directory should probably not be used for new tests. `gcc.c-torture/compile' This testsuite contains test cases that should compile, but do not need to link or run. These test cases are compiled with several different combinations of optimization options. All warnings are disabled for these test cases, so this directory is not suitable if you wish to test for the presence or absence of compiler warnings. While special options can be set, and tests disabled on specific platforms, by the use of `.x' files, mostly these test cases should not contain platform dependencies. FIXME: discuss how defines such as `NO_LABEL_VALUES' and `STACK_SIZE' are used. `gcc.c-torture/execute' This testsuite contains test cases that should compile, link and run; otherwise the same comments as for `gcc.c-torture/compile' apply. `gcc.c-torture/execute/ieee' This contains tests which are specific to IEEE floating point. `gcc.c-torture/unsorted' FIXME: describe this. This directory should probably not be used for new tests. `gcc.c-torture/misc-tests' This directory contains C tests that require special handling. Some of these tests have individual expect files, and others share special-purpose expect files: ``bprob*.c'' Test `-fbranch-probabilities' using `bprob.exp', which in turn uses the generic, language-independent framework (*note Support for testing profile-directed optimizations: profopt Testing.). ``dg-*.c'' Test the testsuite itself using `dg-test.exp'. ``gcov*.c'' Test `gcov' output using `gcov.exp', which in turn uses the language-independent support (*note Support for testing gcov: gcov Testing.). ``i386-pf-*.c'' Test i386-specific support for data prefetch using `i386-prefetch.exp'. FIXME: merge in `testsuite/README.gcc' and discuss the format of test cases and magic comments more.  File: gccint.info, Node: libgcj Tests, Next: gcov Testing, Prev: C Tests, Up: Testsuites 6.4.5 The Java library testsuites. ---------------------------------- Runtime tests are executed via `make check' in the `TARGET/libjava/testsuite' directory in the build tree. Additional runtime tests can be checked into this testsuite. Regression testing of the core packages in libgcj is also covered by the Mauve testsuite. The Mauve Project develops tests for the Java Class Libraries. These tests are run as part of libgcj testing by placing the Mauve tree within the libjava testsuite sources at `libjava/testsuite/libjava.mauve/mauve', or by specifying the location of that tree when invoking `make', as in `make MAUVEDIR=~/mauve check'. To detect regressions, a mechanism in `mauve.exp' compares the failures for a test run against the list of expected failures in `libjava/testsuite/libjava.mauve/xfails' from the source hierarchy. Update this file when adding new failing tests to Mauve, or when fixing bugs in libgcj that had caused Mauve test failures. We encourage developers to contribute test cases to Mauve.  File: gccint.info, Node: gcov Testing, Next: profopt Testing, Prev: libgcj Tests, Up: Testsuites 6.4.6 Support for testing `gcov' -------------------------------- Language-independent support for testing `gcov', and for checking that branch profiling produces expected values, is provided by the expect file `gcov.exp'. `gcov' tests also rely on procedures in `gcc.dg.exp' to compile and run the test program. A typical `gcov' test contains the following DejaGnu commands within comments: { dg-options "-fprofile-arcs -ftest-coverage" } { dg-do run { target native } } { dg-final { run-gcov sourcefile } } Checks of `gcov' output can include line counts, branch percentages, and call return percentages. All of these checks are requested via commands that appear in comments in the test's source file. Commands to check line counts are processed by default. Commands to check branch percentages and call return percentages are processed if the `run-gcov' command has arguments `branches' or `calls', respectively. For example, the following specifies checking both, as well as passing `-b' to `gcov': { dg-final { run-gcov branches calls { -b sourcefile } } } A line count command appears within a comment on the source line that is expected to get the specified count and has the form `count(CNT)'. A test should only check line counts for lines that will get the same count for any architecture. Commands to check branch percentages (`branch') and call return percentages (`returns') are very similar to each other. A beginning command appears on or before the first of a range of lines that will report the percentage, and the ending command follows that range of lines. The beginning command can include a list of percentages, all of which are expected to be found within the range. A range is terminated by the next command of the same kind. A command `branch(end)' or `returns(end)' marks the end of a range without starting a new one. For example: if (i > 10 && j > i && j < 20) /* branch(27 50 75) */ /* branch(end) */ foo (i, j); For a call return percentage, the value specified is the percentage of calls reported to return. For a branch percentage, the value is either the expected percentage or 100 minus that value, since the direction of a branch can differ depending on the target or the optimization level. Not all branches and calls need to be checked. A test should not check for branches that might be optimized away or replaced with predicated instructions. Don't check for calls inserted by the compiler or ones that might be inlined or optimized away. A single test can check for combinations of line counts, branch percentages, and call return percentages. The command to check a line count must appear on the line that will report that count, but commands to check branch percentages and call return percentages can bracket the lines that report them.  File: gccint.info, Node: profopt Testing, Next: compat Testing, Prev: gcov Testing, Up: Testsuites 6.4.7 Support for testing profile-directed optimizations -------------------------------------------------------- The file `profopt.exp' provides language-independent support for checking correct execution of a test built with profile-directed optimization. This testing requires that a test program be built and executed twice. The first time it is compiled to generate profile data, and the second time it is compiled to use the data that was generated during the first execution. The second execution is to verify that the test produces the expected results. To check that the optimization actually generated better code, a test can be built and run a third time with normal optimizations to verify that the performance is better with the profile-directed optimizations. `profopt.exp' has the beginnings of this kind of support. `profopt.exp' provides generic support for profile-directed optimizations. Each set of tests that uses it provides information about a specific optimization: `tool' tool being tested, e.g., `gcc' `profile_option' options used to generate profile data `feedback_option' options used to optimize using that profile data `prof_ext' suffix of profile data files `PROFOPT_OPTIONS' list of options with which to run each test, similar to the lists for torture tests  File: gccint.info, Node: compat Testing, Next: Torture Tests, Prev: profopt Testing, Up: Testsuites 6.4.8 Support for testing binary compatibility ---------------------------------------------- The file `compat.exp' provides language-independent support for binary compatibility testing. It supports testing interoperability of two compilers that follow the same ABI, or of multiple sets of compiler options that should not affect binary compatibility. It is intended to be used for testsuites that complement ABI testsuites. A test supported by this framework has three parts, each in a separate source file: a main program and two pieces that interact with each other to split up the functionality being tested. `TESTNAME_main.SUFFIX' Contains the main program, which calls a function in file `TESTNAME_x.SUFFIX'. `TESTNAME_x.SUFFIX' Contains at least one call to a function in `TESTNAME_y.SUFFIX'. `TESTNAME_y.SUFFIX' Shares data with, or gets arguments from, `TESTNAME_x.SUFFIX'. Within each test, the main program and one functional piece are compiled by the GCC under test. The other piece can be compiled by an alternate compiler. If no alternate compiler is specified, then all three source files are all compiled by the GCC under test. You can specify pairs of sets of compiler options. The first element of such a pair specifies options used with the GCC under test, and the second element of the pair specifies options used with the alternate compiler. Each test is compiled with each pair of options. `compat.exp' defines default pairs of compiler options. These can be overridden by defining the environment variable `COMPAT_OPTIONS' as: COMPAT_OPTIONS="[list [list {TST1} {ALT1}] ...[list {TSTN} {ALTN}]]" where TSTI and ALTI are lists of options, with TSTI used by the compiler under test and ALTI used by the alternate compiler. For example, with `[list [list {-g -O0} {-O3}] [list {-fpic} {-fPIC -O2}]]', the test is first built with `-g -O0' by the compiler under test and with `-O3' by the alternate compiler. The test is built a second time using `-fpic' by the compiler under test and `-fPIC -O2' by the alternate compiler. An alternate compiler is specified by defining an environment variable to be the full pathname of an installed compiler; for C define `ALT_CC_UNDER_TEST', and for C++ define `ALT_CXX_UNDER_TEST'. These will be written to the `site.exp' file used by DejaGnu. The default is to build each test with the compiler under test using the first of each pair of compiler options from `COMPAT_OPTIONS'. When `ALT_CC_UNDER_TEST' or `ALT_CXX_UNDER_TEST' is `same', each test is built using the compiler under test but with combinations of the options from `COMPAT_OPTIONS'. To run only the C++ compatibility suite using the compiler under test and another version of GCC using specific compiler options, do the following from `OBJDIR/gcc': rm site.exp make -k \ ALT_CXX_UNDER_TEST=${alt_prefix}/bin/g++ \ COMPAT_OPTIONS="lists as shown above" \ check-c++ \ RUNTESTFLAGS="compat.exp" A test that fails when the source files are compiled with different compilers, but passes when the files are compiled with the same compiler, demonstrates incompatibility of the generated code or runtime support. A test that fails for the alternate compiler but passes for the compiler under test probably tests for a bug that was fixed in the compiler under test but is present in the alternate compiler. The binary compatibility tests support a small number of test framework commands that appear within comments in a test file. `dg-require-*' These commands can be used in `TESTNAME_main.SUFFIX' to skip the test if specific support is not available on the target. `dg-options' The specified options are used for compiling this particular source file, appended to the options from `COMPAT_OPTIONS'. When this command appears in `TESTNAME_main.SUFFIX' the options are also used to link the test program. `dg-xfail-if' This command can be used in a secondary source file to specify that compilation is expected to fail for particular options on particular targets.  File: gccint.info, Node: Torture Tests, Prev: compat Testing, Up: Testsuites 6.4.9 Support for torture testing using multiple options -------------------------------------------------------- Throughout the compiler testsuite there are several directories whose tests are run multiple times, each with a different set of options. These are known as torture tests. `gcc/testsuite/lib/torture-options.exp' defines procedures to set up these lists: `torture-init' Initialize use of torture lists. `set-torture-options' Set lists of torture options to use for tests with and without loops. Optionally combine a set of torture options with a set of other options, as is done with Objective-C runtime options. `torture-finish' Finalize use of torture lists. The `.exp' file for a set of tests that use torture options must include calls to these three procecures if: * It calls `gcc-dg-runtest' and overrides DG_TORTURE_OPTIONS. * It calls ${TOOL}`-torture' or ${TOOL}`-torture-execute', where TOOL is `c', `fortran', or `objc'. * It calls `dg-pch'. It is not necessary for a `.exp' file that calls `gcc-dg-runtest' to call the torture procedures if the tests should use the list in DG_TORTURE_OPTIONS defined in `gcc-dg.exp'. Most uses of torture options can override the default lists by defining TORTURE_OPTIONS in a `.dejagnurc' file.  File: gccint.info, Node: Options, Next: Passes, Prev: Source Tree, Up: Top 7 Option specification files **************************** Most GCC command-line options are described by special option definition files, the names of which conventionally end in `.opt'. This chapter describes the format of these files. * Menu: * Option file format:: The general layout of the files * Option properties:: Supported option properties  File: gccint.info, Node: Option file format, Next: Option properties, Up: Options 7.1 Option file format ====================== Option files are a simple list of records in which each field occupies its own line and in which the records themselves are separated by blank lines. Comments may appear on their own line anywhere within the file and are preceded by semicolons. Whitespace is allowed before the semicolon. The files can contain the following types of record: * A language definition record.  These records have two fields: the string `Language' and the name of the language.  Once a language has been declared in this way, it can be used as an option property. *Note Option properties::. * An option definition record.  These records have the following fields: 1. the name of the option, with the leading "-" removed 2. a space-separated list of option properties (*note Option properties::) 3. the help text to use for `--help' (omitted if the second field contains the `Undocumented' property). By default, all options beginning with "f", "W" or "m" are implicitly assumed to take a "no-" form. This form should not be listed separately. If an option beginning with one of these letters does not have a "no-" form, you can use the `RejectNegative' property to reject it. The help text is automatically line-wrapped before being displayed. Normally the name of the option is printed on the left-hand side of the output and the help text is printed on the right. However, if the help text contains a tab character, the text to the left of the tab is used instead of the option's name and the text to the right of the tab forms the help text. This allows you to elaborate on what type of argument the option takes. * A target mask record.  These records have one field of the form `Mask(X)'.  The options-processing script will automatically allocate a bit in `target_flags' (*note Run-time Target::) for each mask name X and set the macro `MASK_X' to the appropriate bitmask.  It will also declare a `TARGET_X' macro that has the value 1 when bit `MASK_X' is set and 0 otherwise. They are primarily intended to declare target masks that are not associated with user options, either because these masks represent internal switches or because the options are not available on all configurations and yet the masks always need to be defined.  File: gccint.info, Node: Option properties, Prev: Option file format, Up: Options 7.2 Option properties ===================== The second field of an option record can specify the following properties: `Common' The option is available for all languages and targets. `Target' The option is available for all languages but is target-specific. `LANGUAGE' The option is available when compiling for the given language. It is possible to specify several different languages for the same option. Each LANGUAGE must have been declared by an earlier `Language' record. *Note Option file format::. `RejectNegative' The option does not have a "no-" form. All options beginning with "f", "W" or "m" are assumed to have a "no-" form unless this property is used. `Negative(OTHERNAME)' The option will turn off another option OTHERNAME, which is the the option name with the leading "-" removed. This chain action will propagate through the `Negative' property of the option to be turned off. `Joined' `Separate' The option takes a mandatory argument. `Joined' indicates that the option and argument can be included in the same `argv' entry (as with `-mflush-func=NAME', for example). `Separate' indicates that the option and argument can be separate `argv' entries (as with `-o'). An option is allowed to have both of these properties. `JoinedOrMissing' The option takes an optional argument. If the argument is given, it will be part of the same `argv' entry as the option itself. This property cannot be used alongside `Joined' or `Separate'. `UInteger' The option's argument is a non-negative integer. The option parser will check and convert the argument before passing it to the relevant option handler. `Var(VAR)' The state of this option should be stored in variable VAR. The way that the state is stored depends on the type of option: * If the option uses the `Mask' or `InverseMask' properties, VAR is the integer variable that contains the mask. * If the option is a normal on/off switch, VAR is an integer variable that is nonzero when the option is enabled. The options parser will set the variable to 1 when the positive form of the option is used and 0 when the "no-" form is used. * If the option takes an argument and has the `UInteger' property, VAR is an integer variable that stores the value of the argument. * Otherwise, if the option takes an argument, VAR is a pointer to the argument string. The pointer will be null if the argument is optional and wasn't given. The option-processing script will usually declare VAR in `options.c' and leave it to be zero-initialized at start-up time. You can modify this behavior using `VarExists' and `Init'. `Var(VAR, SET)' The option controls an integer variable VAR and is active when VAR equals SET. The option parser will set VAR to SET when the positive form of the option is used and `!SET' when the "no-" form is used. VAR is declared in the same way as for the single-argument form described above. `VarExists' The variable specified by the `Var' property already exists. No definition should be added to `options.c' in response to this option record. You should use this property only if the variable is declared outside `options.c'. `Init(VALUE)' The variable specified by the `Var' property should be statically initialized to VALUE. `Mask(NAME)' The option is associated with a bit in the `target_flags' variable (*note Run-time Target::) and is active when that bit is set. You may also specify `Var' to select a variable other than `target_flags'. The options-processing script will automatically allocate a unique bit for the option. If the option is attached to `target_flags', the script will set the macro `MASK_NAME' to the appropriate bitmask. It will also declare a `TARGET_NAME' macro that has the value 1 when the option is active and 0 otherwise. If you use `Var' to attach the option to a different variable, the associated macros are called `OPTION_MASK_NAME' and `OPTION_NAME' respectively. You can disable automatic bit allocation using `MaskExists'. `InverseMask(OTHERNAME)' `InverseMask(OTHERNAME, THISNAME)' The option is the inverse of another option that has the `Mask(OTHERNAME)' property. If THISNAME is given, the options-processing script will declare a `TARGET_THISNAME' macro that is 1 when the option is active and 0 otherwise. `MaskExists' The mask specified by the `Mask' property already exists. No `MASK' or `TARGET' definitions should be added to `options.h' in response to this option record. The main purpose of this property is to support synonymous options. The first option should use `Mask(NAME)' and the others should use `Mask(NAME) MaskExists'. `Report' The state of the option should be printed by `-fverbose-asm'. `Undocumented' The option is deliberately missing documentation and should not be included in the `--help' output. `Condition(COND)' The option should only be accepted if preprocessor condition COND is true. Note that any C declarations associated with the option will be present even if COND is false; COND simply controls whether the option is accepted and whether it is printed in the `--help' output.  File: gccint.info, Node: Passes, Next: Trees, Prev: Options, Up: Top 8 Passes and Files of the Compiler ********************************** This chapter is dedicated to giving an overview of the optimization and code generation passes of the compiler. In the process, it describes some of the language front end interface, though this description is no where near complete. * Menu: * Parsing pass:: The language front end turns text into bits. * Gimplification pass:: The bits are turned into something we can optimize. * Pass manager:: Sequencing the optimization passes. * Tree SSA passes:: Optimizations on a high-level representation. * RTL passes:: Optimizations on a low-level representation.  File: gccint.info, Node: Parsing pass, Next: Gimplification pass, Up: Passes 8.1 Parsing pass ================ The language front end is invoked only once, via `lang_hooks.parse_file', to parse the entire input. The language front end may use any intermediate language representation deemed appropriate. The C front end uses GENERIC trees (CROSSREF), plus a double handful of language specific tree codes defined in `c-common.def'. The Fortran front end uses a completely different private representation. At some point the front end must translate the representation used in the front end to a representation understood by the language-independent portions of the compiler. Current practice takes one of two forms. The C front end manually invokes the gimplifier (CROSSREF) on each function, and uses the gimplifier callbacks to convert the language-specific tree nodes directly to GIMPLE (CROSSREF) before passing the function off to be compiled. The Fortran front end converts from a private representation to GENERIC, which is later lowered to GIMPLE when the function is compiled. Which route to choose probably depends on how well GENERIC (plus extensions) can be made to match up with the source language and necessary parsing data structures. BUG: Gimplification must occur before nested function lowering, and nested function lowering must be done by the front end before passing the data off to cgraph. TODO: Cgraph should control nested function lowering. It would only be invoked when it is certain that the outer-most function is used. TODO: Cgraph needs a gimplify_function callback. It should be invoked when (1) it is certain that the function is used, (2) warning flags specified by the user require some amount of compilation in order to honor, (3) the language indicates that semantic analysis is not complete until gimplification occurs. Hum... this sounds overly complicated. Perhaps we should just have the front end gimplify always; in most cases it's only one function call. The front end needs to pass all function definitions and top level declarations off to the middle-end so that they can be compiled and emitted to the object file. For a simple procedural language, it is usually most convenient to do this as each top level declaration or definition is seen. There is also a distinction to be made between generating functional code and generating complete debug information. The only thing that is absolutely required for functional code is that function and data _definitions_ be passed to the middle-end. For complete debug information, function, data and type declarations should all be passed as well. In any case, the front end needs each complete top-level function or data declaration, and each data definition should be passed to `rest_of_decl_compilation'. Each complete type definition should be passed to `rest_of_type_compilation'. Each function definition should be passed to `cgraph_finalize_function'. TODO: I know rest_of_compilation currently has all sorts of RTL generation semantics. I plan to move all code generation bits (both Tree and RTL) to compile_function. Should we hide cgraph from the front ends and move back to rest_of_compilation as the official interface? Possibly we should rename all three interfaces such that the names match in some meaningful way and that is more descriptive than "rest_of". The middle-end will, at its option, emit the function and data definitions immediately or queue them for later processing.  File: gccint.info, Node: Gimplification pass, Next: Pass manager, Prev: Parsing pass, Up: Passes 8.2 Gimplification pass ======================= "Gimplification" is a whimsical term for the process of converting the intermediate representation of a function into the GIMPLE language (CROSSREF). The term stuck, and so words like "gimplification", "gimplify", "gimplifier" and the like are sprinkled throughout this section of code. While a front end may certainly choose to generate GIMPLE directly if it chooses, this can be a moderately complex process unless the intermediate language used by the front end is already fairly simple. Usually it is easier to generate GENERIC trees plus extensions and let the language-independent gimplifier do most of the work. The main entry point to this pass is `gimplify_function_tree' located in `gimplify.c'. From here we process the entire function gimplifying each statement in turn. The main workhorse for this pass is `gimplify_expr'. Approximately everything passes through here at least once, and it is from here that we invoke the `lang_hooks.gimplify_expr' callback. The callback should examine the expression in question and return `GS_UNHANDLED' if the expression is not a language specific construct that requires attention. Otherwise it should alter the expression in some way to such that forward progress is made toward producing valid GIMPLE. If the callback is certain that the transformation is complete and the expression is valid GIMPLE, it should return `GS_ALL_DONE'. Otherwise it should return `GS_OK', which will cause the expression to be processed again. If the callback encounters an error during the transformation (because the front end is relying on the gimplification process to finish semantic checks), it should return `GS_ERROR'.  File: gccint.info, Node: Pass manager, Next: Tree SSA passes, Prev: Gimplification pass, Up: Passes 8.3 Pass manager ================ The pass manager is located in `passes.c', `tree-optimize.c' and `tree-pass.h'. Its job is to run all of the individual passes in the correct order, and take care of standard bookkeeping that applies to every pass. The theory of operation is that each pass defines a structure that represents everything we need to know about that pass--when it should be run, how it should be run, what intermediate language form or on-the-side data structures it needs. We register the pass to be run in some particular order, and the pass manager arranges for everything to happen in the correct order. The actuality doesn't completely live up to the theory at present. Command-line switches and `timevar_id_t' enumerations must still be defined elsewhere. The pass manager validates constraints but does not attempt to (re-)generate data structures or lower intermediate language form based on the requirements of the next pass. Nevertheless, what is present is useful, and a far sight better than nothing at all. TODO: describe the global variables set up by the pass manager, and a brief description of how a new pass should use it. I need to look at what info RTL passes use first...  File: gccint.info, Node: Tree SSA passes, Next: RTL passes, Prev: Pass manager, Up: Passes 8.4 Tree SSA passes =================== The following briefly describes the Tree optimization passes that are run after gimplification and what source files they are located in. * Remove useless statements This pass is an extremely simple sweep across the gimple code in which we identify obviously dead code and remove it. Here we do things like simplify `if' statements with constant conditions, remove exception handling constructs surrounding code that obviously cannot throw, remove lexical bindings that contain no variables, and other assorted simplistic cleanups. The idea is to get rid of the obvious stuff quickly rather than wait until later when it's more work to get rid of it. This pass is located in `tree-cfg.c' and described by `pass_remove_useless_stmts'. * Mudflap declaration registration If mudflap (*note -fmudflap -fmudflapth -fmudflapir: (gcc)Optimize Options.) is enabled, we generate code to register some variable declarations with the mudflap runtime. Specifically, the runtime tracks the lifetimes of those variable declarations that have their addresses taken, or whose bounds are unknown at compile time (`extern'). This pass generates new exception handling constructs (`try'/`finally'), and so must run before those are lowered. In addition, the pass enqueues declarations of static variables whose lifetimes extend to the entire program. The pass is located in `tree-mudflap.c' and is described by `pass_mudflap_1'. * OpenMP lowering If OpenMP generation (`-fopenmp') is enabled, this pass lowers OpenMP constructs into GIMPLE. Lowering of OpenMP constructs involves creating replacement expressions for local variables that have been mapped using data sharing clauses, exposing the control flow of most synchronization directives and adding region markers to facilitate the creation of the control flow graph. The pass is located in `omp-low.c' and is described by `pass_lower_omp'. * OpenMP expansion If OpenMP generation (`-fopenmp') is enabled, this pass expands parallel regions into their own functions to be invoked by the thread library. The pass is located in `omp-low.c' and is described by `pass_expand_omp'. * Lower control flow This pass flattens `if' statements (`COND_EXPR') and moves lexical bindings (`BIND_EXPR') out of line. After this pass, all `if' statements will have exactly two `goto' statements in its `then' and `else' arms. Lexical binding information for each statement will be found in `TREE_BLOCK' rather than being inferred from its position under a `BIND_EXPR'. This pass is found in `gimple-low.c' and is described by `pass_lower_cf'. * Lower exception handling control flow This pass decomposes high-level exception handling constructs (`TRY_FINALLY_EXPR' and `TRY_CATCH_EXPR') into a form that explicitly represents the control flow involved. After this pass, `lookup_stmt_eh_region' will return a non-negative number for any statement that may have EH control flow semantics; examine `tree_can_throw_internal' or `tree_can_throw_external' for exact semantics. Exact control flow may be extracted from `foreach_reachable_handler'. The EH region nesting tree is defined in `except.h' and built in `except.c'. The lowering pass itself is in `tree-eh.c' and is described by `pass_lower_eh'. * Build the control flow graph This pass decomposes a function into basic blocks and creates all of the edges that connect them. It is located in `tree-cfg.c' and is described by `pass_build_cfg'. * Find all referenced variables This pass walks the entire function and collects an array of all variables referenced in the function, `referenced_vars'. The index at which a variable is found in the array is used as a UID for the variable within this function. This data is needed by the SSA rewriting routines. The pass is located in `tree-dfa.c' and is described by `pass_referenced_vars'. * Enter static single assignment form This pass rewrites the function such that it is in SSA form. After this pass, all `is_gimple_reg' variables will be referenced by `SSA_NAME', and all occurrences of other variables will be annotated with `VDEFS' and `VUSES'; PHI nodes will have been inserted as necessary for each basic block. This pass is located in `tree-ssa.c' and is described by `pass_build_ssa'. * Warn for uninitialized variables This pass scans the function for uses of `SSA_NAME's that are fed by default definition. For non-parameter variables, such uses are uninitialized. The pass is run twice, before and after optimization. In the first pass we only warn for uses that are positively uninitialized; in the second pass we warn for uses that are possibly uninitialized. The pass is located in `tree-ssa.c' and is defined by `pass_early_warn_uninitialized' and `pass_late_warn_uninitialized'. * Dead code elimination This pass scans the function for statements without side effects whose result is unused. It does not do memory life analysis, so any value that is stored in memory is considered used. The pass is run multiple times throughout the optimization process. It is located in `tree-ssa-dce.c' and is described by `pass_dce'. * Dominator optimizations This pass performs trivial dominator-based copy and constant propagation, expression simplification, and jump threading. It is run multiple times throughout the optimization process. It it located in `tree-ssa-dom.c' and is described by `pass_dominator'. * Forward propagation of single-use variables This pass attempts to remove redundant computation by substituting variables that are used once into the expression that uses them and seeing if the result can be simplified. It is located in `tree-ssa-forwprop.c' and is described by `pass_forwprop'. * Copy Renaming This pass attempts to change the name of compiler temporaries involved in copy operations such that SSA->normal can coalesce the copy away. When compiler temporaries are copies of user variables, it also renames the compiler temporary to the user variable resulting in better use of user symbols. It is located in `tree-ssa-copyrename.c' and is described by `pass_copyrename'. * PHI node optimizations This pass recognizes forms of PHI inputs that can be represented as conditional expressions and rewrites them into straight line code. It is located in `tree-ssa-phiopt.c' and is described by `pass_phiopt'. * May-alias optimization This pass performs a flow sensitive SSA-based points-to analysis. The resulting may-alias, must-alias, and escape analysis information is used to promote variables from in-memory addressable objects to non-aliased variables that can be renamed into SSA form. We also update the `VDEF'/`VUSE' memory tags for non-renameable aggregates so that we get fewer false kills. The pass is located in `tree-ssa-alias.c' and is described by `pass_may_alias'. Interprocedural points-to information is located in `tree-ssa-structalias.c' and described by `pass_ipa_pta'. * Profiling This pass rewrites the function in order to collect runtime block and value profiling data. Such data may be fed back into the compiler on a subsequent run so as to allow optimization based on expected execution frequencies. The pass is located in `predict.c' and is described by `pass_profile'. * Lower complex arithmetic This pass rewrites complex arithmetic operations into their component scalar arithmetic operations. The pass is located in `tree-complex.c' and is described by `pass_lower_complex'. * Scalar replacement of aggregates This pass rewrites suitable non-aliased local aggregate variables into a set of scalar variables. The resulting scalar variables are rewritten into SSA form, which allows subsequent optimization passes to do a significantly better job with them. The pass is located in `tree-sra.c' and is described by `pass_sra'. * Dead store elimination This pass eliminates stores to memory that are subsequently overwritten by another store, without any intervening loads. The pass is located in `tree-ssa-dse.c' and is described by `pass_dse'. * Tail recursion elimination This pass transforms tail recursion into a loop. It is located in `tree-tailcall.c' and is described by `pass_tail_recursion'. * Forward store motion This pass sinks stores and assignments down the flowgraph closer to their use point. The pass is located in `tree-ssa-sink.c' and is described by `pass_sink_code'. * Partial redundancy elimination This pass eliminates partially redundant computations, as well as performing load motion. The pass is located in `tree-ssa-pre.c' and is described by `pass_pre'. Just before partial redundancy elimination, if `-funsafe-math-optimizations' is on, GCC tries to convert divisions to multiplications by the reciprocal. The pass is located in `tree-ssa-math-opts.c' and is described by `pass_cse_reciprocal'. * Full redundancy elimination This is a simpler form of PRE that only eliminates redundancies that occur an all paths. It is located in `tree-ssa-pre.c' and described by `pass_fre'. * Loop optimization The main driver of the pass is placed in `tree-ssa-loop.c' and described by `pass_loop'. The optimizations performed by this pass are: Loop invariant