+++ /dev/null
-This is doc/gccint.info, produced by makeinfo version 4.5 from
-doc/gccint.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gccint: (gccint). Internals of the GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the internals of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: gccint.info, Node: Back End, Prev: Front End, Up: gcc Directory
-
-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'.
-
- * 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/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 CVS repository, the
-following are also necessary:
-
- * An entry for the target architecture in `readings.html' on the GCC
- web site, with any relevant links.
-
- * 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.
-
-\1f
-File: gccint.info, Node: Test Suites, Prev: gcc Directory, Up: Source Tree
-
-Test Suites
-===========
-
- GCC contains several test suites to help maintain compiler quality.
-Most of the runtime libraries and language front ends in GCC have test
-suites. Currently only the C language test suites are documented here;
-FIXME: document the others.
-
-* Menu:
-
-* Test Idioms:: Idioms used in test suite code.
-* C Tests:: The C language test suites.
-* libgcj Tests:: The Java library test suites.
-
-\1f
-File: gccint.info, Node: Test Idioms, Next: C Tests, Up: Test Suites
-
-Idioms Used in Test Suite Code
-------------------------------
-
- In the `gcc.c-torture' test suites, test cases are commonly 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. In other
-test suites, more descriptive names are used. In general C test cases
-have a trailing `-N.c', starting with `-1.c', in case other test cases
-with similar names are added later.
-
- Test cases should use `abort ()' to indicate failure and `exit (0)'
-for success; on some targets these may be redefined to indicate failure
-and success in other ways.
-
- In the `gcc.dg' test suite, 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).
-
- FIXME: discuss non-C test suites here.
-
-\1f
-File: gccint.info, Node: C Tests, Next: libgcj Tests, Prev: Test Idioms, Up: Test Suites
-
-C Language Test Suites
-----------------------
-
- GCC contains the following C language test suites, in the
-`gcc/testsuite' directory:
-
-`gcc.c-torture/compat'
- FIXME: describe this.
-
- This directory should probably not be used for new tests.
-
-`gcc.c-torture/compile'
- This test suite 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 test suite contains test cases that should compile, link and
- run; otherwise the same comments as for `gcc.c-torture/compile'
- apply.
-
-`gcc.c-torture/unsorted'
- FIXME: describe this.
-
- This directory should probably not be used for new tests.
-
-`gcc.dg'
- This test suite contains tests using the more modern `dg' harness.
- 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/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/misc-tests'
- FIXME: describe this, when it should be used for new tests and
- when it shouldn't.
-
- FIXME: merge in `testsuite/README.gcc' and discuss the format of
-test cases and magic comments more.
-
-\1f
-File: gccint.info, Node: libgcj Tests, Prev: C Tests, Up: Test Suites
-
-The Java library test suites.
------------------------------
-
- Runtime tests are executed via `make check' from the `testsuite'
-directory of the libjava hierarchy 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 test suite. The Mauve Project develops tests for the Java
-Class Libraries. These tests are run as part of libgcj testing by
-specifying the location of the Mauve tree when invoking `make', as in
-`make MAUVEDIR=~/mauve check'.
-
- The Jacks project provides a test suite for Java compilers that can
-be used to test changes that affect the GCJ front end. There is no
-automated mechanism to run the Jacks suite as part of GCJ testing.
-
- We encourage developers to contribute test cases to Mauve and Jacks.
-
-\1f
-File: gccint.info, Node: Passes, Next: Trees, Prev: Source Tree, Up: Top
-
-Passes and Files of the Compiler
-********************************
-
- The overall control structure of the compiler is in `toplev.c'. This
-file is responsible for initialization, decoding arguments, opening and
-closing files, and sequencing the passes.
-
- The parsing pass is invoked only once, to parse the entire input. A
-high level tree representation is then generated from the input, one
-function at a time. This tree code is then transformed into RTL
-intermediate code, and processed. The files involved in transforming
-the trees into RTL are `expr.c', `expmed.c', and `stmt.c'. The order
-of trees that are processed, is not necessarily the same order they are
-generated from the input, due to deferred inlining, and other
-considerations.
-
- Each time the parsing pass reads a complete function definition or
-top-level declaration, it calls either the function
-`rest_of_compilation', or the function `rest_of_decl_compilation' in
-`toplev.c', which are responsible for all further processing necessary,
-ending with output of the assembler language. All other compiler
-passes run, in sequence, within `rest_of_compilation'. When that
-function returns from compiling a function definition, the storage used
-for that function definition's compilation is entirely freed, unless it
-is an inline function, or was deferred for some reason (this can occur
-in templates, for example). (*note An Inline Function is As Fast As a
-Macro: (gcc)Inline.).
-
- Here is a list of all the passes of the compiler and their source
-files. Also included is a description of where debugging dumps can be
-requested with `-d' options.
-
- * Parsing. This pass reads the entire text of a function definition,
- constructing a high level tree representation. (Because of the
- semantic analysis that takes place during this pass, it does more
- than is formally considered to be parsing.)
-
- The tree representation does not entirely follow C syntax, because
- it is intended to support other languages as well.
-
- Language-specific data type analysis is also done in this pass,
- and every tree node that represents an expression has a data type
- attached. Variables are represented as declaration nodes.
-
- The language-independent source files for parsing are `tree.c',
- `fold-const.c', and `stor-layout.c'. There are also header files
- `tree.h' and `tree.def' which define the format of the tree
- representation.
-
- C preprocessing, for language front ends, that want or require it,
- is performed by cpplib, which is covered in separate
- documentation. In particular, the internals are covered in *Note
- Cpplib internals: (cppinternals)Top.
-
- The source files to parse C are `c-convert.c', `c-decl.c',
- `c-errors.c', `c-lang.c', `c-objc-common.c', `c-parse.in',
- `c-aux-info.c', and `c-typeck.c', along with a header file
- `c-tree.h' and some files shared with Objective-C and C++.
-
- The source files for parsing C++ are in `cp/'. They are `parse.y',
- `class.c', `cvt.c', `decl.c', `decl2.c', `except.c', `expr.c',
- `init.c', `lex.c', `method.c', `ptree.c', `search.c', `spew.c',
- `semantics.c', `tree.c', `typeck2.c', and `typeck.c', along with
- header files `cp-tree.def', `cp-tree.h', and `decl.h'.
-
- The special source files for parsing Objective-C are in `objc/'.
- They are `objc-act.c', `objc-tree.def', and `objc-act.h'. Certain
- C-specific files are used for this as well.
-
- The files `c-common.c', `c-common.def', `c-format.c', `c-pragma.c',
- `c-semantics.c', and `c-lex.c', along with header files
- `c-common.h', `c-dump.h', `c-lex.h', and `c-pragma.h', are also
- used for all of the above languages.
-
- * Tree optimization. This is the optimization of the tree
- representation, before converting into RTL code.
-
- Currently, the main optimization performed here is tree-based
- inlining. This is implemented in `tree-inline.c' and used by both
- C and C++. Note that tree based inlining turns off rtx based
- inlining (since it's more powerful, it would be a waste of time to
- do rtx based inlining in addition).
-
- Constant folding and some arithmetic simplifications are also done
- during this pass, on the tree representation. The routines that
- perform these tasks are located in `fold-const.c'.
-
- * RTL generation. This is the conversion of syntax tree into RTL
- code.
-
- This is where the bulk of target-parameter-dependent code is found,
- since often it is necessary for strategies to apply only when
- certain standard kinds of instructions are available. The purpose
- of named instruction patterns is to provide this information to
- the RTL generation pass.
-
- Optimization is done in this pass for `if'-conditions that are
- comparisons, boolean operations or conditional expressions. Tail
- recursion is detected at this time also. Decisions are made about
- how best to arrange loops and how to output `switch' statements.
-
- The source files for RTL generation include `stmt.c', `calls.c',
- `expr.c', `explow.c', `expmed.c', `function.c', `optabs.c' and
- `emit-rtl.c'. Also, the file `insn-emit.c', generated from the
- machine description by the program `genemit', is used in this
- pass. The header file `expr.h' is used for communication within
- this pass.
-
- The header files `insn-flags.h' and `insn-codes.h', generated from
- the machine description by the programs `genflags' and `gencodes',
- tell this pass which standard names are available for use and
- which patterns correspond to them.
-
- Aside from debugging information output, none of the following
- passes refers to the tree structure representation of the function
- (only part of which is saved).
-
- The decision of whether the function can and should be expanded
- inline in its subsequent callers is made at the end of rtl
- generation. The function must meet certain criteria, currently
- related to the size of the function and the types and number of
- parameters it has. Note that this function may contain loops,
- recursive calls to itself (tail-recursive functions can be
- inlined!), gotos, in short, all constructs supported by GCC. The
- file `integrate.c' contains the code to save a function's rtl for
- later inlining and to inline that rtl when the function is called.
- The header file `integrate.h' is also used for this purpose.
-
- The option `-dr' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.rtl' to
- the input file name.
-
- * Sibiling call optimization. This pass performs tail recursion
- elimination, and tail and sibling call optimizations. The purpose
- of these optimizations is to reduce the overhead of function calls,
- whenever possible.
-
- The source file of this pass is `sibcall.c'
-
- The option `-di' causes a debugging dump of the RTL code after
- this pass is run. This dump file's name is made by appending
- `.sibling' to the input file name.
-
- * Jump optimization. This pass simplifies jumps to the following
- instruction, jumps across jumps, and jumps to jumps. It deletes
- unreferenced labels and unreachable code, except that unreachable
- code that contains a loop is not recognized as unreachable in this
- pass. (Such loops are deleted later in the basic block analysis.)
- It also converts some code originally written with jumps into
- sequences of instructions that directly set values from the
- results of comparisons, if the machine has such instructions.
-
- Jump optimization is performed two or three times. The first time
- is immediately following RTL generation. The second time is after
- CSE, but only if CSE says repeated jump optimization is needed.
- The last time is right before the final pass. That time,
- cross-jumping and deletion of no-op move instructions are done
- together with the optimizations described above.
-
- The source file of this pass is `jump.c'.
-
- The option `-dj' causes a debugging dump of the RTL code after
- this pass is run for the first time. This dump file's name is
- made by appending `.jump' to the input file name.
-
- * Register scan. This pass finds the first and last use of each
- register, as a guide for common subexpression elimination. Its
- source is in `regclass.c'.
-
- * Jump threading. This pass detects a condition jump that branches
- to an identical or inverse test. Such jumps can be `threaded'
- through the second conditional test. The source code for this
- pass is in `jump.c'. This optimization is only performed if
- `-fthread-jumps' is enabled.
-
- * Static Single Assignment (SSA) based optimization passes. The SSA
- conversion passes (to/from) are turned on by the `-fssa' option
- (it is also done automatically if you enable an SSA optimization
- pass). These passes utilize a form called Static Single
- Assignment. In SSA form, each variable (pseudo register) is only
- set once, giving you def-use and use-def chains for free, and
- enabling a lot more optimization passes to be run in linear time.
- Conversion to and from SSA form is handled by functions in `ssa.c'.
-
- The option `-de' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.ssa' to
- the input file name.
- * SSA Conditional Constant Propagation. Turned on by the
- `-fssa-ccp' option. This pass performs conditional constant
- propagation to simplify instructions including conditional
- branches. This pass is more aggressive than the constant
- propagation done by the CSE and GCSE passes, but operates in
- linear time.
-
- The option `-dW' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending
- `.ssaccp' to the input file name.
-
- * SSA Aggressive Dead Code Elimination. Turned on by the
- `-fssa-dce' option. This pass performs elimination of code
- considered unnecessary because it has no externally visible
- effects on the program. It operates in linear time.
-
- The option `-dX' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending
- `.ssadce' to the input file name.
-
- * Common subexpression elimination. This pass also does constant
- propagation. Its source files are `cse.c', and `cselib.c'. If
- constant propagation causes conditional jumps to become
- unconditional or to become no-ops, jump optimization is run again
- when CSE is finished.
-
- The option `-ds' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.cse' to
- the input file name.
-
- * Global common subexpression elimination. This pass performs two
- different types of GCSE depending on whether you are optimizing
- for size or not (LCM based GCSE tends to increase code size for a
- gain in speed, while Morel-Renvoise based GCSE does not). When
- optimizing for size, GCSE is done using Morel-Renvoise Partial
- Redundancy Elimination, with the exception that it does not try to
- move invariants out of loops--that is left to the loop
- optimization pass. If MR PRE GCSE is done, code hoisting (aka
- unification) is also done, as well as load motion. If you are
- optimizing for speed, LCM (lazy code motion) based GCSE is done.
- LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
- based GCSE also does loop invariant code motion. We also perform
- load and store motion when optimizing for speed. Regardless of
- which type of GCSE is used, the GCSE pass also performs global
- constant and copy propagation.
-
- The source file for this pass is `gcse.c', and the LCM routines
- are in `lcm.c'.
-
- The option `-dG' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.gcse' to
- the input file name.
-
- * Loop optimization. This pass moves constant expressions out of
- loops, and optionally does strength-reduction and loop unrolling
- as well. Its source files are `loop.c' and `unroll.c', plus the
- header `loop.h' used for communication between them. Loop
- unrolling uses some functions in `integrate.c' and the header
- `integrate.h'. Loop dependency analysis routines are contained in
- `dependence.c'.
-
- The option `-dL' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.loop' to
- the input file name.
-
- * If `-frerun-cse-after-loop' was enabled, a second common
- subexpression elimination pass is performed after the loop
- optimization pass. Jump threading is also done again at this time
- if it was specified.
-
- The option `-dt' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.cse2' to
- the input file name.
-
- * Data flow analysis (`flow.c'). This pass divides the program into
- basic blocks (and in the process deletes unreachable loops); then
- it computes which pseudo-registers are live at each point in the
- program, and makes the first instruction that uses a value point at
- the instruction that computed the value.
-
- This pass also deletes computations whose results are never used,
- and combines memory references with add or subtract instructions
- to make autoincrement or autodecrement addressing.
-
- The option `-df' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.flow' to
- the input file name. If stupid register allocation is in use, this
- dump file reflects the full results of such allocation.
-
- * Instruction combination (`combine.c'). This pass attempts to
- combine groups of two or three instructions that are related by
- data flow into single instructions. It combines the RTL
- expressions for the instructions by substitution, simplifies the
- result using algebra, and then attempts to match the result
- against the machine description.
-
- The option `-dc' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.combine'
- to the input file name.
-
- * If-conversion is a transformation that transforms control
- dependencies into data dependencies (IE it transforms conditional
- code into a single control stream). It is implemented in the file
- `ifcvt.c'.
-
- The option `-dE' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.ce' to
- the input file name.
-
- * Register movement (`regmove.c'). This pass looks for cases where
- matching constraints would force an instruction to need a reload,
- and this reload would be a register-to-register move. It then
- attempts to change the registers used by the instruction to avoid
- the move instruction.
-
- The option `-dN' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.regmove'
- to the input file name.
-
- * Instruction scheduling (`sched.c'). This pass looks for
- instructions whose output will not be available by the time that
- it is used in subsequent instructions. (Memory loads and floating
- point instructions often have this behavior on RISC machines). It
- re-orders instructions within a basic block to try to separate the
- definition and use of items that otherwise would cause pipeline
- stalls.
-
- Instruction scheduling is performed twice. The first time is
- immediately after instruction combination and the second is
- immediately after reload.
-
- The option `-dS' causes a debugging dump of the RTL code after this
- pass is run for the first time. The dump file's name is made by
- appending `.sched' to the input file name.
-
- * Register class preferencing. The RTL code is scanned to find out
- which register class is best for each pseudo register. The source
- file is `regclass.c'.
-
- * Local register allocation (`local-alloc.c'). This pass allocates
- hard registers to pseudo registers that are used only within one
- basic block. Because the basic block is linear, it can use fast
- and powerful techniques to do a very good job.
-
- The option `-dl' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.lreg' to
- the input file name.
-
- * Global register allocation (`global.c'). This pass allocates hard
- registers for the remaining pseudo registers (those whose life
- spans are not contained in one basic block).
-
- * Reloading. This pass renumbers pseudo registers with the hardware
- registers numbers they were allocated. Pseudo registers that did
- not get hard registers are replaced with stack slots. Then it
- finds instructions that are invalid because a value has failed to
- end up in a register, or has ended up in a register of the wrong
- kind. It fixes up these instructions by reloading the
- problematical values temporarily into registers. Additional
- instructions are generated to do the copying.
-
- The reload pass also optionally eliminates the frame pointer and
- inserts instructions to save and restore call-clobbered registers
- around calls.
-
- Source files are `reload.c' and `reload1.c', plus the header
- `reload.h' used for communication between them.
-
- The option `-dg' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.greg' to
- the input file name.
-
- * Instruction scheduling is repeated here to try to avoid pipeline
- stalls due to memory loads generated for spilled pseudo registers.
-
- The option `-dR' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.sched2'
- to the input file name.
-
- * Basic block reordering. This pass implements profile guided code
- positioning. If profile information is not available, various
- types of static analysis are performed to make the predictions
- normally coming from the profile feedback (IE execution frequency,
- branch probability, etc). It is implemented in the file
- `bb-reorder.c', and the various prediction routines are in
- `predict.c'.
-
- The option `-dB' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.bbro' to
- the input file name.
-
- * Delayed branch scheduling. This optional pass attempts to find
- instructions that can go into the delay slots of other
- instructions, usually jumps and calls. The source file name is
- `reorg.c'.
-
- The option `-dd' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.dbr' to
- the input file name.
-
- * Branch shortening. On many RISC machines, branch instructions
- have a limited range. Thus, longer sequences of instructions must
- be used for long branches. In this pass, the compiler figures out
- what how far each instruction will be from each other instruction,
- and therefore whether the usual instructions, or the longer
- sequences, must be used for each branch.
-
- * Conversion from usage of some hard registers to usage of a register
- stack may be done at this point. Currently, this is supported only
- for the floating-point registers of the Intel 80387 coprocessor.
- The source file name is `reg-stack.c'.
-
- The options `-dk' causes a debugging dump of the RTL code after
- this pass. This dump file's name is made by appending `.stack' to
- the input file name.
-
- * Final. This pass outputs the assembler code for the function. It
- is also responsible for identifying spurious test and compare
- instructions. Machine-specific peephole optimizations are
- performed at the same time. The function entry and exit sequences
- are generated directly as assembler code in this pass; they never
- exist as RTL.
-
- The source files are `final.c' plus `insn-output.c'; the latter is
- generated automatically from the machine description by the tool
- `genoutput'. The header file `conditions.h' is used for
- communication between these files.
-
- * Debugging information output. This is run after final because it
- must output the stack slot offsets for pseudo registers that did
- not get hard registers. Source files are `dbxout.c' for DBX
- symbol table format, `sdbout.c' for SDB symbol table format,
- `dwarfout.c' for DWARF symbol table format, files `dwarf2out.c' and
- `dwarf2asm.c' for DWARF2 symbol table format, and `vmsdbgout.c'
- for VMS debug symbol table format.
-
- Some additional files are used by all or many passes:
-
- * Every pass uses `machmode.def' and `machmode.h' which define the
- machine modes.
-
- * Several passes use `real.h', which defines the default
- representation of floating point constants and how to operate on
- them.
-
- * All the passes that work with RTL use the header files `rtl.h' and
- `rtl.def', and subroutines in file `rtl.c'. The tools `gen*' also
- use these files to read and work with the machine description RTL.
-
- * All the tools that read the machine description use support
- routines found in `gensupport.c', `errors.c', and `read-rtl.c'.
-
- * Several passes refer to the header file `insn-config.h' which
- contains a few parameters (C macro definitions) generated
- automatically from the machine description RTL by the tool
- `genconfig'.
-
- * Several passes use the instruction recognizer, which consists of
- `recog.c' and `recog.h', plus the files `insn-recog.c' and
- `insn-extract.c' that are generated automatically from the machine
- description by the tools `genrecog' and `genextract'.
-
- * Several passes use the header files `regs.h' which defines the
- information recorded about pseudo register usage, and
- `basic-block.h' which defines the information recorded about basic
- blocks.
-
- * `hard-reg-set.h' defines the type `HARD_REG_SET', a bit-vector
- with a bit for each hard register, and some macros to manipulate
- it. This type is just `int' if the machine has few enough hard
- registers; otherwise it is an array of `int' and some of the
- macros expand into loops.
-
- * Several passes use instruction attributes. A definition of the
- attributes defined for a particular machine is in file
- `insn-attr.h', which is generated from the machine description by
- the program `genattr'. The file `insn-attrtab.c' contains
- subroutines to obtain the attribute values for insns. It is
- generated from the machine description by the program `genattrtab'.
-
-\1f
-File: gccint.info, Node: Trees, Next: RTL, Prev: Passes, Up: Top
-
-Trees: The intermediate representation used by the C and C++ front ends
-***********************************************************************
-
- This chapter documents the internal representation used by GCC to
-represent C and C++ source programs. When presented with a C or C++
-source program, GCC parses the program, performs semantic analysis
-(including the generation of error messages), and then produces the
-internal representation described here. This representation contains a
-complete representation for the entire translation unit provided as
-input to the front end. This representation is then typically processed
-by a code-generator in order to produce machine code, but could also be
-used in the creation of source browsers, intelligent editors, automatic
-documentation generators, interpreters, and any other programs needing
-the ability to process C or C++ code.
-
- This chapter explains the internal representation. In particular, it
-documents the internal representation for C and C++ source constructs,
-and the macros, functions, and variables that can be used to access
-these constructs. The C++ representation is largely a superset of the
-representation used in the C front end. There is only one construct
-used in C that does not appear in the C++ front end and that is the GNU
-"nested function" extension. Many of the macros documented here do not
-apply in C because the corresponding language constructs do not appear
-in C.
-
- If you are developing a "back end", be it is a code-generator or some
-other tool, that uses this representation, you may occasionally find
-that you need to ask questions not easily answered by the functions and
-macros available here. If that situation occurs, it is quite likely
-that GCC already supports the functionality you desire, but that the
-interface is simply not documented here. In that case, you should ask
-the GCC maintainers (via mail to <gcc@gcc.gnu.org>) about documenting
-the functionality you require. Similarly, if you find yourself writing
-functions that do not deal directly with your back end, but instead
-might be useful to other people using the GCC front end, you should
-submit your patches for inclusion in GCC.
-
-* Menu:
-
-* Deficiencies:: Topics net yet covered in this document.
-* Tree overview:: All about `tree's.
-* Types:: Fundamental and aggregate types.
-* Scopes:: Namespaces and classes.
-* Functions:: Overloading, function bodies, and linkage.
-* Declarations:: Type declarations and variables.
-* Attributes:: Declaration and type attributes.
-* Expression trees:: From `typeid' to `throw'.
-
-\1f
-File: gccint.info, Node: Deficiencies, Next: Tree overview, Up: Trees
-
-Deficiencies
-============
-
- There are many places in which this document is incomplet and
-incorrekt. It is, as of yet, only _preliminary_ documentation.
-
-\1f
-File: gccint.info, Node: Tree overview, Next: Types, Prev: Deficiencies, Up: Trees
-
-Overview
-========
-
- The central data structure used by the internal representation is the
-`tree'. These nodes, while all of the C type `tree', are of many
-varieties. A `tree' is a pointer type, but the object to which it
-points may be of a variety of types. From this point forward, we will
-refer to trees in ordinary type, rather than in `this font', except
-when talking about the actual C type `tree'.
-
- You can tell what kind of node a particular tree is by using the
-`TREE_CODE' macro. Many, many macros take a trees as input and return
-trees as output. However, most macros require a certain kinds of tree
-node as input. In other words, there is a type-system for trees, but
-it is not reflected in the C type-system.
-
- For safety, it is useful to configure GCC with `--enable-checking'.
-Although this results in a significant performance penalty (since all
-tree types are checked at run-time), and is therefore inappropriate in a
-release version, it is extremely helpful during the development process.
-
- Many macros behave as predicates. Many, although not all, of these
-predicates end in `_P'. Do not rely on the result type of these macros
-being of any particular type. You may, however, rely on the fact that
-the type can be compared to `0', so that statements like
- if (TEST_P (t) && !TEST_P (y))
- x = 1;
-
-and
- int i = (TEST_P (t) != 0);
-
-are legal. Macros that return `int' values now may be changed to
-return `tree' values, or other pointers in the future. Even those that
-continue to return `int' may return multiple nonzero codes where
-previously they returned only zero and one. Therefore, you should not
-write code like
- if (TEST_P (t) == 1)
-
-as this code is not guaranteed to work correctly in the future.
-
- You should not take the address of values returned by the macros or
-functions described here. In particular, no guarantee is given that the
-values are lvalues.
-
- In general, the names of macros are all in uppercase, while the
-names of functions are entirely in lower case. There are rare
-exceptions to this rule. You should assume that any macro or function
-whose name is made up entirely of uppercase letters may evaluate its
-arguments more than once. You may assume that a macro or function
-whose name is made up entirely of lowercase letters will evaluate its
-arguments only once.
-
- The `error_mark_node' is a special tree. Its tree code is
-`ERROR_MARK', but since there is only ever one node with that code, the
-usual practice is to compare the tree against `error_mark_node'. (This
-test is just a test for pointer equality.) If an error has occurred
-during front-end processing the flag `errorcount' will be set. If the
-front end has encountered code it cannot handle, it will issue a
-message to the user and set `sorrycount'. When these flags are set,
-any macro or function which normally returns a tree of a particular
-kind may instead return the `error_mark_node'. Thus, if you intend to
-do any processing of erroneous code, you must be prepared to deal with
-the `error_mark_node'.
-
- Occasionally, a particular tree slot (like an operand to an
-expression, or a particular field in a declaration) will be referred to
-as "reserved for the back end." These slots are used to store RTL when
-the tree is converted to RTL for use by the GCC back end. However, if
-that process is not taking place (e.g., if the front end is being hooked
-up to an intelligent editor), then those slots may be used by the back
-end presently in use.
-
- If you encounter situations that do not match this documentation,
-such as tree nodes of types not mentioned here, or macros documented to
-return entities of a particular kind that instead return entities of
-some different kind, you have found a bug, either in the front end or in
-the documentation. Please report these bugs as you would any other bug.
-
-* Menu:
-
-* Macros and Functions::Macros and functions that can be used with all trees.
-* Identifiers:: The names of things.
-* Containers:: Lists and vectors.
-
-\1f
-File: gccint.info, Node: Macros and Functions, Next: Identifiers, Up: Tree overview
-
-Trees
------
-
- This section is not here yet.
-
-\1f
-File: gccint.info, Node: Identifiers, Next: Containers, Prev: Macros and Functions, Up: Tree overview
-
-Identifiers
------------
-
- An `IDENTIFIER_NODE' represents a slightly more general concept that
-the standard C or C++ concept of identifier. In particular, an
-`IDENTIFIER_NODE' may contain a `$', or other extraordinary characters.
-
- There are never two distinct `IDENTIFIER_NODE's representing the
-same identifier. Therefore, you may use pointer equality to compare
-`IDENTIFIER_NODE's, rather than using a routine like `strcmp'.
-
- You can use the following macros to access identifiers:
-`IDENTIFIER_POINTER'
- The string represented by the identifier, represented as a
- `char*'. This string is always `NUL'-terminated, and contains no
- embedded `NUL' characters.
-
-`IDENTIFIER_LENGTH'
- The length of the string returned by `IDENTIFIER_POINTER', not
- including the trailing `NUL'. This value of `IDENTIFIER_LENGTH
- (x)' is always the same as `strlen (IDENTIFIER_POINTER (x))'.
-
-`IDENTIFIER_OPNAME_P'
- This predicate holds if the identifier represents the name of an
- overloaded operator. In this case, you should not depend on the
- contents of either the `IDENTIFIER_POINTER' or the
- `IDENTIFIER_LENGTH'.
-
-`IDENTIFIER_TYPENAME_P'
- This predicate holds if the identifier represents the name of a
- user-defined conversion operator. In this case, the `TREE_TYPE' of
- the `IDENTIFIER_NODE' holds the type to which the conversion
- operator converts.
-
-
-\1f
-File: gccint.info, Node: Containers, Prev: Identifiers, Up: Tree overview
-
-Containers
-----------
-
- Two common container data structures can be represented directly with
-tree nodes. A `TREE_LIST' is a singly linked list containing two trees
-per node. These are the `TREE_PURPOSE' and `TREE_VALUE' of each node.
-(Often, the `TREE_PURPOSE' contains some kind of tag, or additional
-information, while the `TREE_VALUE' contains the majority of the
-payload. In other cases, the `TREE_PURPOSE' is simply `NULL_TREE',
-while in still others both the `TREE_PURPOSE' and `TREE_VALUE' are of
-equal stature.) Given one `TREE_LIST' node, the next node is found by
-following the `TREE_CHAIN'. If the `TREE_CHAIN' is `NULL_TREE', then
-you have reached the end of the list.
-
- A `TREE_VEC' is a simple vector. The `TREE_VEC_LENGTH' is an
-integer (not a tree) giving the number of nodes in the vector. The
-nodes themselves are accessed using the `TREE_VEC_ELT' macro, which
-takes two arguments. The first is the `TREE_VEC' in question; the
-second is an integer indicating which element in the vector is desired.
-The elements are indexed from zero.
-
projects / msp430-gcc.git / blobdiff