-This is doc/gccint.info, produced by makeinfo version 4.5 from
+This is doc/gccint.info, produced by makeinfo version 4.11 from
doc/gccint.texi.
INFO-DIR-SECTION Programming
Introduction
************
- This manual documents the internals of the GNU compilers, including
-how to port them to new targets and some information about how to write
+This manual documents the internals of the GNU compilers, including how
+to port them to new targets and some information about how to write
front ends for new languages. It corresponds to GCC version 3.2.3.
The use of the GNU compilers is documented in a separate manual. *Note
Introduction: (gcc)Top.
\1f
File: gccint.info, Node: Contributing, Next: Portability, Prev: Top, Up: Top
-Contributing to GCC Development
-*******************************
+1 Contributing to GCC Development
+*********************************
- If you would like to help pretest GCC releases to assure they work
-well, our current development sources are available by CVS (see
+If you would like to help pretest GCC releases to assure they work well,
+our current development sources are available by CVS (see
`http://gcc.gnu.org/cvs.html'). Source and binary snapshots are also
available for FTP; see `http://gcc.gnu.org/snapshots.html'.
\1f
File: gccint.info, Node: Portability, Next: Interface, Prev: Contributing, Up: Top
-GCC and Portability
-*******************
+2 GCC and Portability
+*********************
- The main goal of GCC was to make a good, fast compiler for machines
-in the class that the GNU system aims to run on: 32-bit machines that
+The main goal of GCC was to make a good, fast compiler for machines in
+the class that the GNU system aims to run on: 32-bit machines that
address 8-bit bytes and have several general registers. Elegance,
theoretical power and simplicity are only secondary.
\1f
File: gccint.info, Node: Interface, Next: Languages, Prev: Portability, Up: Top
-Interfacing to GCC Output
-*************************
+3 Interfacing to GCC Output
+***************************
- GCC is normally configured to use the same function calling
-convention normally in use on the target system. This is done with the
+GCC is normally configured to use the same function calling convention
+normally in use on the target system. This is done with the
machine-description macros described (*note Target Macros::).
However, returning of structure and union values is done differently
\1f
File: gccint.info, Node: Languages, Next: Source Tree, Prev: Interface, Up: Top
-Language Front Ends in GCC
-**************************
+4 Language Front Ends in GCC
+****************************
- The interface to front ends for languages in GCC, and in particular
-the `tree' structure (*note Trees::), was initially designed for C, and
+The interface to front ends for languages in GCC, and in particular the
+`tree' structure (*note Trees::), was initially designed for C, and
many aspects of it are still somewhat biased towards C and C-like
languages. It is, however, reasonably well suited to other procedural
languages, and front ends for many such languages have been written for
\1f
File: gccint.info, Node: Source Tree, Next: Passes, Prev: Languages, Up: Top
-Source Tree Structure and Build System
-**************************************
+5 Source Tree Structure and Build System
+****************************************
- This chapter describes the structure of the GCC source tree, and how
+This chapter describes the structure of the GCC source tree, and how
GCC is built. The user documentation for building and installing GCC
is in a separate manual (`http://gcc.gnu.org/install/'), with which it
is presumed that you are familiar.
\1f
File: gccint.info, Node: Configure Terms, Next: Top Level, Up: Source Tree
-Configure Terms and History
-===========================
+5.1 Configure Terms and History
+===============================
- The configure and build process has a long and colorful history, and
-can be confusing to anyone who doesn't know why things are the way they
-are. While there are other documents which describe the configuration
-process in detail, here are a few things that everyone working on GCC
-should know.
+The configure and build process has a long and colorful history, and can
+be confusing to anyone who doesn't know why things are the way they are.
+While there are other documents which describe the configuration process
+in detail, here are a few things that everyone working on GCC should
+know.
There are three system names that the build knows about: the machine
you are building on ("build"), the machine that you are building for
\1f
File: gccint.info, Node: Top Level, Next: gcc Directory, Prev: Configure Terms, Up: Source Tree
-Top Level Source Directory
-==========================
+5.2 Top Level Source Directory
+==============================
- The top level source directory in a GCC distribution contains several
+The top level source directory in a GCC distribution contains several
files and directories that are shared with other software distributions
such as that of GNU Binutils. It also contains several subdirectories
that contain parts of GCC and its runtime libraries:
\1f
File: gccint.info, Node: gcc Directory, Next: Test Suites, Prev: Top Level, Up: Source Tree
-The `gcc' Subdirectory
-======================
+5.3 The `gcc' Subdirectory
+==========================
- The `gcc' directory contains many files that are part of the C
-sources of GCC, other files used as part of the configuration and build
+The `gcc' directory contains many files that are part of the C sources
+of GCC, other files used as part of the configuration and build
process, and subdirectories including documentation and a test suite.
The files that are sources of GCC are documented in a separate chapter.
*Note Passes and Files of the Compiler: Passes.
\1f
File: gccint.info, Node: Subdirectories, Next: Configuration, Up: gcc Directory
-Subdirectories of `gcc'
------------------------
+5.3.1 Subdirectories of `gcc'
+-----------------------------
- The `gcc' directory contains the following subdirectories:
+The `gcc' directory contains the following subdirectories:
`LANGUAGE'
Subdirectories for various languages. Directories containing a
\1f
File: gccint.info, Node: Configuration, Next: Build, Prev: Subdirectories, Up: gcc Directory
-Configuration in the `gcc' Directory
-------------------------------------
+5.3.2 Configuration in the `gcc' Directory
+------------------------------------------
- The `gcc' directory is configured with an Autoconf-generated script
+The `gcc' directory is configured with an Autoconf-generated script
`configure'. The `configure' script is generated from `configure.in'
and `aclocal.m4'. From the files `configure.in' and `acconfig.h',
Autoheader generates the file `config.in'. The file `cstamp-h.in' is
\1f
File: gccint.info, Node: Config Fragments, Next: System Config, Up: Configuration
-Scripts Used by `configure'
-...........................
+5.3.2.1 Scripts Used by `configure'
+...................................
- `configure' uses some other scripts to help in its work:
+`configure' uses some other scripts to help in its work:
* The standard GNU `config.sub' and `config.guess' files, kept in
the top level directory, are used. FIXME: when is the
\1f
File: gccint.info, Node: System Config, Next: Configuration Files, Prev: Config Fragments, Up: Configuration
-The `config.gcc' File
-.....................
+5.3.2.2 The `config.gcc' File
+.............................
- FIXME: document the contents of this file, and what variables should
-be set to control build, host and target configuration.
+FIXME: document the contents of this file, and what variables should be
+set to control build, host and target configuration.
\1f
File: gccint.info, Node: Configuration Files, Prev: System Config, Up: Configuration
-Files Created by `configure'
-............................
+5.3.2.3 Files Created by `configure'
+....................................
- Here we spell out what files will be set up by `configure' in the
-`gcc' directory. Some other files are created as temporary files in
-the configuration process, and are not used in the subsequent build;
-these are not documented.
+Here we spell out what files will be set up by `configure' in the `gcc'
+directory. Some other files are created as temporary files in the
+configuration process, and are not used in the subsequent build; these
+are not documented.
* `Makefile' is constructed from `Makefile.in', together with the
host and target fragments (*note Makefile Fragments: Fragments.)
\1f
File: gccint.info, Node: Build, Next: Makefile, Prev: Configuration, Up: gcc Directory
-Build System in the `gcc' Directory
------------------------------------
+5.3.3 Build System in the `gcc' Directory
+-----------------------------------------
- FIXME: describe the build system, including what is built in what
+FIXME: describe the build system, including what is built in what
stages. Also list the various source files that are used in the build
process but aren't source files of GCC itself and so aren't documented
below (*note Passes::).
\1f
File: gccint.info, Node: Makefile, Next: Library Files, Prev: Build, Up: gcc Directory
-Makefile Targets
-----------------
+5.3.4 Makefile Targets
+----------------------
`all'
This is the default target. Depending on what your
\1f
File: gccint.info, Node: Library Files, Next: Headers, Prev: Makefile, Up: gcc Directory
-Library Source Files and Headers under the `gcc' Directory
-----------------------------------------------------------
+5.3.5 Library Source Files and Headers under the `gcc' Directory
+----------------------------------------------------------------
- FIXME: list here, with explanation, all the C source files and
-headers under the `gcc' directory that aren't built into the GCC
-executable but rather are part of runtime libraries and object files,
-such as `crtstuff.c' and `unwind-dw2.c'. *Note Headers Installed by
-GCC: Headers, for more information about the `ginclude' directory.
+FIXME: list here, with explanation, all the C source files and headers
+under the `gcc' directory that aren't built into the GCC executable but
+rather are part of runtime libraries and object files, such as
+`crtstuff.c' and `unwind-dw2.c'. *Note Headers Installed by GCC:
+Headers, for more information about the `ginclude' directory.
\1f
File: gccint.info, Node: Headers, Next: Documentation, Prev: Library Files, Up: gcc Directory
-Headers Installed by GCC
-------------------------
+5.3.6 Headers Installed by GCC
+------------------------------
- In general, GCC expects the system C library to provide most of the
+In general, GCC expects the system C library to provide most of the
headers to be used with it. However, GCC will fix those headers if
necessary to make them work with GCC, and will install some headers
required of freestanding implementations. These headers are installed
\1f
File: gccint.info, Node: Documentation, Next: Front End, Prev: Headers, Up: gcc Directory
-Building Documentation
-----------------------
+5.3.7 Building Documentation
+----------------------------
- The main GCC documentation is in the form of manuals in Texinfo
-format. These are installed in Info format, and DVI versions may be
-generated by `make dvi'. In addition, some man pages are generated
-from the Texinfo manuals, there are some other text files with
-miscellaneous documentation, and runtime libraries have their own
-documentation outside the `gcc' directory. FIXME: document the
-documentation for runtime libraries somewhere.
+The main GCC documentation is in the form of manuals in Texinfo format.
+These are installed in Info format, and DVI versions may be generated
+by `make dvi'. In addition, some man pages are generated from the
+Texinfo manuals, there are some other text files with miscellaneous
+documentation, and runtime libraries have their own documentation
+outside the `gcc' directory. FIXME: document the documentation for
+runtime libraries somewhere.
* Menu:
\1f
File: gccint.info, Node: Texinfo Manuals, Next: Man Page Generation, Up: Documentation
-Texinfo Manuals
-...............
+5.3.7.1 Texinfo Manuals
+.......................
- The manuals for GCC as a whole, and the C and C++ front ends, are in
+The manuals for GCC as a whole, and the C and C++ front ends, are in
files `doc/*.texi'. Other front ends have their own manuals in files
`LANGUAGE/*.texi'. Common files `doc/include/*.texi' are provided
which may be included in multiple manuals; the following files are in
\1f
File: gccint.info, Node: Man Page Generation, Next: Miscellaneous Docs, Prev: Texinfo Manuals, Up: Documentation
-Man Page Generation
-...................
+5.3.7.2 Man Page Generation
+...........................
- Because of user demand, in addition to full Texinfo manuals, man
-pages are provided which contain extracts from those manuals. These man
+Because of user demand, in addition to full Texinfo manuals, man pages
+are provided which contain extracts from those manuals. These man
pages are generated from the Texinfo manuals using
`contrib/texi2pod.pl' and `pod2man'. (The man page for `g++',
`cp/g++.1', just contains a `.so' reference to `gcc.1', but all the
\1f
File: gccint.info, Node: Miscellaneous Docs, Prev: Man Page Generation, Up: Documentation
-Miscellaneous Documentation
-...........................
+5.3.7.3 Miscellaneous Documentation
+...................................
- In addition to the formal documentation that is installed by GCC,
-there are several other text files with miscellaneous documentation:
+In addition to the formal documentation that is installed by GCC, there
+are several other text files with miscellaneous documentation:
`ABOUT-GCC-NLS'
Notes on GCC's Native Language Support. FIXME: this should be
\1f
File: gccint.info, Node: Front End, Next: Back End, Prev: Documentation, Up: gcc Directory
-Anatomy of a Language Front End
--------------------------------
+5.3.8 Anatomy of a Language Front End
+-------------------------------------
- A front end for a language in GCC has the following parts:
+A front end for a language in GCC has the following parts:
* A directory `LANGUAGE' under `gcc' containing source files for
that front end. *Note The Front End `LANGUAGE' Directory: Front
\1f
File: gccint.info, Node: Front End Directory, Next: Front End Config, Up: Front End
-The Front End `LANGUAGE' Directory
-..................................
+5.3.8.1 The Front End `LANGUAGE' Directory
+..........................................
- A front end `LANGUAGE' directory contains the source files of that
+A front end `LANGUAGE' directory contains the source files of that
front end (but not of any runtime libraries, which should be outside
the `gcc' directory). This includes documentation, and possibly some
subsidiary programs build alongside the front end. Certain files are
\1f
File: gccint.info, Node: Front End Config, Prev: Front End Directory, Up: Front End
-The Front End `config-lang.in' File
-...................................
+5.3.8.2 The Front End `config-lang.in' File
+...........................................
- Each language subdirectory contains a `config-lang.in' file. This
-file is a shell script that may define some variables describing the
+Each language subdirectory contains a `config-lang.in' file. This file
+is a shell script that may define some variables describing the
language:
`language'
`LANGUAGE/Makefile.in', but this is deprecated, building
everything from the single `gcc/Makefile' is preferred.
+\1f
+File: gccint.info, Node: Back End, Prev: Front End, Up: gcc Directory
+
+5.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'.
+
+ * 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
+
+5.4 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
+
+5.4.1 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
+
+5.4.2 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
+
+5.4.3 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
+
+6 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
+
+7 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
+
+7.1 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
+
+7.2 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
+
+7.2.1 Trees
+-----------
+
+This section is not here yet.
+
+\1f
+File: gccint.info, Node: Identifiers, Next: Containers, Prev: Macros and Functions, Up: Tree overview
+
+7.2.2 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
+
+7.2.3 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.
+
+\1f
+File: gccint.info, Node: Types, Next: Scopes, Prev: Tree overview, Up: Trees
+
+7.3 Types
+=========
+
+All types have corresponding tree nodes. However, you should not assume
+that there is exactly one tree node corresponding to each type. There
+are often several nodes each of which correspond to the same type.
+
+ For the most part, different kinds of types have different tree
+codes. (For example, pointer types use a `POINTER_TYPE' code while
+arrays use an `ARRAY_TYPE' code.) However, pointers to member functions
+use the `RECORD_TYPE' code. Therefore, when writing a `switch'
+statement that depends on the code associated with a particular type,
+you should take care to handle pointers to member functions under the
+`RECORD_TYPE' case label.
+
+ In C++, an array type is not qualified; rather the type of the array
+elements is qualified. This situation is reflected in the intermediate
+representation. The macros described here will always examine the
+qualification of the underlying element type when applied to an array
+type. (If the element type is itself an array, then the recursion
+continues until a non-array type is found, and the qualification of this
+type is examined.) So, for example, `CP_TYPE_CONST_P' will hold of the
+type `const int ()[7]', denoting an array of seven `int's.
+
+ The following functions and macros deal with cv-qualification of
+types:
+`CP_TYPE_QUALS'
+ This macro returns the set of type qualifiers applied to this type.
+ This value is `TYPE_UNQUALIFIED' if no qualifiers have been
+ applied. The `TYPE_QUAL_CONST' bit is set if the type is
+ `const'-qualified. The `TYPE_QUAL_VOLATILE' bit is set if the
+ type is `volatile'-qualified. The `TYPE_QUAL_RESTRICT' bit is set
+ if the type is `restrict'-qualified.
+
+`CP_TYPE_CONST_P'
+ This macro holds if the type is `const'-qualified.
+
+`CP_TYPE_VOLATILE_P'
+ This macro holds if the type is `volatile'-qualified.
+
+`CP_TYPE_RESTRICT_P'
+ This macro holds if the type is `restrict'-qualified.
+
+`CP_TYPE_CONST_NON_VOLATILE_P'
+ This predicate holds for a type that is `const'-qualified, but
+ _not_ `volatile'-qualified; other cv-qualifiers are ignored as
+ well: only the `const'-ness is tested.
+
+`TYPE_MAIN_VARIANT'
+ This macro returns the unqualified version of a type. It may be
+ applied to an unqualified type, but it is not always the identity
+ function in that case.
+
+ A few other macros and functions are usable with all types:
+`TYPE_SIZE'
+ The number of bits required to represent the type, represented as
+ an `INTEGER_CST'. For an incomplete type, `TYPE_SIZE' will be
+ `NULL_TREE'.
+
+`TYPE_ALIGN'
+ The alignment of the type, in bits, represented as an `int'.
+
+`TYPE_NAME'
+ This macro returns a declaration (in the form of a `TYPE_DECL') for
+ the type. (Note this macro does _not_ return a `IDENTIFIER_NODE',
+ as you might expect, given its name!) You can look at the
+ `DECL_NAME' of the `TYPE_DECL' to obtain the actual name of the
+ type. The `TYPE_NAME' will be `NULL_TREE' for a type that is not
+ a built-in type, the result of a typedef, or a named class type.
+
+`CP_INTEGRAL_TYPE'
+ This predicate holds if the type is an integral type. Notice that
+ in C++, enumerations are _not_ integral types.
+
+`ARITHMETIC_TYPE_P'
+ This predicate holds if the type is an integral type (in the C++
+ sense) or a floating point type.
+
+`CLASS_TYPE_P'
+ This predicate holds for a class-type.
+
+`TYPE_BUILT_IN'
+ This predicate holds for a built-in type.
+
+`TYPE_PTRMEM_P'
+ This predicate holds if the type is a pointer to data member.
+
+`TYPE_PTR_P'
+ This predicate holds if the type is a pointer type, and the
+ pointee is not a data member.
+
+`TYPE_PTRFN_P'
+ This predicate holds for a pointer to function type.
+
+`TYPE_PTROB_P'
+ This predicate holds for a pointer to object type. Note however
+ that it does not hold for the generic pointer to object type `void
+ *'. You may use `TYPE_PTROBV_P' to test for a pointer to object
+ type as well as `void *'.
+
+`same_type_p'
+ This predicate takes two types as input, and holds if they are the
+ same type. For example, if one type is a `typedef' for the other,
+ or both are `typedef's for the same type. This predicate also
+ holds if the two trees given as input are simply copies of one
+ another; i.e., there is no difference between them at the source
+ level, but, for whatever reason, a duplicate has been made in the
+ representation. You should never use `==' (pointer equality) to
+ compare types; always use `same_type_p' instead.
+
+ Detailed below are the various kinds of types, and the macros that
+can be used to access them. Although other kinds of types are used
+elsewhere in G++, the types described here are the only ones that you
+will encounter while examining the intermediate representation.
+
+`VOID_TYPE'
+ Used to represent the `void' type.
+
+`INTEGER_TYPE'
+ Used to represent the various integral types, including `char',
+ `short', `int', `long', and `long long'. This code is not used
+ for enumeration types, nor for the `bool' type. Note that GCC's
+ `CHAR_TYPE' node is _not_ used to represent `char'. The
+ `TYPE_PRECISION' is the number of bits used in the representation,
+ represented as an `unsigned int'. (Note that in the general case
+ this is not the same value as `TYPE_SIZE'; suppose that there were
+ a 24-bit integer type, but that alignment requirements for the ABI
+ required 32-bit alignment. Then, `TYPE_SIZE' would be an
+ `INTEGER_CST' for 32, while `TYPE_PRECISION' would be 24.) The
+ integer type is unsigned if `TREE_UNSIGNED' holds; otherwise, it
+ is signed.
+
+ The `TYPE_MIN_VALUE' is an `INTEGER_CST' for the smallest integer
+ that may be represented by this type. Similarly, the
+ `TYPE_MAX_VALUE' is an `INTEGER_CST' for the largest integer that
+ may be represented by this type.
+
+`REAL_TYPE'
+ Used to represent the `float', `double', and `long double' types.
+ The number of bits in the floating-point representation is given
+ by `TYPE_PRECISION', as in the `INTEGER_TYPE' case.
+
+`COMPLEX_TYPE'
+ Used to represent GCC built-in `__complex__' data types. The
+ `TREE_TYPE' is the type of the real and imaginary parts.
+
+`ENUMERAL_TYPE'
+ Used to represent an enumeration type. The `TYPE_PRECISION' gives
+ (as an `int'), the number of bits used to represent the type. If
+ there are no negative enumeration constants, `TREE_UNSIGNED' will
+ hold. The minimum and maximum enumeration constants may be
+ obtained with `TYPE_MIN_VALUE' and `TYPE_MAX_VALUE', respectively;
+ each of these macros returns an `INTEGER_CST'.
+
+ The actual enumeration constants themselves may be obtained by
+ looking at the `TYPE_VALUES'. This macro will return a
+ `TREE_LIST', containing the constants. The `TREE_PURPOSE' of each
+ node will be an `IDENTIFIER_NODE' giving the name of the constant;
+ the `TREE_VALUE' will be an `INTEGER_CST' giving the value
+ assigned to that constant. These constants will appear in the
+ order in which they were declared. The `TREE_TYPE' of each of
+ these constants will be the type of enumeration type itself.
+
+`BOOLEAN_TYPE'
+ Used to represent the `bool' type.
+
+`POINTER_TYPE'
+ Used to represent pointer types, and pointer to data member types.
+ The `TREE_TYPE' gives the type to which this type points. If the
+ type is a pointer to data member type, then `TYPE_PTRMEM_P' will
+ hold. For a pointer to data member type of the form `T X::*',
+ `TYPE_PTRMEM_CLASS_TYPE' will be the type `X', while
+ `TYPE_PTRMEM_POINTED_TO_TYPE' will be the type `T'.
+
+`REFERENCE_TYPE'
+ Used to represent reference types. The `TREE_TYPE' gives the type
+ to which this type refers.
+
+`FUNCTION_TYPE'
+ Used to represent the type of non-member functions and of static
+ member functions. The `TREE_TYPE' gives the return type of the
+ function. The `TYPE_ARG_TYPES' are a `TREE_LIST' of the argument
+ types. The `TREE_VALUE' of each node in this list is the type of
+ the corresponding argument; the `TREE_PURPOSE' is an expression
+ for the default argument value, if any. If the last node in the
+ list is `void_list_node' (a `TREE_LIST' node whose `TREE_VALUE' is
+ the `void_type_node'), then functions of this type do not take
+ variable arguments. Otherwise, they do take a variable number of
+ arguments.
+
+ Note that in C (but not in C++) a function declared like `void f()'
+ is an unprototyped function taking a variable number of arguments;
+ the `TYPE_ARG_TYPES' of such a function will be `NULL'.
+
+`METHOD_TYPE'
+ Used to represent the type of a non-static member function. Like a
+ `FUNCTION_TYPE', the return type is given by the `TREE_TYPE'. The
+ type of `*this', i.e., the class of which functions of this type
+ are a member, is given by the `TYPE_METHOD_BASETYPE'. The
+ `TYPE_ARG_TYPES' is the parameter list, as for a `FUNCTION_TYPE',
+ and includes the `this' argument.
+
+`ARRAY_TYPE'
+ Used to represent array types. The `TREE_TYPE' gives the type of
+ the elements in the array. If the array-bound is present in the
+ type, the `TYPE_DOMAIN' is an `INTEGER_TYPE' whose
+ `TYPE_MIN_VALUE' and `TYPE_MAX_VALUE' will be the lower and upper
+ bounds of the array, respectively. The `TYPE_MIN_VALUE' will
+ always be an `INTEGER_CST' for zero, while the `TYPE_MAX_VALUE'
+ will be one less than the number of elements in the array, i.e.,
+ the highest value which may be used to index an element in the
+ array.
+
+`RECORD_TYPE'
+ Used to represent `struct' and `class' types, as well as pointers
+ to member functions and similar constructs in other languages.
+ `TYPE_FIELDS' contains the items contained in this type, each of
+ which can be a `FIELD_DECL', `VAR_DECL', `CONST_DECL', or
+ `TYPE_DECL'. You may not make any assumptions about the ordering
+ of the fields in the type or whether one or more of them overlap.
+ If `TYPE_PTRMEMFUNC_P' holds, then this type is a pointer-to-member
+ type. In that case, the `TYPE_PTRMEMFUNC_FN_TYPE' is a
+ `POINTER_TYPE' pointing to a `METHOD_TYPE'. The `METHOD_TYPE' is
+ the type of a function pointed to by the pointer-to-member
+ function. If `TYPE_PTRMEMFUNC_P' does not hold, this type is a
+ class type. For more information, see *note Classes::.
+
+`UNION_TYPE'
+ Used to represent `union' types. Similar to `RECORD_TYPE' except
+ that all `FIELD_DECL' nodes in `TYPE_FIELD' start at bit position
+ zero.
+
+`QUAL_UNION_TYPE'
+ Used to represent part of a variant record in Ada. Similar to
+ `UNION_TYPE' except that each `FIELD_DECL' has a `DECL_QUALIFIER'
+ field, which contains a boolean expression that indicates whether
+ the field is present in the object. The type will only have one
+ field, so each field's `DECL_QUALIFIER' is only evaluated if none
+ of the expressions in the previous fields in `TYPE_FIELDS' are
+ nonzero. Normally these expressions will reference a field in the
+ outer object using a `PLACEHOLDER_EXPR'.
+
+`UNKNOWN_TYPE'
+ This node is used to represent a type the knowledge of which is
+ insufficient for a sound processing.
+
+`OFFSET_TYPE'
+ This node is used to represent a data member; for example a
+ pointer-to-data-member is represented by a `POINTER_TYPE' whose
+ `TREE_TYPE' is an `OFFSET_TYPE'. For a data member `X::m' the
+ `TYPE_OFFSET_BASETYPE' is `X' and the `TREE_TYPE' is the type of
+ `m'.
+
+`TYPENAME_TYPE'
+ Used to represent a construct of the form `typename T::A'. The
+ `TYPE_CONTEXT' is `T'; the `TYPE_NAME' is an `IDENTIFIER_NODE' for
+ `A'. If the type is specified via a template-id, then
+ `TYPENAME_TYPE_FULLNAME' yields a `TEMPLATE_ID_EXPR'. The
+ `TREE_TYPE' is non-`NULL' if the node is implicitly generated in
+ support for the implicit typename extension; in which case the
+ `TREE_TYPE' is a type node for the base-class.
+
+`TYPEOF_TYPE'
+ Used to represent the `__typeof__' extension. The `TYPE_FIELDS'
+ is the expression the type of which is being represented.
+
+ There are variables whose values represent some of the basic types.
+These include:
+`void_type_node'
+ A node for `void'.
+
+`integer_type_node'
+ A node for `int'.
+
+`unsigned_type_node.'
+ A node for `unsigned int'.
+
+`char_type_node.'
+ A node for `char'.
+ It may sometimes be useful to compare one of these variables with a
+type in hand, using `same_type_p'.
+
+\1f
+File: gccint.info, Node: Scopes, Next: Functions, Prev: Types, Up: Trees
+
+7.4 Scopes
+==========
+
+The root of the entire intermediate representation is the variable
+`global_namespace'. This is the namespace specified with `::' in C++
+source code. All other namespaces, types, variables, functions, and so
+forth can be found starting with this namespace.
+
+ Besides namespaces, the other high-level scoping construct in C++ is
+the class. (Throughout this manual the term "class" is used to mean the
+types referred to in the ANSI/ISO C++ Standard as classes; these include
+types defined with the `class', `struct', and `union' keywords.)
+
+* Menu:
+
+* Namespaces:: Member functions, types, etc.
+* Classes:: Members, bases, friends, etc.
+
+\1f
+File: gccint.info, Node: Namespaces, Next: Classes, Up: Scopes
+
+7.4.1 Namespaces
+----------------
+
+A namespace is represented by a `NAMESPACE_DECL' node.
+
+ However, except for the fact that it is distinguished as the root of
+the representation, the global namespace is no different from any other
+namespace. Thus, in what follows, we describe namespaces generally,
+rather than the global namespace in particular.
+
+ The following macros and functions can be used on a `NAMESPACE_DECL':
+
+`DECL_NAME'
+ This macro is used to obtain the `IDENTIFIER_NODE' corresponding to
+ the unqualified name of the name of the namespace (*note
+ Identifiers::). The name of the global namespace is `::', even
+ though in C++ the global namespace is unnamed. However, you
+ should use comparison with `global_namespace', rather than
+ `DECL_NAME' to determine whether or not a namespaces is the global
+ one. An unnamed namespace will have a `DECL_NAME' equal to
+ `anonymous_namespace_name'. Within a single translation unit, all
+ unnamed namespaces will have the same name.
+
+`DECL_CONTEXT'
+ This macro returns the enclosing namespace. The `DECL_CONTEXT' for
+ the `global_namespace' is `NULL_TREE'.
+
+`DECL_NAMESPACE_ALIAS'
+ If this declaration is for a namespace alias, then
+ `DECL_NAMESPACE_ALIAS' is the namespace for which this one is an
+ alias.
+
+ Do not attempt to use `cp_namespace_decls' for a namespace which is
+ an alias. Instead, follow `DECL_NAMESPACE_ALIAS' links until you
+ reach an ordinary, non-alias, namespace, and call
+ `cp_namespace_decls' there.
+
+`DECL_NAMESPACE_STD_P'
+ This predicate holds if the namespace is the special `::std'
+ namespace.
+
+`cp_namespace_decls'
+ This function will return the declarations contained in the
+ namespace, including types, overloaded functions, other
+ namespaces, and so forth. If there are no declarations, this
+ function will return `NULL_TREE'. The declarations are connected
+ through their `TREE_CHAIN' fields.
+
+ Although most entries on this list will be declarations,
+ `TREE_LIST' nodes may also appear. In this case, the `TREE_VALUE'
+ will be an `OVERLOAD'. The value of the `TREE_PURPOSE' is
+ unspecified; back ends should ignore this value. As with the
+ other kinds of declarations returned by `cp_namespace_decls', the
+ `TREE_CHAIN' will point to the next declaration in this list.
+
+ For more information on the kinds of declarations that can occur
+ on this list, *Note Declarations::. Some declarations will not
+ appear on this list. In particular, no `FIELD_DECL',
+ `LABEL_DECL', or `PARM_DECL' nodes will appear here.
+
+ This function cannot be used with namespaces that have
+ `DECL_NAMESPACE_ALIAS' set.
+
+
+\1f
+File: gccint.info, Node: Classes, Prev: Namespaces, Up: Scopes
+
+7.4.2 Classes
+-------------
+
+A class type is represented by either a `RECORD_TYPE' or a
+`UNION_TYPE'. A class declared with the `union' tag is represented by
+a `UNION_TYPE', while classes declared with either the `struct' or the
+`class' tag are represented by `RECORD_TYPE's. You can use the
+`CLASSTYPE_DECLARED_CLASS' macro to discern whether or not a particular
+type is a `class' as opposed to a `struct'. This macro will be true
+only for classes declared with the `class' tag.
+
+ Almost all non-function members are available on the `TYPE_FIELDS'
+list. Given one member, the next can be found by following the
+`TREE_CHAIN'. You should not depend in any way on the order in which
+fields appear on this list. All nodes on this list will be `DECL'
+nodes. A `FIELD_DECL' is used to represent a non-static data member, a
+`VAR_DECL' is used to represent a static data member, and a `TYPE_DECL'
+is used to represent a type. Note that the `CONST_DECL' for an
+enumeration constant will appear on this list, if the enumeration type
+was declared in the class. (Of course, the `TYPE_DECL' for the
+enumeration type will appear here as well.) There are no entries for
+base classes on this list. In particular, there is no `FIELD_DECL' for
+the "base-class portion" of an object.
+
+ The `TYPE_VFIELD' is a compiler-generated field used to point to
+virtual function tables. It may or may not appear on the `TYPE_FIELDS'
+list. However, back ends should handle the `TYPE_VFIELD' just like all
+the entries on the `TYPE_FIELDS' list.
+
+ The function members are available on the `TYPE_METHODS' list.
+Again, subsequent members are found by following the `TREE_CHAIN'
+field. If a function is overloaded, each of the overloaded functions
+appears; no `OVERLOAD' nodes appear on the `TYPE_METHODS' list.
+Implicitly declared functions (including default constructors, copy
+constructors, assignment operators, and destructors) will appear on
+this list as well.
+
+ Every class has an associated "binfo", which can be obtained with
+`TYPE_BINFO'. Binfos are used to represent base-classes. The binfo
+given by `TYPE_BINFO' is the degenerate case, whereby every class is
+considered to be its own base-class. The base classes for a particular
+binfo can be obtained with `BINFO_BASETYPES'. These base-classes are
+themselves binfos. The class type associated with a binfo is given by
+`BINFO_TYPE'. It is always the case that `BINFO_TYPE (TYPE_BINFO (x))'
+is the same type as `x', up to qualifiers. However, it is not always
+the case that `TYPE_BINFO (BINFO_TYPE (y))' is always the same binfo as
+`y'. The reason is that if `y' is a binfo representing a base-class
+`B' of a derived class `D', then `BINFO_TYPE (y)' will be `B', and
+`TYPE_BINFO (BINFO_TYPE (y))' will be `B' as its own base-class, rather
+than as a base-class of `D'.
+
+ The `BINFO_BASETYPES' is a `TREE_VEC' (*note Containers::). Base
+types appear in left-to-right order in this vector. You can tell
+whether or `public', `protected', or `private' inheritance was used by
+using the `TREE_VIA_PUBLIC', `TREE_VIA_PROTECTED', and
+`TREE_VIA_PRIVATE' macros. Each of these macros takes a `BINFO' and is
+true if and only if the indicated kind of inheritance was used. If
+`TREE_VIA_VIRTUAL' holds of a binfo, then its `BINFO_TYPE' was
+inherited from virtually.
+
+ The following macros can be used on a tree node representing a
+class-type.
+
+`LOCAL_CLASS_P'
+ This predicate holds if the class is local class _i.e._ declared
+ inside a function body.
+
+`TYPE_POLYMORPHIC_P'
+ This predicate holds if the class has at least one virtual function
+ (declared or inherited).
+
+`TYPE_HAS_DEFAULT_CONSTRUCTOR'
+ This predicate holds whenever its argument represents a class-type
+ with default constructor.
+
+`CLASSTYPE_HAS_MUTABLE'
+
+`TYPE_HAS_MUTABLE_P'
+ These predicates hold for a class-type having a mutable data
+ member.
+
+`CLASSTYPE_NON_POD_P'
+ This predicate holds only for class-types that are not PODs.
+
+`TYPE_HAS_NEW_OPERATOR'
+ This predicate holds for a class-type that defines `operator new'.
+
+`TYPE_HAS_ARRAY_NEW_OPERATOR'
+ This predicate holds for a class-type for which `operator new[]'
+ is defined.
+
+`TYPE_OVERLOADS_CALL_EXPR'
+ This predicate holds for class-type for which the function call
+ `operator()' is overloaded.
+
+`TYPE_OVERLOADS_ARRAY_REF'
+ This predicate holds for a class-type that overloads `operator[]'
+
+`TYPE_OVERLOADS_ARROW'
+ This predicate holds for a class-type for which `operator->' is
+ overloaded.
+
+
+\1f
+File: gccint.info, Node: Declarations, Next: Attributes, Prev: Functions, Up: Trees
+
+7.5 Declarations
+================
+
+This section covers the various kinds of declarations that appear in the
+internal representation, except for declarations of functions
+(represented by `FUNCTION_DECL' nodes), which are described in *note
+Functions::.
+
+ Some macros can be used with any kind of declaration. These include:
+`DECL_NAME'
+ This macro returns an `IDENTIFIER_NODE' giving the name of the
+ entity.
+
+`TREE_TYPE'
+ This macro returns the type of the entity declared.
+
+`DECL_SOURCE_FILE'
+ This macro returns the name of the file in which the entity was
+ declared, as a `char*'. For an entity declared implicitly by the
+ compiler (like `__builtin_memcpy'), this will be the string
+ `"<internal>"'.
+
+`DECL_SOURCE_LINE'
+ This macro returns the line number at which the entity was
+ declared, as an `int'.
+
+`DECL_ARTIFICIAL'
+ This predicate holds if the declaration was implicitly generated
+ by the compiler. For example, this predicate will hold of an
+ implicitly declared member function, or of the `TYPE_DECL'
+ implicitly generated for a class type. Recall that in C++ code
+ like:
+ struct S {};
+ is roughly equivalent to C code like:
+ struct S {};
+ typedef struct S S;
+ The implicitly generated `typedef' declaration is represented by a
+ `TYPE_DECL' for which `DECL_ARTIFICIAL' holds.
+
+`DECL_NAMESPACE_SCOPE_P'
+ This predicate holds if the entity was declared at a namespace
+ scope.
+
+`DECL_CLASS_SCOPE_P'
+ This predicate holds if the entity was declared at a class scope.
+
+`DECL_FUNCTION_SCOPE_P'
+ This predicate holds if the entity was declared inside a function
+ body.
+
+
+ The various kinds of declarations include:
+`LABEL_DECL'
+ These nodes are used to represent labels in function bodies. For
+ more information, see *note Functions::. These nodes only appear
+ in block scopes.
+
+`CONST_DECL'
+ These nodes are used to represent enumeration constants. The
+ value of the constant is given by `DECL_INITIAL' which will be an
+ `INTEGER_CST' with the same type as the `TREE_TYPE' of the
+ `CONST_DECL', i.e., an `ENUMERAL_TYPE'.
+
+`RESULT_DECL'
+ These nodes represent the value returned by a function. When a
+ value is assigned to a `RESULT_DECL', that indicates that the
+ value should be returned, via bitwise copy, by the function. You
+ can use `DECL_SIZE' and `DECL_ALIGN' on a `RESULT_DECL', just as
+ with a `VAR_DECL'.
+
+`TYPE_DECL'
+ These nodes represent `typedef' declarations. The `TREE_TYPE' is
+ the type declared to have the name given by `DECL_NAME'. In some
+ cases, there is no associated name.
+
+`VAR_DECL'
+ These nodes represent variables with namespace or block scope, as
+ well as static data members. The `DECL_SIZE' and `DECL_ALIGN' are
+ analogous to `TYPE_SIZE' and `TYPE_ALIGN'. For a declaration, you
+ should always use the `DECL_SIZE' and `DECL_ALIGN' rather than the
+ `TYPE_SIZE' and `TYPE_ALIGN' given by the `TREE_TYPE', since
+ special attributes may have been applied to the variable to give
+ it a particular size and alignment. You may use the predicates
+ `DECL_THIS_STATIC' or `DECL_THIS_EXTERN' to test whether the
+ storage class specifiers `static' or `extern' were used to declare
+ a variable.
+
+ If this variable is initialized (but does not require a
+ constructor), the `DECL_INITIAL' will be an expression for the
+ initializer. The initializer should be evaluated, and a bitwise
+ copy into the variable performed. If the `DECL_INITIAL' is the
+ `error_mark_node', there is an initializer, but it is given by an
+ explicit statement later in the code; no bitwise copy is required.
+
+ GCC provides an extension that allows either automatic variables,
+ or global variables, to be placed in particular registers. This
+ extension is being used for a particular `VAR_DECL' if
+ `DECL_REGISTER' holds for the `VAR_DECL', and if
+ `DECL_ASSEMBLER_NAME' is not equal to `DECL_NAME'. In that case,
+ `DECL_ASSEMBLER_NAME' is the name of the register into which the
+ variable will be placed.
+
+`PARM_DECL'
+ Used to represent a parameter to a function. Treat these nodes
+ similarly to `VAR_DECL' nodes. These nodes only appear in the
+ `DECL_ARGUMENTS' for a `FUNCTION_DECL'.
+
+ The `DECL_ARG_TYPE' for a `PARM_DECL' is the type that will
+ actually be used when a value is passed to this function. It may
+ be a wider type than the `TREE_TYPE' of the parameter; for
+ example, the ordinary type might be `short' while the
+ `DECL_ARG_TYPE' is `int'.
+
+`FIELD_DECL'
+ These nodes represent non-static data members. The `DECL_SIZE' and
+ `DECL_ALIGN' behave as for `VAR_DECL' nodes. The
+ `DECL_FIELD_BITPOS' gives the first bit used for this field, as an
+ `INTEGER_CST'. These values are indexed from zero, where zero
+ indicates the first bit in the object.
+
+ If `DECL_C_BIT_FIELD' holds, this field is a bit-field.
+
+`NAMESPACE_DECL'
+ *Note Namespaces::.
+
+`TEMPLATE_DECL'
+ These nodes are used to represent class, function, and variable
+ (static data member) templates. The
+ `DECL_TEMPLATE_SPECIALIZATIONS' are a `TREE_LIST'. The
+ `TREE_VALUE' of each node in the list is a `TEMPLATE_DECL's or
+ `FUNCTION_DECL's representing specializations (including
+ instantiations) of this template. Back ends can safely ignore
+ `TEMPLATE_DECL's, but should examine `FUNCTION_DECL' nodes on the
+ specializations list just as they would ordinary `FUNCTION_DECL'
+ nodes.
+
+ For a class template, the `DECL_TEMPLATE_INSTANTIATIONS' list
+ contains the instantiations. The `TREE_VALUE' of each node is an
+ instantiation of the class. The `DECL_TEMPLATE_SPECIALIZATIONS'
+ contains partial specializations of the class.
+
+`USING_DECL'
+ Back ends can safely ignore these nodes.
+
+
+\1f
+File: gccint.info, Node: Functions, Next: Declarations, Prev: Scopes, Up: Trees
+
+7.6 Functions
+=============
+
+A function is represented by a `FUNCTION_DECL' node. A set of
+overloaded functions is sometimes represented by a `OVERLOAD' node.
+
+ An `OVERLOAD' node is not a declaration, so none of the `DECL_'
+macros should be used on an `OVERLOAD'. An `OVERLOAD' node is similar
+to a `TREE_LIST'. Use `OVL_CURRENT' to get the function associated
+with an `OVERLOAD' node; use `OVL_NEXT' to get the next `OVERLOAD' node
+in the list of overloaded functions. The macros `OVL_CURRENT' and
+`OVL_NEXT' are actually polymorphic; you can use them to work with
+`FUNCTION_DECL' nodes as well as with overloads. In the case of a
+`FUNCTION_DECL', `OVL_CURRENT' will always return the function itself,
+and `OVL_NEXT' will always be `NULL_TREE'.
+
+ To determine the scope of a function, you can use the
+`DECL_REAL_CONTEXT' macro. This macro will return the class (either a
+`RECORD_TYPE' or a `UNION_TYPE') or namespace (a `NAMESPACE_DECL') of
+which the function is a member. For a virtual function, this macro
+returns the class in which the function was actually defined, not the
+base class in which the virtual declaration occurred. If a friend
+function is defined in a class scope, the `DECL_CLASS_CONTEXT' macro
+can be used to determine the class in which it was defined. For
+example, in
+ class C { friend void f() {} };
+ the `DECL_REAL_CONTEXT' for `f' will be the `global_namespace', but
+the `DECL_CLASS_CONTEXT' will be the `RECORD_TYPE' for `C'.
+
+ The `DECL_REAL_CONTEXT' and `DECL_CLASS_CONTEXT' are not available
+in C; instead you should simply use `DECL_CONTEXT'. In C, the
+`DECL_CONTEXT' for a function maybe another function. This
+representation indicates that the GNU nested function extension is in
+use. For details on the semantics of nested functions, see the GCC
+Manual. The nested function can refer to local variables in its
+containing function. Such references are not explicitly marked in the
+tree structure; back ends must look at the `DECL_CONTEXT' for the
+referenced `VAR_DECL'. If the `DECL_CONTEXT' for the referenced
+`VAR_DECL' is not the same as the function currently being processed,
+and neither `DECL_EXTERNAL' nor `DECL_STATIC' hold, then the reference
+is to a local variable in a containing function, and the back end must
+take appropriate action.
+
+* Menu:
+
+* Function Basics:: Function names, linkage, and so forth.
+* Function Bodies:: The statements that make up a function body.
+
+\1f
+File: gccint.info, Node: Function Basics, Next: Function Bodies, Up: Functions
+
+7.6.1 Function Basics
+---------------------
+
+The following macros and functions can be used on a `FUNCTION_DECL':
+`DECL_MAIN_P'
+ This predicate holds for a function that is the program entry point
+ `::code'.
+
+`DECL_NAME'
+ This macro returns the unqualified name of the function, as an
+ `IDENTIFIER_NODE'. For an instantiation of a function template,
+ the `DECL_NAME' is the unqualified name of the template, not
+ something like `f<int>'. The value of `DECL_NAME' is undefined
+ when used on a constructor, destructor, overloaded operator, or
+ type-conversion operator, or any function that is implicitly
+ generated by the compiler. See below for macros that can be used
+ to distinguish these cases.
+
+`DECL_ASSEMBLER_NAME'
+ This macro returns the mangled name of the function, also an
+ `IDENTIFIER_NODE'. This name does not contain leading underscores
+ on systems that prefix all identifiers with underscores. The
+ mangled name is computed in the same way on all platforms; if
+ special processing is required to deal with the object file format
+ used on a particular platform, it is the responsibility of the
+ back end to perform those modifications. (Of course, the back end
+ should not modify `DECL_ASSEMBLER_NAME' itself.)
+
+`DECL_EXTERNAL'
+ This predicate holds if the function is undefined.
+
+`TREE_PUBLIC'
+ This predicate holds if the function has external linkage.
+
+`DECL_LOCAL_FUNCTION_P'
+ This predicate holds if the function was declared at block scope,
+ even though it has a global scope.
+
+`DECL_ANTICIPATED'
+ This predicate holds if the function is a built-in function but its
+ prototype is not yet explicitly declared.
+
+`DECL_EXTERN_C_FUNCTION_P'
+ This predicate holds if the function is declared as an ``extern
+ "C"'' function.
+
+`DECL_LINKONCE_P'
+ This macro holds if multiple copies of this function may be
+ emitted in various translation units. It is the responsibility of
+ the linker to merge the various copies. Template instantiations
+ are the most common example of functions for which
+ `DECL_LINKONCE_P' holds; G++ instantiates needed templates in all
+ translation units which require them, and then relies on the
+ linker to remove duplicate instantiations.
+
+ FIXME: This macro is not yet implemented.
+
+`DECL_FUNCTION_MEMBER_P'
+ This macro holds if the function is a member of a class, rather
+ than a member of a namespace.
+
+`DECL_STATIC_FUNCTION_P'
+ This predicate holds if the function a static member function.
+
+`DECL_NONSTATIC_MEMBER_FUNCTION_P'
+ This macro holds for a non-static member function.
+
+`DECL_CONST_MEMFUNC_P'
+ This predicate holds for a `const'-member function.
+
+`DECL_VOLATILE_MEMFUNC_P'
+ This predicate holds for a `volatile'-member function.
+
+`DECL_CONSTRUCTOR_P'
+ This macro holds if the function is a constructor.
+
+`DECL_NONCONVERTING_P'
+ This predicate holds if the constructor is a non-converting
+ constructor.
+
+`DECL_COMPLETE_CONSTRUCTOR_P'
+ This predicate holds for a function which is a constructor for an
+ object of a complete type.
+
+`DECL_BASE_CONSTRUCTOR_P'
+ This predicate holds for a function which is a constructor for a
+ base class sub-object.
+
+`DECL_COPY_CONSTRUCTOR_P'
+ This predicate holds for a function which is a copy-constructor.
+
+`DECL_DESTRUCTOR_P'
+ This macro holds if the function is a destructor.
+
+`DECL_COMPLETE_DESTRUCTOR_P'
+ This predicate holds if the function is the destructor for an
+ object a complete type.
+
+`DECL_OVERLOADED_OPERATOR_P'
+ This macro holds if the function is an overloaded operator.
+
+`DECL_CONV_FN_P'
+ This macro holds if the function is a type-conversion operator.
+
+`DECL_GLOBAL_CTOR_P'
+ This predicate holds if the function is a file-scope initialization
+ function.
+
+`DECL_GLOBAL_DTOR_P'
+ This predicate holds if the function is a file-scope finalization
+ function.
+
+`DECL_THUNK_P'
+ This predicate holds if the function is a thunk.
+
+ These functions represent stub code that adjusts the `this' pointer
+ and then jumps to another function. When the jumped-to function
+ returns, control is transferred directly to the caller, without
+ returning to the thunk. The first parameter to the thunk is
+ always the `this' pointer; the thunk should add `THUNK_DELTA' to
+ this value. (The `THUNK_DELTA' is an `int', not an `INTEGER_CST'.)
+
+ Then, if `THUNK_VCALL_OFFSET' (an `INTEGER_CST') is nonzero the
+ adjusted `this' pointer must be adjusted again. The complete
+ calculation is given by the following pseudo-code:
+
+ this += THUNK_DELTA
+ if (THUNK_VCALL_OFFSET)
+ this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET]
+
+ Finally, the thunk should jump to the location given by
+ `DECL_INITIAL'; this will always be an expression for the address
+ of a function.
+
+`DECL_NON_THUNK_FUNCTION_P'
+ This predicate holds if the function is _not_ a thunk function.
+
+`GLOBAL_INIT_PRIORITY'
+ If either `DECL_GLOBAL_CTOR_P' or `DECL_GLOBAL_DTOR_P' holds, then
+ this gives the initialization priority for the function. The
+ linker will arrange that all functions for which
+ `DECL_GLOBAL_CTOR_P' holds are run in increasing order of priority
+ before `main' is called. When the program exits, all functions for
+ which `DECL_GLOBAL_DTOR_P' holds are run in the reverse order.
+
+`DECL_ARTIFICIAL'
+ This macro holds if the function was implicitly generated by the
+ compiler, rather than explicitly declared. In addition to
+ implicitly generated class member functions, this macro holds for
+ the special functions created to implement static initialization
+ and destruction, to compute run-time type information, and so
+ forth.
+
+`DECL_ARGUMENTS'
+ This macro returns the `PARM_DECL' for the first argument to the
+ function. Subsequent `PARM_DECL' nodes can be obtained by
+ following the `TREE_CHAIN' links.
+
+`DECL_RESULT'
+ This macro returns the `RESULT_DECL' for the function.
+
+`TREE_TYPE'
+ This macro returns the `FUNCTION_TYPE' or `METHOD_TYPE' for the
+ function.
+
+`TYPE_RAISES_EXCEPTIONS'
+ This macro returns the list of exceptions that a (member-)function
+ can raise. The returned list, if non `NULL', is comprised of nodes
+ whose `TREE_VALUE' represents a type.
+
+`TYPE_NOTHROW_P'
+ This predicate holds when the exception-specification of its
+ arguments if of the form ``()''.
+
+`DECL_ARRAY_DELETE_OPERATOR_P'
+ This predicate holds if the function an overloaded `operator
+ delete[]'.
+
+
+\1f
+File: gccint.info, Node: Function Bodies, Prev: Function Basics, Up: Functions
+
+7.6.2 Function Bodies
+---------------------
+
+A function that has a definition in the current translation unit will
+have a non-`NULL' `DECL_INITIAL'. However, back ends should not make
+use of the particular value given by `DECL_INITIAL'.
+
+ The `DECL_SAVED_TREE' macro will give the complete body of the
+function. This node will usually be a `COMPOUND_STMT' representing the
+outermost block of the function, but it may also be a `TRY_BLOCK', a
+`RETURN_INIT', or any other valid statement.
+
+7.6.2.1 Statements
+..................
+
+There are tree nodes corresponding to all of the source-level statement
+constructs. These are enumerated here, together with a list of the
+various macros that can be used to obtain information about them. There
+are a few macros that can be used with all statements:
+
+`STMT_LINENO'
+ This macro returns the line number for the statement. If the
+ statement spans multiple lines, this value will be the number of
+ the first line on which the statement occurs. Although we mention
+ `CASE_LABEL' below as if it were a statement, they do not allow
+ the use of `STMT_LINENO'. There is no way to obtain the line
+ number for a `CASE_LABEL'.
+
+ Statements do not contain information about the file from which
+ they came; that information is implicit in the `FUNCTION_DECL'
+ from which the statements originate.
+
+`STMT_IS_FULL_EXPR_P'
+ In C++, statements normally constitute "full expressions";
+ temporaries created during a statement are destroyed when the
+ statement is complete. However, G++ sometimes represents
+ expressions by statements; these statements will not have
+ `STMT_IS_FULL_EXPR_P' set. Temporaries created during such
+ statements should be destroyed when the innermost enclosing
+ statement with `STMT_IS_FULL_EXPR_P' set is exited.
+
+
+ Here is the list of the various statement nodes, and the macros used
+to access them. This documentation describes the use of these nodes in
+non-template functions (including instantiations of template functions).
+In template functions, the same nodes are used, but sometimes in
+slightly different ways.
+
+ Many of the statements have substatements. For example, a `while'
+loop will have a body, which is itself a statement. If the substatement
+is `NULL_TREE', it is considered equivalent to a statement consisting
+of a single `;', i.e., an expression statement in which the expression
+has been omitted. A substatement may in fact be a list of statements,
+connected via their `TREE_CHAIN's. So, you should always process the
+statement tree by looping over substatements, like this:
+ void process_stmt (stmt)
+ tree stmt;
+ {
+ while (stmt)
+ {
+ switch (TREE_CODE (stmt))
+ {
+ case IF_STMT:
+ process_stmt (THEN_CLAUSE (stmt));
+ /* More processing here. */
+ break;
+
+ ...
+ }
+
+ stmt = TREE_CHAIN (stmt);
+ }
+ }
+ In other words, while the `then' clause of an `if' statement in C++
+can be only one statement (although that one statement may be a
+compound statement), the intermediate representation will sometimes use
+several statements chained together.
+
+`ASM_STMT'
+ Used to represent an inline assembly statement. For an inline
+ assembly statement like:
+ asm ("mov x, y");
+ The `ASM_STRING' macro will return a `STRING_CST' node for `"mov
+ x, y"'. If the original statement made use of the
+ extended-assembly syntax, then `ASM_OUTPUTS', `ASM_INPUTS', and
+ `ASM_CLOBBERS' will be the outputs, inputs, and clobbers for the
+ statement, represented as `STRING_CST' nodes. The
+ extended-assembly syntax looks like:
+ asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
+ The first string is the `ASM_STRING', containing the instruction
+ template. The next two strings are the output and inputs,
+ respectively; this statement has no clobbers. As this example
+ indicates, "plain" assembly statements are merely a special case
+ of extended assembly statements; they have no cv-qualifiers,
+ outputs, inputs, or clobbers. All of the strings will be
+ `NUL'-terminated, and will contain no embedded `NUL'-characters.
+
+ If the assembly statement is declared `volatile', or if the
+ statement was not an extended assembly statement, and is therefore
+ implicitly volatile, then the predicate `ASM_VOLATILE_P' will hold
+ of the `ASM_STMT'.
+
+`BREAK_STMT'
+ Used to represent a `break' statement. There are no additional
+ fields.
+
+`CASE_LABEL'
+ Use to represent a `case' label, range of `case' labels, or a
+ `default' label. If `CASE_LOW' is `NULL_TREE', then this is a
+ `default' label. Otherwise, if `CASE_HIGH' is `NULL_TREE', then
+ this is an ordinary `case' label. In this case, `CASE_LOW' is an
+ expression giving the value of the label. Both `CASE_LOW' and
+ `CASE_HIGH' are `INTEGER_CST' nodes. These values will have the
+ same type as the condition expression in the switch statement.
+
+ Otherwise, if both `CASE_LOW' and `CASE_HIGH' are defined, the
+ statement is a range of case labels. Such statements originate
+ with the extension that allows users to write things of the form:
+ case 2 ... 5:
+ The first value will be `CASE_LOW', while the second will be
+ `CASE_HIGH'.
+
+`CLEANUP_STMT'
+ Used to represent an action that should take place upon exit from
+ the enclosing scope. Typically, these actions are calls to
+ destructors for local objects, but back ends cannot rely on this
+ fact. If these nodes are in fact representing such destructors,
+ `CLEANUP_DECL' will be the `VAR_DECL' destroyed. Otherwise,
+ `CLEANUP_DECL' will be `NULL_TREE'. In any case, the
+ `CLEANUP_EXPR' is the expression to execute. The cleanups
+ executed on exit from a scope should be run in the reverse order
+ of the order in which the associated `CLEANUP_STMT's were
+ encountered.
+
+`COMPOUND_STMT'
+ Used to represent a brace-enclosed block. The first substatement
+ is given by `COMPOUND_BODY'. Subsequent substatements are found by
+ following the `TREE_CHAIN' link from one substatement to the next.
+ The `COMPOUND_BODY' will be `NULL_TREE' if there are no
+ substatements.
+
+`CONTINUE_STMT'
+ Used to represent a `continue' statement. There are no additional
+ fields.
+
+`CTOR_STMT'
+ Used to mark the beginning (if `CTOR_BEGIN_P' holds) or end (if
+ `CTOR_END_P' holds of the main body of a constructor. See also
+ `SUBOBJECT' for more information on how to use these nodes.
+
+`DECL_STMT'
+ Used to represent a local declaration. The `DECL_STMT_DECL' macro
+ can be used to obtain the entity declared. This declaration may
+ be a `LABEL_DECL', indicating that the label declared is a local
+ label. (As an extension, GCC allows the declaration of labels
+ with scope.) In C, this declaration may be a `FUNCTION_DECL',
+ indicating the use of the GCC nested function extension. For more
+ information, *note Functions::.
+
+`DO_STMT'
+ Used to represent a `do' loop. The body of the loop is given by
+ `DO_BODY' while the termination condition for the loop is given by
+ `DO_COND'. The condition for a `do'-statement is always an
+ expression.
+
+`EMPTY_CLASS_EXPR'
+ Used to represent a temporary object of a class with no data whose
+ address is never taken. (All such objects are interchangeable.)
+ The `TREE_TYPE' represents the type of the object.
+
+`EXPR_STMT'
+ Used to represent an expression statement. Use `EXPR_STMT_EXPR' to
+ obtain the expression.
+
+`FILE_STMT'
+ Used to record a change in filename within the body of a function.
+ Use `FILE_STMT_FILENAME' to obtain the new filename.
+
+`FOR_STMT'
+ Used to represent a `for' statement. The `FOR_INIT_STMT' is the
+ initialization statement for the loop. The `FOR_COND' is the
+ termination condition. The `FOR_EXPR' is the expression executed
+ right before the `FOR_COND' on each loop iteration; often, this
+ expression increments a counter. The body of the loop is given by
+ `FOR_BODY'. Note that `FOR_INIT_STMT' and `FOR_BODY' return
+ statements, while `FOR_COND' and `FOR_EXPR' return expressions.
+
+`GOTO_STMT'
+ Used to represent a `goto' statement. The `GOTO_DESTINATION' will
+ usually be a `LABEL_DECL'. However, if the "computed goto"
+ extension has been used, the `GOTO_DESTINATION' will be an
+ arbitrary expression indicating the destination. This expression
+ will always have pointer type. Additionally the `GOTO_FAKE_P'
+ flag is set whenever the goto statement does not come from source
+ code, but it is generated implicitly by the compiler. This is
+ used for branch prediction.
+
+`HANDLER'
+ Used to represent a C++ `catch' block. The `HANDLER_TYPE' is the
+ type of exception that will be caught by this handler; it is equal
+ (by pointer equality) to `CATCH_ALL_TYPE' if this handler is for
+ all types. `HANDLER_PARMS' is the `DECL_STMT' for the catch
+ parameter, and `HANDLER_BODY' is the `COMPOUND_STMT' for the block
+ itself.
+
+`IF_STMT'
+ Used to represent an `if' statement. The `IF_COND' is the
+ expression.
+
+ If the condition is a `TREE_LIST', then the `TREE_PURPOSE' is a
+ statement (usually a `DECL_STMT'). Each time the condition is
+ evaluated, the statement should be executed. Then, the
+ `TREE_VALUE' should be used as the conditional expression itself.
+ This representation is used to handle C++ code like this:
+
+ if (int i = 7) ...
+
+ where there is a new local variable (or variables) declared within
+ the condition.
+
+ The `THEN_CLAUSE' represents the statement given by the `then'
+ condition, while the `ELSE_CLAUSE' represents the statement given
+ by the `else' condition.
+
+`LABEL_STMT'
+ Used to represent a label. The `LABEL_DECL' declared by this
+ statement can be obtained with the `LABEL_STMT_LABEL' macro. The
+ `IDENTIFIER_NODE' giving the name of the label can be obtained from
+ the `LABEL_DECL' with `DECL_NAME'.
+
+`RETURN_INIT'
+ If the function uses the G++ "named return value" extension,
+ meaning that the function has been defined like:
+ S f(int) return s {...}
+ then there will be a `RETURN_INIT'. There is never a named
+ returned value for a constructor. The first argument to the
+ `RETURN_INIT' is the name of the object returned; the second
+ argument is the initializer for the object. The object is
+ initialized when the `RETURN_INIT' is encountered. The object
+ referred to is the actual object returned; this extension is a
+ manual way of doing the "return-value optimization." Therefore,
+ the object must actually be constructed in the place where the
+ object will be returned.
+
+`RETURN_STMT'
+ Used to represent a `return' statement. The `RETURN_EXPR' is the
+ expression returned; it will be `NULL_TREE' if the statement was
+ just
+ return;
+
+`SCOPE_STMT'
+ A scope-statement represents the beginning or end of a scope. If
+ `SCOPE_BEGIN_P' holds, this statement represents the beginning of a
+ scope; if `SCOPE_END_P' holds this statement represents the end of
+ a scope. On exit from a scope, all cleanups from `CLEANUP_STMT's
+ occurring in the scope must be run, in reverse order to the order
+ in which they were encountered. If `SCOPE_NULLIFIED_P' or
+ `SCOPE_NO_CLEANUPS_P' holds of the scope, back ends should behave
+ as if the `SCOPE_STMT' were not present at all.
+
+`SUBOBJECT'
+ In a constructor, these nodes are used to mark the point at which a
+ subobject of `this' is fully constructed. If, after this point, an
+ exception is thrown before a `CTOR_STMT' with `CTOR_END_P' set is
+ encountered, the `SUBOBJECT_CLEANUP' must be executed. The
+ cleanups must be executed in the reverse order in which they
+ appear.
+
+`SWITCH_STMT'
+ Used to represent a `switch' statement. The `SWITCH_COND' is the
+ expression on which the switch is occurring. See the documentation
+ for an `IF_STMT' for more information on the representation used
+ for the condition. The `SWITCH_BODY' is the body of the switch
+ statement. The `SWITCH_TYPE' is the original type of switch
+ expression as given in the source, before any compiler conversions.
+
+`TRY_BLOCK'
+ Used to represent a `try' block. The body of the try block is
+ given by `TRY_STMTS'. Each of the catch blocks is a `HANDLER'
+ node. The first handler is given by `TRY_HANDLERS'. Subsequent
+ handlers are obtained by following the `TREE_CHAIN' link from one
+ handler to the next. The body of the handler is given by
+ `HANDLER_BODY'.
+
+ If `CLEANUP_P' holds of the `TRY_BLOCK', then the `TRY_HANDLERS'
+ will not be a `HANDLER' node. Instead, it will be an expression
+ that should be executed if an exception is thrown in the try
+ block. It must rethrow the exception after executing that code.
+ And, if an exception is thrown while the expression is executing,
+ `terminate' must be called.
+
+`USING_STMT'
+ Used to represent a `using' directive. The namespace is given by
+ `USING_STMT_NAMESPACE', which will be a NAMESPACE_DECL. This node
+ is needed inside template functions, to implement using directives
+ during instantiation.
+
+`WHILE_STMT'
+ Used to represent a `while' loop. The `WHILE_COND' is the
+ termination condition for the loop. See the documentation for an
+ `IF_STMT' for more information on the representation used for the
+ condition.
+
+ The `WHILE_BODY' is the body of the loop.
+
+
+\1f
+File: gccint.info, Node: Attributes, Next: Expression trees, Prev: Declarations, Up: Trees
+
+7.7 Attributes in trees
+=======================
+
+Attributes, as specified using the `__attribute__' keyword, are
+represented internally as a `TREE_LIST'. The `TREE_PURPOSE' is the
+name of the attribute, as an `IDENTIFIER_NODE'. The `TREE_VALUE' is a
+`TREE_LIST' of the arguments of the attribute, if any, or `NULL_TREE'
+if there are no arguments; the arguments are stored as the `TREE_VALUE'
+of successive entries in the list, and may be identifiers or
+expressions. The `TREE_CHAIN' of the attribute is the next attribute
+in a list of attributes applying to the same declaration or type, or
+`NULL_TREE' if there are no further attributes in the list.
+
+ Attributes may be attached to declarations and to types; these
+attributes may be accessed with the following macros. All attributes
+are stored in this way, and many also cause other changes to the
+declaration or type or to other internal compiler data structures.
+
+ -- Tree Macro: tree DECL_ATTRIBUTES (tree DECL)
+ This macro returns the attributes on the declaration DECL.
+
+ -- Tree Macro: tree TYPE_ATTRIBUTES (tree TYPE)
+ This macro returns the attributes on the type TYPE.
+
+\1f
+File: gccint.info, Node: Expression trees, Prev: Attributes, Up: Trees
+
+7.8 Expressions
+===============
+
+The internal representation for expressions is for the most part quite
+straightforward. However, there are a few facts that one must bear in
+mind. In particular, the expression "tree" is actually a directed
+acyclic graph. (For example there may be many references to the integer
+constant zero throughout the source program; many of these will be
+represented by the same expression node.) You should not rely on
+certain kinds of node being shared, nor should rely on certain kinds of
+nodes being unshared.
+
+ The following macros can be used with all expression nodes:
+
+`TREE_TYPE'
+ Returns the type of the expression. This value may not be
+ precisely the same type that would be given the expression in the
+ original program.
+
+ In what follows, some nodes that one might expect to always have type
+`bool' are documented to have either integral or boolean type. At some
+point in the future, the C front end may also make use of this same
+intermediate representation, and at this point these nodes will
+certainly have integral type. The previous sentence is not meant to
+imply that the C++ front end does not or will not give these nodes
+integral type.
+
+ Below, we list the various kinds of expression nodes. Except where
+noted otherwise, the operands to an expression are accessed using the
+`TREE_OPERAND' macro. For example, to access the first operand to a
+binary plus expression `expr', use:
+
+ TREE_OPERAND (expr, 0)
+ As this example indicates, the operands are zero-indexed.
+
+ The table below begins with constants, moves on to unary expressions,
+then proceeds to binary expressions, and concludes with various other
+kinds of expressions:
+
+`INTEGER_CST'
+ These nodes represent integer constants. Note that the type of
+ these constants is obtained with `TREE_TYPE'; they are not always
+ of type `int'. In particular, `char' constants are represented
+ with `INTEGER_CST' nodes. The value of the integer constant `e' is
+ given by
+ ((TREE_INT_CST_HIGH (e) << HOST_BITS_PER_WIDE_INT)
+ + TREE_INST_CST_LOW (e))
+ HOST_BITS_PER_WIDE_INT is at least thirty-two on all platforms.
+ Both `TREE_INT_CST_HIGH' and `TREE_INT_CST_LOW' return a
+ `HOST_WIDE_INT'. The value of an `INTEGER_CST' is interpreted as
+ a signed or unsigned quantity depending on the type of the
+ constant. In general, the expression given above will overflow,
+ so it should not be used to calculate the value of the constant.
+
+ The variable `integer_zero_node' is an integer constant with value
+ zero. Similarly, `integer_one_node' is an integer constant with
+ value one. The `size_zero_node' and `size_one_node' variables are
+ analogous, but have type `size_t' rather than `int'.
+
+ The function `tree_int_cst_lt' is a predicate which holds if its
+ first argument is less than its second. Both constants are
+ assumed to have the same signedness (i.e., either both should be
+ signed or both should be unsigned.) The full width of the
+ constant is used when doing the comparison; the usual rules about
+ promotions and conversions are ignored. Similarly,
+ `tree_int_cst_equal' holds if the two constants are equal. The
+ `tree_int_cst_sgn' function returns the sign of a constant. The
+ value is `1', `0', or `-1' according on whether the constant is
+ greater than, equal to, or less than zero. Again, the signedness
+ of the constant's type is taken into account; an unsigned constant
+ is never less than zero, no matter what its bit-pattern.
+
+`REAL_CST'
+ FIXME: Talk about how to obtain representations of this constant,
+ do comparisons, and so forth.
+
+`COMPLEX_CST'
+ These nodes are used to represent complex number constants, that
+ is a `__complex__' whose parts are constant nodes. The
+ `TREE_REALPART' and `TREE_IMAGPART' return the real and the
+ imaginary parts respectively.
+
+`VECTOR_CST'
+ These nodes are used to represent vector constants, whose parts are
+ constant nodes. Each individual constant node is either an
+ integer or a double constant node. The first operand is a
+ `TREE_LIST' of the constant nodes and is accessed through
+ `TREE_VECTOR_CST_ELTS'.
+
+`STRING_CST'
+ These nodes represent string-constants. The `TREE_STRING_LENGTH'
+ returns the length of the string, as an `int'. The
+ `TREE_STRING_POINTER' is a `char*' containing the string itself.
+ The string may not be `NUL'-terminated, and it may contain
+ embedded `NUL' characters. Therefore, the `TREE_STRING_LENGTH'
+ includes the trailing `NUL' if it is present.
+
+ For wide string constants, the `TREE_STRING_LENGTH' is the number
+ of bytes in the string, and the `TREE_STRING_POINTER' points to an
+ array of the bytes of the string, as represented on the target
+ system (that is, as integers in the target endianness). Wide and
+ non-wide string constants are distinguished only by the `TREE_TYPE'
+ of the `STRING_CST'.
+
+ FIXME: The formats of string constants are not well-defined when
+ the target system bytes are not the same width as host system
+ bytes.
+
+`PTRMEM_CST'
+ These nodes are used to represent pointer-to-member constants. The
+ `PTRMEM_CST_CLASS' is the class type (either a `RECORD_TYPE' or
+ `UNION_TYPE' within which the pointer points), and the
+ `PTRMEM_CST_MEMBER' is the declaration for the pointed to object.
+ Note that the `DECL_CONTEXT' for the `PTRMEM_CST_MEMBER' is in
+ general different from the `PTRMEM_CST_CLASS'. For example, given:
+ struct B { int i; };
+ struct D : public B {};
+ int D::*dp = &D::i;
+ The `PTRMEM_CST_CLASS' for `&D::i' is `D', even though the
+ `DECL_CONTEXT' for the `PTRMEM_CST_MEMBER' is `B', since `B::i' is
+ a member of `B', not `D'.
+
+`VAR_DECL'
+ These nodes represent variables, including static data members.
+ For more information, *note Declarations::.
+
+`NEGATE_EXPR'
+ These nodes represent unary negation of the single operand, for
+ both integer and floating-point types. The type of negation can be
+ determined by looking at the type of the expression.
+
+`BIT_NOT_EXPR'
+ These nodes represent bitwise complement, and will always have
+ integral type. The only operand is the value to be complemented.
+
+`TRUTH_NOT_EXPR'
+ These nodes represent logical negation, and will always have
+ integral (or boolean) type. The operand is the value being
+ negated.
+
+`PREDECREMENT_EXPR'
+`PREINCREMENT_EXPR'
+`POSTDECREMENT_EXPR'
+`POSTINCREMENT_EXPR'
+ These nodes represent increment and decrement expressions. The
+ value of the single operand is computed, and the operand
+ incremented or decremented. In the case of `PREDECREMENT_EXPR' and
+ `PREINCREMENT_EXPR', the value of the expression is the value
+ resulting after the increment or decrement; in the case of
+ `POSTDECREMENT_EXPR' and `POSTINCREMENT_EXPR' is the value before
+ the increment or decrement occurs. The type of the operand, like
+ that of the result, will be either integral, boolean, or
+ floating-point.
+
+`ADDR_EXPR'
+ These nodes are used to represent the address of an object. (These
+ expressions will always have pointer or reference type.) The
+ operand may be another expression, or it may be a declaration.
+
+ As an extension, GCC allows users to take the address of a label.
+ In this case, the operand of the `ADDR_EXPR' will be a
+ `LABEL_DECL'. The type of such an expression is `void*'.
+
+ If the object addressed is not an lvalue, a temporary is created,
+ and the address of the temporary is used.
+
+`INDIRECT_REF'
+ These nodes are used to represent the object pointed to by a
+ pointer. The operand is the pointer being dereferenced; it will
+ always have pointer or reference type.
+
+`FIX_TRUNC_EXPR'
+ These nodes represent conversion of a floating-point value to an
+ integer. The single operand will have a floating-point type,
+ while the the complete expression will have an integral (or
+ boolean) type. The operand is rounded towards zero.
+
+`FLOAT_EXPR'
+ These nodes represent conversion of an integral (or boolean) value
+ to a floating-point value. The single operand will have integral
+ type, while the complete expression will have a floating-point
+ type.
+
+ FIXME: How is the operand supposed to be rounded? Is this
+ dependent on `-mieee'?
+
+`COMPLEX_EXPR'
+ These nodes are used to represent complex numbers constructed from
+ two expressions of the same (integer or real) type. The first
+ operand is the real part and the second operand is the imaginary
+ part.
+
+`CONJ_EXPR'
+ These nodes represent the conjugate of their operand.
+
+`REALPART_EXPR'
+
+`IMAGPART_EXPR'
+ These nodes represent respectively the real and the imaginary parts
+ of complex numbers (their sole argument).
+
+`NON_LVALUE_EXPR'
+ These nodes indicate that their one and only operand is not an
+ lvalue. A back end can treat these identically to the single
+ operand.
+
+`NOP_EXPR'
+ These nodes are used to represent conversions that do not require
+ any code-generation. For example, conversion of a `char*' to an
+ `int*' does not require any code be generated; such a conversion is
+ represented by a `NOP_EXPR'. The single operand is the expression
+ to be converted. The conversion from a pointer to a reference is
+ also represented with a `NOP_EXPR'.
+
+`CONVERT_EXPR'
+ These nodes are similar to `NOP_EXPR's, but are used in those
+ situations where code may need to be generated. For example, if an
+ `int*' is converted to an `int' code may need to be generated on
+ some platforms. These nodes are never used for C++-specific
+ conversions, like conversions between pointers to different
+ classes in an inheritance hierarchy. Any adjustments that need to
+ be made in such cases are always indicated explicitly. Similarly,
+ a user-defined conversion is never represented by a
+ `CONVERT_EXPR'; instead, the function calls are made explicit.
+
+`THROW_EXPR'
+ These nodes represent `throw' expressions. The single operand is
+ an expression for the code that should be executed to throw the
+ exception. However, there is one implicit action not represented
+ in that expression; namely the call to `__throw'. This function
+ takes no arguments. If `setjmp'/`longjmp' exceptions are used, the
+ function `__sjthrow' is called instead. The normal GCC back end
+ uses the function `emit_throw' to generate this code; you can
+ examine this function to see what needs to be done.
+
+`LSHIFT_EXPR'
+`RSHIFT_EXPR'
+ These nodes represent left and right shifts, respectively. The
+ first operand is the value to shift; it will always be of integral
+ type. The second operand is an expression for the number of bits
+ by which to shift. Right shift should be treated as arithmetic,
+ i.e., the high-order bits should be zero-filled when the
+ expression has unsigned type and filled with the sign bit when the
+ expression has signed type. Note that the result is undefined if
+ the second operand is larger than the first operand's type size.
+
+`BIT_IOR_EXPR'
+`BIT_XOR_EXPR'
+`BIT_AND_EXPR'
+ These nodes represent bitwise inclusive or, bitwise exclusive or,
+ and bitwise and, respectively. Both operands will always have
+ integral type.
+
+`TRUTH_ANDIF_EXPR'
+`TRUTH_ORIF_EXPR'
+ These nodes represent logical and and logical or, respectively.
+ These operators are not strict; i.e., the second operand is
+ evaluated only if the value of the expression is not determined by
+ evaluation of the first operand. The type of the operands, and
+ the result type, is always of boolean or integral type.
+
+`TRUTH_AND_EXPR'
+`TRUTH_OR_EXPR'
+`TRUTH_XOR_EXPR'
+ These nodes represent logical and, logical or, and logical
+ exclusive or. They are strict; both arguments are always
+ evaluated. There are no corresponding operators in C or C++, but
+ the front end will sometimes generate these expressions anyhow, if
+ it can tell that strictness does not matter.
+
+`PLUS_EXPR'
+`MINUS_EXPR'
+`MULT_EXPR'
+`TRUNC_DIV_EXPR'
+`TRUNC_MOD_EXPR'
+`RDIV_EXPR'
+ These nodes represent various binary arithmetic operations.
+ Respectively, these operations are addition, subtraction (of the
+ second operand from the first), multiplication, integer division,
+ integer remainder, and floating-point division. The operands to
+ the first three of these may have either integral or floating
+ type, but there will never be case in which one operand is of
+ floating type and the other is of integral type.
+
+ The result of a `TRUNC_DIV_EXPR' is always rounded towards zero.
+ The `TRUNC_MOD_EXPR' of two operands `a' and `b' is always `a -
+ a/b' where the division is as if computed by a `TRUNC_DIV_EXPR'.
+
+`ARRAY_REF'
+ These nodes represent array accesses. The first operand is the
+ array; the second is the index. To calculate the address of the
+ memory accessed, you must scale the index by the size of the type
+ of the array elements. The type of these expressions must be the
+ type of a component of the array.
+
+`ARRAY_RANGE_REF'
+ These nodes represent access to a range (or "slice") of an array.
+ The operands are the same as that for `ARRAY_REF' and have the same
+ meanings. The type of these expressions must be an array whose
+ component type is the same as that of the first operand. The
+ range of that array type determines the amount of data these
+ expressions access.
+
+`EXACT_DIV_EXPR'
+ Document.
+
+`LT_EXPR'
+`LE_EXPR'
+`GT_EXPR'
+`GE_EXPR'
+`EQ_EXPR'
+`NE_EXPR'
+ These nodes represent the less than, less than or equal to, greater
+ than, greater than or equal to, equal, and not equal comparison
+ operators. The first and second operand with either be both of
+ integral type or both of floating type. The result type of these
+ expressions will always be of integral or boolean type.
+
+`MODIFY_EXPR'
+ These nodes represent assignment. The left-hand side is the first
+ operand; the right-hand side is the second operand. The left-hand
+ side will be a `VAR_DECL', `INDIRECT_REF', `COMPONENT_REF', or
+ other lvalue.
+
+ These nodes are used to represent not only assignment with `=' but
+ also compound assignments (like `+='), by reduction to `='
+ assignment. In other words, the representation for `i += 3' looks
+ just like that for `i = i + 3'.
+
+`INIT_EXPR'
+ These nodes are just like `MODIFY_EXPR', but are used only when a
+ variable is initialized, rather than assigned to subsequently.
+
+`COMPONENT_REF'
+ These nodes represent non-static data member accesses. The first
+ operand is the object (rather than a pointer to it); the second
+ operand is the `FIELD_DECL' for the data member.
+
+`COMPOUND_EXPR'
+ These nodes represent comma-expressions. The first operand is an
+ expression whose value is computed and thrown away prior to the
+ evaluation of the second operand. The value of the entire
+ expression is the value of the second operand.
+
+`COND_EXPR'
+ These nodes represent `?:' expressions. The first operand is of
+ boolean or integral type. If it evaluates to a nonzero value, the
+ second operand should be evaluated, and returned as the value of
+ the expression. Otherwise, the third operand is evaluated, and
+ returned as the value of the expression. As a GNU extension, the
+ middle operand of the `?:' operator may be omitted in the source,
+ like this:
+
+ x ? : 3
+ which is equivalent to
+
+ x ? x : 3
+
+ assuming that `x' is an expression without side-effects. However,
+ in the case that the first operation causes side effects, the
+ side-effects occur only once. Consumers of the internal
+ representation do not need to worry about this oddity; the second
+ operand will be always be present in the internal representation.
+
+`CALL_EXPR'
+ These nodes are used to represent calls to functions, including
+ non-static member functions. The first operand is a pointer to the
+ function to call; it is always an expression whose type is a
+ `POINTER_TYPE'. The second argument is a `TREE_LIST'. The
+ arguments to the call appear left-to-right in the list. The
+ `TREE_VALUE' of each list node contains the expression
+ corresponding to that argument. (The value of `TREE_PURPOSE' for
+ these nodes is unspecified, and should be ignored.) For non-static
+ member functions, there will be an operand corresponding to the
+ `this' pointer. There will always be expressions corresponding to
+ all of the arguments, even if the function is declared with default
+ arguments and some arguments are not explicitly provided at the
+ call sites.
+
+`STMT_EXPR'
+ These nodes are used to represent GCC's statement-expression
+ extension. The statement-expression extension allows code like
+ this:
+ int f() { return ({ int j; j = 3; j + 7; }); }
+ In other words, an sequence of statements may occur where a single
+ expression would normally appear. The `STMT_EXPR' node represents
+ such an expression. The `STMT_EXPR_STMT' gives the statement
+ contained in the expression; this is always a `COMPOUND_STMT'. The
+ value of the expression is the value of the last sub-statement in
+ the `COMPOUND_STMT'. More precisely, the value is the value
+ computed by the last `EXPR_STMT' in the outermost scope of the
+ `COMPOUND_STMT'. For example, in:
+ ({ 3; })
+ the value is `3' while in:
+ ({ if (x) { 3; } })
+ (represented by a nested `COMPOUND_STMT'), there is no value. If
+ the `STMT_EXPR' does not yield a value, it's type will be `void'.
+
+`BIND_EXPR'
+ These nodes represent local blocks. The first operand is a list of
+ temporary variables, connected via their `TREE_CHAIN' field. These
+ will never require cleanups. The scope of these variables is just
+ the body of the `BIND_EXPR'. The body of the `BIND_EXPR' is the
+ second operand.
+
+`LOOP_EXPR'
+ These nodes represent "infinite" loops. The `LOOP_EXPR_BODY'
+ represents the body of the loop. It should be executed forever,
+ unless an `EXIT_EXPR' is encountered.
+
+`EXIT_EXPR'
+ These nodes represent conditional exits from the nearest enclosing
+ `LOOP_EXPR'. The single operand is the condition; if it is
+ nonzero, then the loop should be exited. An `EXIT_EXPR' will only
+ appear within a `LOOP_EXPR'.
+
+`CLEANUP_POINT_EXPR'
+ These nodes represent full-expressions. The single operand is an
+ expression to evaluate. Any destructor calls engendered by the
+ creation of temporaries during the evaluation of that expression
+ should be performed immediately after the expression is evaluated.
+
+`CONSTRUCTOR'
+ These nodes represent the brace-enclosed initializers for a
+ structure or array. The first operand is reserved for use by the
+ back end. The second operand is a `TREE_LIST'. If the
+ `TREE_TYPE' of the `CONSTRUCTOR' is a `RECORD_TYPE' or
+ `UNION_TYPE', then the `TREE_PURPOSE' of each node in the
+ `TREE_LIST' will be a `FIELD_DECL' and the `TREE_VALUE' of each
+ node will be the expression used to initialize that field. You
+ should not depend on the fields appearing in any particular order,
+ nor should you assume that all fields will be represented.
+ Unrepresented fields may be assigned any value.
+
+ If the `TREE_TYPE' of the `CONSTRUCTOR' is an `ARRAY_TYPE', then
+ the `TREE_PURPOSE' of each element in the `TREE_LIST' will be an
+ `INTEGER_CST'. This constant indicates which element of the array
+ (indexed from zero) is being assigned to; again, the `TREE_VALUE'
+ is the corresponding initializer. If the `TREE_PURPOSE' is
+ `NULL_TREE', then the initializer is for the next available array
+ element.
+
+ Conceptually, before any initialization is done, the entire area of
+ storage is initialized to zero.
+
+`COMPOUND_LITERAL_EXPR'
+ These nodes represent ISO C99 compound literals. The
+ `COMPOUND_LITERAL_EXPR_DECL_STMT' is a `DECL_STMT' containing an
+ anonymous `VAR_DECL' for the unnamed object represented by the
+ compound literal; the `DECL_INITIAL' of that `VAR_DECL' is a
+ `CONSTRUCTOR' representing the brace-enclosed list of initializers
+ in the compound literal. That anonymous `VAR_DECL' can also be
+ accessed directly by the `COMPOUND_LITERAL_EXPR_DECL' macro.
+
+`SAVE_EXPR'
+ A `SAVE_EXPR' represents an expression (possibly involving
+ side-effects) that is used more than once. The side-effects should
+ occur only the first time the expression is evaluated. Subsequent
+ uses should just reuse the computed value. The first operand to
+ the `SAVE_EXPR' is the expression to evaluate. The side-effects
+ should be executed where the `SAVE_EXPR' is first encountered in a
+ depth-first preorder traversal of the expression tree.
+
+`TARGET_EXPR'
+ A `TARGET_EXPR' represents a temporary object. The first operand
+ is a `VAR_DECL' for the temporary variable. The second operand is
+ the initializer for the temporary. The initializer is evaluated,
+ and copied (bitwise) into the temporary.
+
+ Often, a `TARGET_EXPR' occurs on the right-hand side of an
+ assignment, or as the second operand to a comma-expression which is
+ itself the right-hand side of an assignment, etc. In this case,
+ we say that the `TARGET_EXPR' is "normal"; otherwise, we say it is
+ "orphaned". For a normal `TARGET_EXPR' the temporary variable
+ should be treated as an alias for the left-hand side of the
+ assignment, rather than as a new temporary variable.
+
+ The third operand to the `TARGET_EXPR', if present, is a
+ cleanup-expression (i.e., destructor call) for the temporary. If
+ this expression is orphaned, then this expression must be executed
+ when the statement containing this expression is complete. These
+ cleanups must always be executed in the order opposite to that in
+ which they were encountered. Note that if a temporary is created
+ on one branch of a conditional operator (i.e., in the second or
+ third operand to a `COND_EXPR'), the cleanup must be run only if
+ that branch is actually executed.
+
+ See `STMT_IS_FULL_EXPR_P' for more information about running these
+ cleanups.
+
+`AGGR_INIT_EXPR'
+ An `AGGR_INIT_EXPR' represents the initialization as the return
+ value of a function call, or as the result of a constructor. An
+ `AGGR_INIT_EXPR' will only appear as the second operand of a
+ `TARGET_EXPR'. The first operand to the `AGGR_INIT_EXPR' is the
+ address of a function to call, just as in a `CALL_EXPR'. The
+ second operand are the arguments to pass that function, as a
+ `TREE_LIST', again in a manner similar to that of a `CALL_EXPR'.
+ The value of the expression is that returned by the function.
+
+ If `AGGR_INIT_VIA_CTOR_P' holds of the `AGGR_INIT_EXPR', then the
+ initialization is via a constructor call. The address of the third
+ operand of the `AGGR_INIT_EXPR', which is always a `VAR_DECL', is
+ taken, and this value replaces the first argument in the argument
+ list. In this case, the value of the expression is the `VAR_DECL'
+ given by the third operand to the `AGGR_INIT_EXPR'; constructors do
+ not return a value.
+
+`VTABLE_REF'
+ A `VTABLE_REF' indicates that the interior expression computes a
+ value that is a vtable entry. It is used with `-fvtable-gc' to
+ track the reference through to front end to the middle end, at
+ which point we transform this to a `REG_VTABLE_REF' note, which
+ survives the balance of code generation.
+
+ The first operand is the expression that computes the vtable
+ reference. The second operand is the `VAR_DECL' of the vtable.
+ The third operand is an `INTEGER_CST' of the byte offset into the
+ vtable.
+
+
+\1f
+File: gccint.info, Node: RTL, Next: Machine Desc, Prev: Trees, Up: Top
+
+8 RTL Representation
+********************
+
+Most of the work of the compiler is done on an intermediate
+representation called register transfer language. In this language,
+the instructions to be output are described, pretty much one by one, in
+an algebraic form that describes what the instruction does.
+
+ RTL is inspired by Lisp lists. It has both an internal form, made
+up of structures that point at other structures, and a textual form
+that is used in the machine description and in printed debugging dumps.
+The textual form uses nested parentheses to indicate the pointers in
+the internal form.
+
+* Menu:
+
+* RTL Objects:: Expressions vs vectors vs strings vs integers.
+* RTL Classes:: Categories of RTL expression objects, and their structure.
+* Accessors:: Macros to access expression operands or vector elts.
+* Flags:: Other flags in an RTL expression.
+* Machine Modes:: Describing the size and format of a datum.
+* Constants:: Expressions with constant values.
+* Regs and Memory:: Expressions representing register contents or memory.
+* Arithmetic:: Expressions representing arithmetic on other expressions.
+* Comparisons:: Expressions representing comparison of expressions.
+* Bit-Fields:: Expressions representing bit-fields in memory or reg.
+* Vector Operations:: Expressions involving vector datatypes.
+* Conversions:: Extending, truncating, floating or fixing.
+* RTL Declarations:: Declaring volatility, constancy, etc.
+* Side Effects:: Expressions for storing in registers, etc.
+* Incdec:: Embedded side-effects for autoincrement addressing.
+* Assembler:: Representing `asm' with operands.
+* Insns:: Expression types for entire insns.
+* Calls:: RTL representation of function call insns.
+* Sharing:: Some expressions are unique; others *must* be copied.
+* Reading RTL:: Reading textual RTL from a file.
+
+\1f
+File: gccint.info, Node: RTL Objects, Next: RTL Classes, Up: RTL
+
+8.1 RTL Object Types
+====================
+
+RTL uses five kinds of objects: expressions, integers, wide integers,
+strings and vectors. Expressions are the most important ones. An RTL
+expression ("RTX", for short) is a C structure, but it is usually
+referred to with a pointer; a type that is given the typedef name `rtx'.
+
+ An integer is simply an `int'; their written form uses decimal
+digits. A wide integer is an integral object whose type is
+`HOST_WIDE_INT'; their written form uses decimal digits.
+
+ A string is a sequence of characters. In core it is represented as a
+`char *' in usual C fashion, and it is written in C syntax as well.
+However, strings in RTL may never be null. If you write an empty
+string in a machine description, it is represented in core as a null
+pointer rather than as a pointer to a null character. In certain
+contexts, these null pointers instead of strings are valid. Within RTL
+code, strings are most commonly found inside `symbol_ref' expressions,
+but they appear in other contexts in the RTL expressions that make up
+machine descriptions.
+
+ In a machine description, strings are normally written with double
+quotes, as you would in C. However, strings in machine descriptions may
+extend over many lines, which is invalid C, and adjacent string
+constants are not concatenated as they are in C. Any string constant
+may be surrounded with a single set of parentheses. Sometimes this
+makes the machine description easier to read.
+
+ There is also a special syntax for strings, which can be useful when
+C code is embedded in a machine description. Wherever a string can
+appear, it is also valid to write a C-style brace block. The entire
+brace block, including the outermost pair of braces, is considered to be
+the string constant. Double quote characters inside the braces are not
+special. Therefore, if you write string constants in the C code, you
+need not escape each quote character with a backslash.
+
+ A vector contains an arbitrary number of pointers to expressions.
+The number of elements in the vector is explicitly present in the
+vector. The written form of a vector consists of square brackets
+(`[...]') surrounding the elements, in sequence and with whitespace
+separating them. Vectors of length zero are not created; null pointers
+are used instead.
+
+ Expressions are classified by "expression codes" (also called RTX
+codes). The expression code is a name defined in `rtl.def', which is
+also (in upper case) a C enumeration constant. The possible expression
+codes and their meanings are machine-independent. The code of an RTX
+can be extracted with the macro `GET_CODE (X)' and altered with
+`PUT_CODE (X, NEWCODE)'.
+
+ The expression code determines how many operands the expression
+contains, and what kinds of objects they are. In RTL, unlike Lisp, you
+cannot tell by looking at an operand what kind of object it is.
+Instead, you must know from its context--from the expression code of
+the containing expression. For example, in an expression of code
+`subreg', the first operand is to be regarded as an expression and the
+second operand as an integer. In an expression of code `plus', there
+are two operands, both of which are to be regarded as expressions. In
+a `symbol_ref' expression, there is one operand, which is to be
+regarded as a string.
+
+ Expressions are written as parentheses containing the name of the
+expression type, its flags and machine mode if any, and then the
+operands of the expression (separated by spaces).
+
+ Expression code names in the `md' file are written in lower case,
+but when they appear in C code they are written in upper case. In this
+manual, they are shown as follows: `const_int'.
+
+ In a few contexts a null pointer is valid where an expression is
+normally wanted. The written form of this is `(nil)'.
+
+\1f
+File: gccint.info, Node: RTL Classes, Next: Accessors, Prev: RTL Objects, Up: RTL
+
+8.2 RTL Classes and Formats
+===========================
+
+The various expression codes are divided into several "classes", which
+are represented by single characters. You can determine the class of
+an RTX code with the macro `GET_RTX_CLASS (CODE)'. Currently,
+`rtx.def' defines these classes:
+
+`o'
+ An RTX code that represents an actual object, such as a register
+ (`REG') or a memory location (`MEM', `SYMBOL_REF'). Constants and
+ basic transforms on objects (`ADDRESSOF', `HIGH', `LO_SUM') are
+ also included. Note that `SUBREG' and `STRICT_LOW_PART' are not
+ in this class, but in class `x'.
+
+`<'
+ An RTX code for a comparison, such as `NE' or `LT'.
+
+`1'
+ An RTX code for a unary arithmetic operation, such as `NEG',
+ `NOT', or `ABS'. This category also includes value extension
+ (sign or zero) and conversions between integer and floating point.
+
+`c'
+ An RTX code for a commutative binary operation, such as `PLUS' or
+ `AND'. `NE' and `EQ' are comparisons, so they have class `<'.
+
+`2'
+ An RTX code for a non-commutative binary operation, such as
+ `MINUS', `DIV', or `ASHIFTRT'.
+
+`b'
+ An RTX code for a bit-field operation. Currently only
+ `ZERO_EXTRACT' and `SIGN_EXTRACT'. These have three inputs and
+ are lvalues (so they can be used for insertion as well). *Note
+ Bit-Fields::.
+
+`3'
+ An RTX code for other three input operations. Currently only
+ `IF_THEN_ELSE'.
+
+`i'
+ An RTX code for an entire instruction: `INSN', `JUMP_INSN', and
+ `CALL_INSN'. *Note Insns::.
+
+`m'
+ An RTX code for something that matches in insns, such as
+ `MATCH_DUP'. These only occur in machine descriptions.
+
+`a'
+ An RTX code for an auto-increment addressing mode, such as
+ `POST_INC'.
+
+`x'
+ All other RTX codes. This category includes the remaining codes
+ used only in machine descriptions (`DEFINE_*', etc.). It also
+ includes all the codes describing side effects (`SET', `USE',
+ `CLOBBER', etc.) and the non-insns that may appear on an insn
+ chain, such as `NOTE', `BARRIER', and `CODE_LABEL'.
+
+ For each expression code, `rtl.def' specifies the number of
+contained objects and their kinds using a sequence of characters called
+the "format" of the expression code. For example, the format of
+`subreg' is `ei'.
+
+ These are the most commonly used format characters:
+
+`e'
+ An expression (actually a pointer to an expression).
+
+`i'
+ An integer.
+
+`w'
+ A wide integer.
+
+`s'
+ A string.
+
+`E'
+ A vector of expressions.
+
+ A few other format characters are used occasionally:
+
+`u'
+ `u' is equivalent to `e' except that it is printed differently in
+ debugging dumps. It is used for pointers to insns.
+
+`n'
+ `n' is equivalent to `i' except that it is printed differently in
+ debugging dumps. It is used for the line number or code number of
+ a `note' insn.
+
+`S'
+ `S' indicates a string which is optional. In the RTL objects in
+ core, `S' is equivalent to `s', but when the object is read, from
+ an `md' file, the string value of this operand may be omitted. An
+ omitted string is taken to be the null string.
+
+`V'
+ `V' indicates a vector which is optional. In the RTL objects in
+ core, `V' is equivalent to `E', but when the object is read from
+ an `md' file, the vector value of this operand may be omitted. An
+ omitted vector is effectively the same as a vector of no elements.
+
+`0'
+ `0' means a slot whose contents do not fit any normal category.
+ `0' slots are not printed at all in dumps, and are often used in
+ special ways by small parts of the compiler.
+
+ There are macros to get the number of operands and the format of an
+expression code:
+
+`GET_RTX_LENGTH (CODE)'
+ Number of operands of an RTX of code CODE.
+
+`GET_RTX_FORMAT (CODE)'
+ The format of an RTX of code CODE, as a C string.
+
+ Some classes of RTX codes always have the same format. For example,
+it is safe to assume that all comparison operations have format `ee'.
+
+`1'
+ All codes of this class have format `e'.
+
+`<'
+`c'
+`2'
+ All codes of these classes have format `ee'.
+
+`b'
+`3'
+ All codes of these classes have format `eee'.
+
+`i'
+ All codes of this class have formats that begin with `iuueiee'.
+ *Note Insns::. Note that not all RTL objects linked onto an insn
+ chain are of class `i'.
+
+`o'
+`m'
+`x'
+ You can make no assumptions about the format of these codes.
+
+\1f
+File: gccint.info, Node: Accessors, Next: Flags, Prev: RTL Classes, Up: RTL
+
+8.3 Access to Operands
+======================
+
+Operands of expressions are accessed using the macros `XEXP', `XINT',
+`XWINT' and `XSTR'. Each of these macros takes two arguments: an
+expression-pointer (RTX) and an operand number (counting from zero).
+Thus,
+
+ XEXP (X, 2)
+
+accesses operand 2 of expression X, as an expression.
+
+ XINT (X, 2)
+
+accesses the same operand as an integer. `XSTR', used in the same
+fashion, would access it as a string.
+
+ Any operand can be accessed as an integer, as an expression or as a
+string. You must choose the correct method of access for the kind of
+value actually stored in the operand. You would do this based on the
+expression code of the containing expression. That is also how you
+would know how many operands there are.
+
+ For example, if X is a `subreg' expression, you know that it has two
+operands which can be correctly accessed as `XEXP (X, 0)' and `XINT (X,
+1)'. If you did `XINT (X, 0)', you would get the address of the
+expression operand but cast as an integer; that might occasionally be
+useful, but it would be cleaner to write `(int) XEXP (X, 0)'. `XEXP
+(X, 1)' would also compile without error, and would return the second,
+integer operand cast as an expression pointer, which would probably
+result in a crash when accessed. Nothing stops you from writing `XEXP
+(X, 28)' either, but this will access memory past the end of the
+expression with unpredictable results.
+
+ Access to operands which are vectors is more complicated. You can
+use the macro `XVEC' to get the vector-pointer itself, or the macros
+`XVECEXP' and `XVECLEN' to access the elements and length of a vector.
+
+`XVEC (EXP, IDX)'
+ Access the vector-pointer which is operand number IDX in EXP.
+
+`XVECLEN (EXP, IDX)'
+ Access the length (number of elements) in the vector which is in
+ operand number IDX in EXP. This value is an `int'.
+
+`XVECEXP (EXP, IDX, ELTNUM)'
+ Access element number ELTNUM in the vector which is in operand
+ number IDX in EXP. This value is an RTX.
+
+ It is up to you to make sure that ELTNUM is not negative and is
+ less than `XVECLEN (EXP, IDX)'.
+
+ All the macros defined in this section expand into lvalues and
+therefore can be used to assign the operands, lengths and vector
+elements as well as to access them.
+
+\1f
+File: gccint.info, Node: Flags, Next: Machine Modes, Prev: Accessors, Up: RTL
+
+8.4 Flags in an RTL Expression
+==============================
+
+RTL expressions contain several flags (one-bit bit-fields) that are
+used in certain types of expression. Most often they are accessed with
+the following macros, which expand into lvalues:
+
+`CONSTANT_POOL_ADDRESS_P (X)'
+ Nonzero in a `symbol_ref' if it refers to part of the current
+ function's constant pool. For most targets these addresses are in
+ a `.rodata' section entirely separate from the function, but for
+ some targets the addresses are close to the beginning of the
+ function. In either case GCC assumes these addresses can be
+ addressed directly, perhaps with the help of base registers.
+ Stored in the `unchanging' field and printed as `/u'.
+
+`CONST_OR_PURE_CALL_P (X)'
+ In a `call_insn', `note', or an `expr_list' for notes, indicates
+ that the insn represents a call to a const or pure function.
+ Stored in the `unchanging' field and printed as `/u'.
+
+`INSN_ANNULLED_BRANCH_P (X)'
+ In an `insn' in the delay slot of a branch insn, indicates that an
+ annulling branch should be used. See the discussion under
+ `sequence' below. Stored in the `unchanging' field and printed as
+ `/u'.
+
+`INSN_DEAD_CODE_P (X)'
+ In an `insn' during the dead-code elimination pass, nonzero if the
+ insn is dead. Stored in the `in_struct' field and printed as `/s'.
+
+`INSN_DELETED_P (X)'
+ In an `insn', nonzero if the insn has been deleted. Stored in the
+ `volatil' field and printed as `/v'.
+
+`INSN_FROM_TARGET_P (X)'
+ In an `insn' in a delay slot of a branch, indicates that the insn
+ is from the target of the branch. If the branch insn has
+ `INSN_ANNULLED_BRANCH_P' set, this insn will only be executed if
+ the branch is taken. For annulled branches with
+ `INSN_FROM_TARGET_P' clear, the insn will be executed only if the
+ branch is not taken. When `INSN_ANNULLED_BRANCH_P' is not set,
+ this insn will always be executed. Stored in the `in_struct'
+ field and printed as `/s'.
+
+`LABEL_OUTSIDE_LOOP_P (X)'
+ In `label_ref' expressions, nonzero if this is a reference to a
+ label that is outside the innermost loop containing the reference
+ to the label. Stored in the `in_struct' field and printed as `/s'.
+
+`LABEL_PRESERVE_P (X)'
+ In a `code_label', indicates that the label is referenced by code
+ or data not visible to the RTL of a given function. Labels
+ referenced by a non-local goto will have this bit set. Stored in
+ the `in_struct' field and printed as `/s'.
+
+`LABEL_REF_NONLOCAL_P (X)'
+ In `label_ref' and `reg_label' expressions, nonzero if this is a
+ reference to a non-local label. Stored in the `volatil' field and
+ printed as `/v'.
+
+`LINK_COST_FREE (X)'
+ In the `LOG_LINKS' `insn_list' during scheduling, nonzero when the
+ cost of executing an instruction through the link is zero, i.e.,
+ the link makes the cost free. Stored in the `call' field and
+ printed as `/c'.
+
+`LINK_COST_ZERO (X)'
+ In the `LOG_LINKS' `insn_list' during scheduling, nonzero when the
+ cost of executing an instruction through the link varies and is
+ unchanged, i.e., the link has zero additional cost. Stored in the
+ `jump' field and printed as `/j'.
+
+`MEM_IN_STRUCT_P (X)'
+ In `mem' expressions, nonzero for reference to an entire structure,
+ union or array, or to a component of one. Zero for references to a
+ scalar variable or through a pointer to a scalar. If both this
+ flag and `MEM_SCALAR_P' are clear, then we don't know whether this
+ `mem' is in a structure or not. Both flags should never be
+ simultaneously set. Stored in the `in_struct' field and printed
+ as `/s'.
+
+`MEM_KEEP_ALIAS_SET_P (X)'
+ In `mem' expressions, 1 if we should keep the alias set for this
+ mem unchanged when we access a component. Set to 1, for example,
+ when we are already in a non-addressable component of an aggregate.
+ Stored in the `jump' field and printed as `/j'.
+
+`MEM_SCALAR_P (X)'
+ In `mem' expressions, nonzero for reference to a scalar known not
+ to be a member of a structure, union, or array. Zero for such
+ references and for indirections through pointers, even pointers
+ pointing to scalar types. If both this flag and `MEM_IN_STRUCT_P'
+ are clear, then we don't know whether this `mem' is in a structure
+ or not. Both flags should never be simultaneously set. Stored in
+ the `frame_related' field and printed as `/f'.
+
+`MEM_VOLATILE_P (X)'
+ In `mem' and `asm_operands' expressions, nonzero for volatile
+ memory references. Stored in the `volatil' field and printed as
+ `/v'.
+
+`REG_FUNCTION_VALUE_P (X)'
+ Nonzero in a `reg' if it is the place in which this function's
+ value is going to be returned. (This happens only in a hard
+ register.) Stored in the `integrated' field and printed as `/i'.
+
+`REG_LOOP_TEST_P (X)'
+ In `reg' expressions, nonzero if this register's entire life is
+ contained in the exit test code for some loop. Stored in the
+ `in_struct' field and printed as `/s'.
+
+`REG_POINTER (X)'
+ Nonzero in a `reg' if the register holds a pointer. Stored in the
+ `frame_related' field and printed as `/f'.
+
+`REG_USERVAR_P (X)'
+ In a `reg', nonzero if it corresponds to a variable present in the
+ user's source code. Zero for temporaries generated internally by
+ the compiler. Stored in the `volatil' field and printed as `/v'.
+
+ The same hard register may be used also for collecting the values
+ of functions called by this one, but `REG_FUNCTION_VALUE_P' is zero
+ in this kind of use.
+
+`RTX_FRAME_RELATED_P (X)'
+ Nonzero in an `insn' or `set' which is part of a function prologue
+ and sets the stack pointer, sets the frame pointer, or saves a
+ register. This flag should also be set on an instruction that
+ sets up a temporary register to use in place of the frame pointer.
+ Stored in the `frame_related' field and printed as `/f'.
+
+ In particular, on RISC targets where there are limits on the sizes
+ of immediate constants, it is sometimes impossible to reach the
+ register save area directly from the stack pointer. In that case,
+ a temporary register is used that is near enough to the register
+ save area, and the Canonical Frame Address, i.e., DWARF2's logical
+ frame pointer, register must (temporarily) be changed to be this
+ temporary register. So, the instruction that sets this temporary
+ register must be marked as `RTX_FRAME_RELATED_P'.
+
+ If the marked instruction is overly complex (defined in terms of
+ what `dwarf2out_frame_debug_expr' can handle), you will also have
+ to create a `REG_FRAME_RELATED_EXPR' note and attach it to the
+ instruction. This note should contain a simple expression of the
+ computation performed by this instruction, i.e., one that
+ `dwarf2out_frame_debug_expr' can handle.
+
+ This flag is required for exception handling support on targets
+ with RTL prologues.
+
+`RTX_INTEGRATED_P (X)'
+ Nonzero in an `insn', `insn_list', or `const' if it resulted from
+ an in-line function call. Stored in the `integrated' field and
+ printed as `/i'.
+
+`RTX_UNCHANGING_P (X)'
+ Nonzero in a `reg' or `mem' if the memory is set at most once,
+ anywhere. This does not mean that it is function invariant.
+ Stored in the `unchanging' field and printed as `/u'.
+
+`SCHED_GROUP_P (X)'
+ During instruction scheduling, in an `insn', indicates that the
+ previous insn must be scheduled together with this insn. This is
+ used to ensure that certain groups of instructions will not be
+ split up by the instruction scheduling pass, for example, `use'
+ insns before a `call_insn' may not be separated from the
+ `call_insn'. Stored in the `in_struct' field and printed as `/s'.
+
+`SET_IS_RETURN_P (X)'
+ For a `set', nonzero if it is for a return. Stored in the `jump'
+ field and printed as `/j'.
+
+`SIBLING_CALL_P (X)'
+ For a `call_insn', nonzero if the insn is a sibling call. Stored
+ in the `jump' field and printed as `/j'.
+
+`STRING_POOL_ADDRESS_P (X)'
+ For a `symbol_ref' expression, nonzero if it addresses this
+ function's string constant pool. Stored in the `frame_related'
+ field and printed as `/f'.
+
+`SUBREG_PROMOTED_UNSIGNED_P (X)'
+ Nonzero in a `subreg' that has `SUBREG_PROMOTED_VAR_P' nonzero if
+ the object being referenced is kept zero-extended and zero if it
+ is kept sign-extended. Stored in the `unchanging' field and
+ printed as `/u'.
+
+`SUBREG_PROMOTED_VAR_P (X)'
+ Nonzero in a `subreg' if it was made when accessing an object that
+ was promoted to a wider mode in accord with the `PROMOTED_MODE'
+ machine description macro (*note Storage Layout::). In this case,
+ the mode of the `subreg' is the declared mode of the object and
+ the mode of `SUBREG_REG' is the mode of the register that holds
+ the object. Promoted variables are always either sign- or
+ zero-extended to the wider mode on every assignment. Stored in
+ the `in_struct' field and printed as `/s'.
+
+`SYMBOL_REF_FLAG (X)'
+ In a `symbol_ref', this is used as a flag for machine-specific
+ purposes. Stored in the `volatil' field and printed as `/v'.
+
+`SYMBOL_REF_USED (X)'
+ In a `symbol_ref', indicates that X has been used. This is
+ normally only used to ensure that X is only declared external
+ once. Stored in the `used' field.
+
+`SYMBOL_REF_WEAK (X)'
+ In a `symbol_ref', indicates that X has been declared weak.
+ Stored in the `integrated' field and printed as `/i'.
+
+ These are the fields to which the above macros refer:
+
+`call'
+ In the `LOG_LINKS' of an `insn_list' during scheduling, 1 means
+ that the cost of executing an instruction through the link is zero.
+
+ In an RTL dump, this flag is represented as `/c'.
+
+`frame_related'
+ In an `insn' or `set' expression, 1 means that it is part of a
+ function prologue and sets the stack pointer, sets the frame
+ pointer, saves a register, or sets up a temporary register to use
+ in place of the frame pointer.
+
+ In `reg' expressions, 1 means that the register holds a pointer.
+
+ In `symbol_ref' expressions, 1 means that the reference addresses
+ this function's string constant pool.
+
+ In `mem' expressions, 1 means that the reference is to a scalar.
+
+ In an RTL dump, this flag is represented as `/f'.
+
+`in_struct'
+ In `mem' expressions, it is 1 if the memory datum referred to is
+ all or part of a structure or array; 0 if it is (or might be) a
+ scalar variable. A reference through a C pointer has 0 because
+ the pointer might point to a scalar variable. This information
+ allows the compiler to determine something about possible cases of
+ aliasing.
+
+ In `reg' expressions, it is 1 if the register has its entire life
+ contained within the test expression of some loop.
+
+ In `subreg' expressions, 1 means that the `subreg' is accessing an
+ object that has had its mode promoted from a wider mode.
+
+ In `label_ref' expressions, 1 means that the referenced label is
+ outside the innermost loop containing the insn in which the
+ `label_ref' was found.
+
+ In `code_label' expressions, it is 1 if the label may never be
+ deleted. This is used for labels which are the target of
+ non-local gotos. Such a label that would have been deleted is
+ replaced with a `note' of type `NOTE_INSN_DELETED_LABEL'.
+
+ In an `insn' during dead-code elimination, 1 means that the insn is
+ dead code.
+
+ In an `insn' during reorg for an insn in the delay slot of a
+ branch, 1 means that this insn is from the target of the branch.
+
+ In an `insn' during instruction scheduling, 1 means that this insn
+ must be scheduled as part of a group together with the previous
+ insn.
+
+ In an RTL dump, this flag is represented as `/s'.
+
+`integrated'
+ In an `insn', `insn_list', or `const', 1 means the RTL was
+ produced by procedure integration.
+
+ In `reg' expressions, 1 means the register contains the value to
+ be returned by the current function. On machines that pass
+ parameters in registers, the same register number may be used for
+ parameters as well, but this flag is not set on such uses.
+
+ In `symbol_ref' expressions, 1 means the referenced symbol is weak.
+
+ In an RTL dump, this flag is represented as `/i'.
+
+`jump'
+ In a `mem' expression, 1 means we should keep the alias set for
+ this mem unchanged when we access a component.
+
+ In a `set', 1 means it is for a return.
+
+ In a `call_insn', 1 means it is a sibling call.
+
+ In the `LOG_LINKS' of an `insn_list' during scheduling, 1 means the
+ cost of executing an instruction through the link varies and is
+ unchanging.
+
+ In an RTL dump, this flag is represented as `/j'.
+
+`unchanging'
+ In `reg' and `mem' expressions, 1 means that the value of the
+ expression never changes.
+
+ In `subreg' expressions, it is 1 if the `subreg' references an
+ unsigned object whose mode has been promoted to a wider mode.
+
+ In an `insn', 1 means that this is an annulling branch.
+
+ In a `symbol_ref' expression, 1 means that this symbol addresses
+ something in the per-function constant pool.
+
+ In a `call_insn', `note', or an `expr_list' of notes, 1 means that
+ this instruction is a call to a const or pure function.
+
+ In an RTL dump, this flag is represented as `/u'.
+
+`used'
+ This flag is used directly (without an access macro) at the end of
+ RTL generation for a function, to count the number of times an
+ expression appears in insns. Expressions that appear more than
+ once are copied, according to the rules for shared structure
+ (*note Sharing::).
+
+ For a `reg', it is used directly (without an access macro) by the
+ leaf register renumbering code to ensure that each register is only
+ renumbered once.
+
+ In a `symbol_ref', it indicates that an external declaration for
+ the symbol has already been written.
+
+`volatil'
+ In a `mem' or `asm_operands' expression, it is 1 if the memory
+ reference is volatile. Volatile memory references may not be
+ deleted, reordered or combined.
+
+ In a `symbol_ref' expression, it is used for machine-specific
+ purposes.
+
+ In a `reg' expression, it is 1 if the value is a user-level
+ variable. 0 indicates an internal compiler temporary.
+
+ In an `insn', 1 means the insn has been deleted.
+
+ In `label_ref' and `reg_label' expressions, 1 means a reference to
+ a non-local label.
+
+ In an RTL dump, this flag is represented as `/v'.
+
+\1f
+File: gccint.info, Node: Machine Modes, Next: Constants, Prev: Flags, Up: RTL
+
+8.5 Machine Modes
+=================
+
+A machine mode describes a size of data object and the representation
+used for it. In the C code, machine modes are represented by an
+enumeration type, `enum machine_mode', defined in `machmode.def'. Each
+RTL expression has room for a machine mode and so do certain kinds of
+tree expressions (declarations and types, to be precise).
+
+ In debugging dumps and machine descriptions, the machine mode of an
+RTL expression is written after the expression code with a colon to
+separate them. The letters `mode' which appear at the end of each
+machine mode name are omitted. For example, `(reg:SI 38)' is a `reg'
+expression with machine mode `SImode'. If the mode is `VOIDmode', it
+is not written at all.
+
+ Here is a table of machine modes. The term "byte" below refers to an
+object of `BITS_PER_UNIT' bits (*note Storage Layout::).
+
+`BImode'
+ "Bit" mode represents a single bit, for predicate registers.
+
+`QImode'
+ "Quarter-Integer" mode represents a single byte treated as an
+ integer.
+
+`HImode'
+ "Half-Integer" mode represents a two-byte integer.
+
+`PSImode'
+ "Partial Single Integer" mode represents an integer which occupies
+ four bytes but which doesn't really use all four. On some
+ machines, this is the right mode to use for pointers.
+
+`SImode'
+ "Single Integer" mode represents a four-byte integer.
+
+`PDImode'
+ "Partial Double Integer" mode represents an integer which occupies
+ eight bytes but which doesn't really use all eight. On some
+ machines, this is the right mode to use for certain pointers.
+
+`DImode'
+ "Double Integer" mode represents an eight-byte integer.
+
+`TImode'
+ "Tetra Integer" (?) mode represents a sixteen-byte integer.
+
+`OImode'
+ "Octa Integer" (?) mode represents a thirty-two-byte integer.
+
+`QFmode'
+ "Quarter-Floating" mode represents a quarter-precision (single
+ byte) floating point number.
+
+`HFmode'
+ "Half-Floating" mode represents a half-precision (two byte)
+ floating point number.
+
+`TQFmode'
+ "Three-Quarter-Floating" (?) mode represents a
+ three-quarter-precision (three byte) floating point number.
+
+`SFmode'
+ "Single Floating" mode represents a four byte floating point
+ number. In the common case, of a processor with IEEE arithmetic
+ and 8-bit bytes, this is a single-precision IEEE floating point
+ number; it can also be used for double-precision (on processors
+ with 16-bit bytes) and single-precision VAX and IBM types.
+
+`DFmode'
+ "Double Floating" mode represents an eight byte floating point
+ number. In the common case, of a processor with IEEE arithmetic
+ and 8-bit bytes, this is a double-precision IEEE floating point
+ number.
+
+`XFmode'
+ "Extended Floating" mode represents a twelve byte floating point
+ number. This mode is used for IEEE extended floating point. On
+ some systems not all bits within these bytes will actually be used.
+
+`TFmode'
+ "Tetra Floating" mode represents a sixteen byte floating point
+ number. This gets used for both the 96-bit extended IEEE
+ floating-point types padded to 128 bits, and true 128-bit extended
+ IEEE floating-point types.
+
+`CCmode'
+ "Condition Code" mode represents the value of a condition code,
+ which is a machine-specific set of bits used to represent the
+ result of a comparison operation. Other machine-specific modes
+ may also be used for the condition code. These modes are not used
+ on machines that use `cc0' (see *note Condition Code::).
+
+`BLKmode'
+ "Block" mode represents values that are aggregates to which none of
+ the other modes apply. In RTL, only memory references can have
+ this mode, and only if they appear in string-move or vector
+ instructions. On machines which have no such instructions,
+ `BLKmode' will not appear in RTL.
+
+`VOIDmode'
+ Void mode means the absence of a mode or an unspecified mode. For
+ example, RTL expressions of code `const_int' have mode `VOIDmode'
+ because they can be taken to have whatever mode the context
+ requires. In debugging dumps of RTL, `VOIDmode' is expressed by
+ the absence of any mode.
+
+`QCmode, HCmode, SCmode, DCmode, XCmode, TCmode'
+ These modes stand for a complex number represented as a pair of
+ floating point values. The floating point values are in `QFmode',
+ `HFmode', `SFmode', `DFmode', `XFmode', and `TFmode', respectively.
+
+`CQImode, CHImode, CSImode, CDImode, CTImode, COImode'
+ These modes stand for a complex number represented as a pair of
+ integer values. The integer values are in `QImode', `HImode',
+ `SImode', `DImode', `TImode', and `OImode', respectively.
+
+ The machine description defines `Pmode' as a C macro which expands
+into the machine mode used for addresses. Normally this is the mode
+whose size is `BITS_PER_WORD', `SImode' on 32-bit machines.
+
+ The only modes which a machine description must support are
+`QImode', and the modes corresponding to `BITS_PER_WORD',
+`FLOAT_TYPE_SIZE' and `DOUBLE_TYPE_SIZE'. The compiler will attempt to
+use `DImode' for 8-byte structures and unions, but this can be
+prevented by overriding the definition of `MAX_FIXED_MODE_SIZE'.
+Alternatively, you can have the compiler use `TImode' for 16-byte
+structures and unions. Likewise, you can arrange for the C type `short
+int' to avoid using `HImode'.
+
+ Very few explicit references to machine modes remain in the compiler
+and these few references will soon be removed. Instead, the machine
+modes are divided into mode classes. These are represented by the
+enumeration type `enum mode_class' defined in `machmode.h'. The
+possible mode classes are:
+
+`MODE_INT'
+ Integer modes. By default these are `BImode', `QImode', `HImode',
+ `SImode', `DImode', `TImode', and `OImode'.
+
+`MODE_PARTIAL_INT'
+ The "partial integer" modes, `PQImode', `PHImode', `PSImode' and
+ `PDImode'.
+
+`MODE_FLOAT'
+ Floating point modes. By default these are `QFmode', `HFmode',
+ `TQFmode', `SFmode', `DFmode', `XFmode' and `TFmode'.
+
+`MODE_COMPLEX_INT'
+ Complex integer modes. (These are not currently implemented).
+
+`MODE_COMPLEX_FLOAT'
+ Complex floating point modes. By default these are `QCmode',
+ `HCmode', `SCmode', `DCmode', `XCmode', and `TCmode'.
+
+`MODE_FUNCTION'
+ Algol or Pascal function variables including a static chain.
+ (These are not currently implemented).
+
+`MODE_CC'
+ Modes representing condition code values. These are `CCmode' plus
+ any modes listed in the `EXTRA_CC_MODES' macro. *Note Jump
+ Patterns::, also see *note Condition Code::.
+
+`MODE_RANDOM'
+ This is a catchall mode class for modes which don't fit into the
+ above classes. Currently `VOIDmode' and `BLKmode' are in
+ `MODE_RANDOM'.
+
+ Here are some C macros that relate to machine modes:
+
+`GET_MODE (X)'
+ Returns the machine mode of the RTX X.
+
+`PUT_MODE (X, NEWMODE)'
+ Alters the machine mode of the RTX X to be NEWMODE.
+
+`NUM_MACHINE_MODES'
+ Stands for the number of machine modes available on the target
+ machine. This is one greater than the largest numeric value of any
+ machine mode.
+
+`GET_MODE_NAME (M)'
+ Returns the name of mode M as a string.
+
+`GET_MODE_CLASS (M)'
+ Returns the mode class of mode M.
+
+`GET_MODE_WIDER_MODE (M)'
+ Returns the next wider natural mode. For example, the expression
+ `GET_MODE_WIDER_MODE (QImode)' returns `HImode'.
+
+`GET_MODE_SIZE (M)'
+ Returns the size in bytes of a datum of mode M.
+
+`GET_MODE_BITSIZE (M)'
+ Returns the size in bits of a datum of mode M.
+
+`GET_MODE_MASK (M)'
+ Returns a bitmask containing 1 for all bits in a word that fit
+ within mode M. This macro can only be used for modes whose
+ bitsize is less than or equal to `HOST_BITS_PER_INT'.
+
+`GET_MODE_ALIGNMENT (M)'
+ Return the required alignment, in bits, for an object of mode M.
+
+`GET_MODE_UNIT_SIZE (M)'
+ Returns the size in bytes of the subunits of a datum of mode M.
+ This is the same as `GET_MODE_SIZE' except in the case of complex
+ modes. For them, the unit size is the size of the real or
+ imaginary part.
+
+`GET_MODE_NUNITS (M)'
+ Returns the number of units contained in a mode, i.e.,
+ `GET_MODE_SIZE' divided by `GET_MODE_UNIT_SIZE'.
+
+`GET_CLASS_NARROWEST_MODE (C)'
+ Returns the narrowest mode in mode class C.
+
+ The global variables `byte_mode' and `word_mode' contain modes whose
+classes are `MODE_INT' and whose bitsizes are either `BITS_PER_UNIT' or
+`BITS_PER_WORD', respectively. On 32-bit machines, these are `QImode'
+and `SImode', respectively.
+
+\1f
+File: gccint.info, Node: Constants, Next: Regs and Memory, Prev: Machine Modes, Up: RTL
+
+8.6 Constant Expression Types
+=============================
+
+The simplest RTL expressions are those that represent constant values.
+
+`(const_int I)'
+ This type of expression represents the integer value I. I is
+ customarily accessed with the macro `INTVAL' as in `INTVAL (EXP)',
+ which is equivalent to `XWINT (EXP, 0)'.
+
+ There is only one expression object for the integer value zero; it
+ is the value of the variable `const0_rtx'. Likewise, the only
+ expression for integer value one is found in `const1_rtx', the only
+ expression for integer value two is found in `const2_rtx', and the
+ only expression for integer value negative one is found in
+ `constm1_rtx'. Any attempt to create an expression of code
+ `const_int' and value zero, one, two or negative one will return
+ `const0_rtx', `const1_rtx', `const2_rtx' or `constm1_rtx' as
+ appropriate.
+
+ Similarly, there is only one object for the integer whose value is
+ `STORE_FLAG_VALUE'. It is found in `const_true_rtx'. If
+ `STORE_FLAG_VALUE' is one, `const_true_rtx' and `const1_rtx' will
+ point to the same object. If `STORE_FLAG_VALUE' is -1,
+ `const_true_rtx' and `constm1_rtx' will point to the same object.
+
+`(const_double:M ADDR I0 I1 ...)'
+ Represents either a floating-point constant of mode M or an
+ integer constant too large to fit into `HOST_BITS_PER_WIDE_INT'
+ bits but small enough to fit within twice that number of bits (GCC
+ does not provide a mechanism to represent even larger constants).
+ In the latter case, M will be `VOIDmode'.
+
+`(const_vector:M [X0 X1 ...])'
+ Represents a vector constant. The square brackets stand for the
+ vector containing the constant elements. X0, X1 and so on are the
+ `const_int' or `const_double' elements.
+
+ The number of units in a `const_vector' is obtained with the macro
+ `CONST_VECTOR_NUNITS' as in `CONST_VECTOR_NUNITS (V)'.
+
+ Individual elements in a vector constant are accessed with the
+ macro `CONST_VECTOR_ELT' as in `CONST_VECTOR_ELT (V, N)' where V
+ is the vector constant and N is the element desired.
+
+ ADDR is used to contain the `mem' expression that corresponds to
+ the location in memory that at which the constant can be found. If
+ it has not been allocated a memory location, but is on the chain
+ of all `const_double' expressions in this compilation (maintained
+ using an undisplayed field), ADDR contains `const0_rtx'. If it is
+ not on the chain, ADDR contains `cc0_rtx'. ADDR is customarily
+ accessed with the macro `CONST_DOUBLE_MEM' and the chain field via
+ `CONST_DOUBLE_CHAIN'.
+
+ If M is `VOIDmode', the bits of the value are stored in I0 and I1.
+ I0 is customarily accessed with the macro `CONST_DOUBLE_LOW' and
+ I1 with `CONST_DOUBLE_HIGH'.
+
+ If the constant is floating point (regardless of its precision),
+ then the number of integers used to store the value depends on the
+ size of `REAL_VALUE_TYPE' (*note Cross-compilation::). The
+ integers represent a floating point number, but not precisely in
+ the target machine's or host machine's floating point format. To
+ convert them to the precise bit pattern used by the target
+ machine, use the macro `REAL_VALUE_TO_TARGET_DOUBLE' and friends
+ (*note Data Output::).
+
+ The macro `CONST0_RTX (MODE)' refers to an expression with value 0
+ in mode MODE. If mode MODE is of mode class `MODE_INT', it
+ returns `const0_rtx'. If mode MODE is of mode class `MODE_FLOAT',
+ it returns a `CONST_DOUBLE' expression in mode MODE. Otherwise,
+ it returns a `CONST_VECTOR' expression in mode MODE. Similarly,
+ the macro `CONST1_RTX (MODE)' refers to an expression with value 1
+ in mode MODE and similarly for `CONST2_RTX'. The `CONST1_RTX' and
+ `CONST2_RTX' macros are undefined for vector modes.
+
+`(const_string STR)'
+ Represents a constant string with value STR. Currently this is
+ used only for insn attributes (*note Insn Attributes::) since
+ constant strings in C are placed in memory.
+
+`(symbol_ref:MODE SYMBOL)'
+ Represents the value of an assembler label for data. SYMBOL is a
+ string that describes the name of the assembler label. If it
+ starts with a `*', the label is the rest of SYMBOL not including
+ the `*'. Otherwise, the label is SYMBOL, usually prefixed with
+ `_'.
+
+ The `symbol_ref' contains a mode, which is usually `Pmode'.
+ Usually that is the only mode for which a symbol is directly valid.
+
+`(label_ref LABEL)'
+ Represents the value of an assembler label for code. It contains
+ one operand, an expression, which must be a `code_label' or a
+ `note' of type `NOTE_INSN_DELETED_LABEL' that appears in the
+ instruction sequence to identify the place where the label should
+ go.
+
+ The reason for using a distinct expression type for code label
+ references is so that jump optimization can distinguish them.
+
+`(const:M EXP)'
+ Represents a constant that is the result of an assembly-time
+ arithmetic computation. The operand, EXP, is an expression that
+ contains only constants (`const_int', `symbol_ref' and `label_ref'
+ expressions) combined with `plus' and `minus'. However, not all
+ combinations are valid, since the assembler cannot do arbitrary
+ arithmetic on relocatable symbols.
+
+ M should be `Pmode'.
+
+`(high:M EXP)'
+ Represents the high-order bits of EXP, usually a `symbol_ref'.
+ The number of bits is machine-dependent and is normally the number
+ of bits specified in an instruction that initializes the high
+ order bits of a register. It is used with `lo_sum' to represent
+ the typical two-instruction sequence used in RISC machines to
+ reference a global memory location.
+
+ M should be `Pmode'.
+
+\1f
+File: gccint.info, Node: Regs and Memory, Next: Arithmetic, Prev: Constants, Up: RTL
+
+8.7 Registers and Memory
+========================
+
+Here are the RTL expression types for describing access to machine
+registers and to main memory.
+
+`(reg:M N)'
+ For small values of the integer N (those that are less than
+ `FIRST_PSEUDO_REGISTER'), this stands for a reference to machine
+ register number N: a "hard register". For larger values of N, it
+ stands for a temporary value or "pseudo register". The compiler's
+ strategy is to generate code assuming an unlimited number of such
+ pseudo registers, and later convert them into hard registers or
+ into memory references.
+
+ M is the machine mode of the reference. It is necessary because
+ machines can generally refer to each register in more than one
+ mode. For example, a register may contain a full word but there
+ may be instructions to refer to it as a half word or as a single
+ byte, as well as instructions to refer to it as a floating point
+ number of various precisions.
+
+ Even for a register that the machine can access in only one mode,
+ the mode must always be specified.
+
+ The symbol `FIRST_PSEUDO_REGISTER' is defined by the machine
+ description, since the number of hard registers on the machine is
+ an invariant characteristic of the machine. Note, however, that
+ not all of the machine registers must be general registers. All
+ the machine registers that can be used for storage of data are
+ given hard register numbers, even those that can be used only in
+ certain instructions or can hold only certain types of data.
+
+ A hard register may be accessed in various modes throughout one
+ function, but each pseudo register is given a natural mode and is
+ accessed only in that mode. When it is necessary to describe an
+ access to a pseudo register using a nonnatural mode, a `subreg'
+ expression is used.
+
+ A `reg' expression with a machine mode that specifies more than
+ one word of data may actually stand for several consecutive
+ registers. If in addition the register number specifies a
+ hardware register, then it actually represents several consecutive
+ hardware registers starting with the specified one.
+
+ Each pseudo register number used in a function's RTL code is
+ represented by a unique `reg' expression.
+
+ Some pseudo register numbers, those within the range of
+ `FIRST_VIRTUAL_REGISTER' to `LAST_VIRTUAL_REGISTER' only appear
+ during the RTL generation phase and are eliminated before the
+ optimization phases. These represent locations in the stack frame
+ that cannot be determined until RTL generation for the function
+ has been completed. The following virtual register numbers are
+ defined:
+
+ `VIRTUAL_INCOMING_ARGS_REGNUM'
+ This points to the first word of the incoming arguments
+ passed on the stack. Normally these arguments are placed
+ there by the caller, but the callee may have pushed some
+ arguments that were previously passed in registers.
+
+ When RTL generation is complete, this virtual register is
+ replaced by the sum of the register given by
+ `ARG_POINTER_REGNUM' and the value of `FIRST_PARM_OFFSET'.
+
+ `VIRTUAL_STACK_VARS_REGNUM'
+ If `FRAME_GROWS_DOWNWARD' is defined, this points to
+ immediately above the first variable on the stack.
+ Otherwise, it points to the first variable on the stack.
+
+ `VIRTUAL_STACK_VARS_REGNUM' is replaced with the sum of the
+ register given by `FRAME_POINTER_REGNUM' and the value
+ `STARTING_FRAME_OFFSET'.
+
+ `VIRTUAL_STACK_DYNAMIC_REGNUM'
+ This points to the location of dynamically allocated memory
+ on the stack immediately after the stack pointer has been
+ adjusted by the amount of memory desired.
+
+ This virtual register is replaced by the sum of the register
+ given by `STACK_POINTER_REGNUM' and the value
+ `STACK_DYNAMIC_OFFSET'.
+
+ `VIRTUAL_OUTGOING_ARGS_REGNUM'
+ This points to the location in the stack at which outgoing
+ arguments should be written when the stack is pre-pushed
+ (arguments pushed using push insns should always use
+ `STACK_POINTER_REGNUM').
+
+ This virtual register is replaced by the sum of the register
+ given by `STACK_POINTER_REGNUM' and the value
+ `STACK_POINTER_OFFSET'.
+
+`(subreg:M REG BYTENUM)'
+ `subreg' expressions are used to refer to a register in a machine
+ mode other than its natural one, or to refer to one register of a
+ multi-part `reg' that actually refers to several registers.
+
+ Each pseudo-register has a natural mode. If it is necessary to
+ operate on it in a different mode--for example, to perform a
+ fullword move instruction on a pseudo-register that contains a
+ single byte--the pseudo-register must be enclosed in a `subreg'.
+ In such a case, BYTENUM is zero.
+
+ Usually M is at least as narrow as the mode of REG, in which case
+ it is restricting consideration to only the bits of REG that are
+ in M.
+
+ Sometimes M is wider than the mode of REG. These `subreg'
+ expressions are often called "paradoxical". They are used in
+ cases where we want to refer to an object in a wider mode but do
+ not care what value the additional bits have. The reload pass
+ ensures that paradoxical references are only made to hard
+ registers.
+
+ The other use of `subreg' is to extract the individual registers of
+ a multi-register value. Machine modes such as `DImode' and
+ `TImode' can indicate values longer than a word, values which
+ usually require two or more consecutive registers. To access one
+ of the registers, use a `subreg' with mode `SImode' and a BYTENUM
+ offset that says which register.
+
+ Storing in a non-paradoxical `subreg' has undefined results for
+ bits belonging to the same word as the `subreg'. This laxity makes
+ it easier to generate efficient code for such instructions. To
+ represent an instruction that preserves all the bits outside of
+ those in the `subreg', use `strict_low_part' around the `subreg'.
+
+ The compilation parameter `WORDS_BIG_ENDIAN', if set to 1, says
+ that byte number zero is part of the most significant word;
+ otherwise, it is part of the least significant word.
+
+ The compilation parameter `BYTES_BIG_ENDIAN', if set to 1, says
+ that byte number zero is the most significant byte within a word;
+ otherwise, it is the least significant byte within a word.
+
+ On a few targets, `FLOAT_WORDS_BIG_ENDIAN' disagrees with
+ `WORDS_BIG_ENDIAN'. However, most parts of the compiler treat
+ floating point values as if they had the same endianness as
+ integer values. This works because they handle them solely as a
+ collection of integer values, with no particular numerical value.
+ Only real.c and the runtime libraries care about
+ `FLOAT_WORDS_BIG_ENDIAN'.
+
+ Between the combiner pass and the reload pass, it is possible to
+ have a paradoxical `subreg' which contains a `mem' instead of a
+ `reg' as its first operand. After the reload pass, it is also
+ possible to have a non-paradoxical `subreg' which contains a
+ `mem'; this usually occurs when the `mem' is a stack slot which
+ replaced a pseudo register.
+
+ Note that it is not valid to access a `DFmode' value in `SFmode'
+ using a `subreg'. On some machines the most significant part of a
+ `DFmode' value does not have the same format as a single-precision
+ floating value.
+
+ It is also not valid to access a single word of a multi-word value
+ in a hard register when less registers can hold the value than
+ would be expected from its size. For example, some 32-bit
+ machines have floating-point registers that can hold an entire
+ `DFmode' value. If register 10 were such a register `(subreg:SI
+ (reg:DF 10) 1)' would be invalid because there is no way to
+ convert that reference to a single machine register. The reload
+ pass prevents `subreg' expressions such as these from being formed.
+
+ The first operand of a `subreg' expression is customarily accessed
+ with the `SUBREG_REG' macro and the second operand is customarily
+ accessed with the `SUBREG_BYTE' macro.
+
+`(scratch:M)'
+ This represents a scratch register that will be required for the
+ execution of a single instruction and not used subsequently. It is
+ converted into a `reg' by either the local register allocator or
+ the reload pass.
+
+ `scratch' is usually present inside a `clobber' operation (*note
+ Side Effects::).
+
+`(cc0)'
+ This refers to the machine's condition code register. It has no
+ operands and may not have a machine mode. There are two ways to
+ use it:
+
+ * To stand for a complete set of condition code flags. This is
+ best on most machines, where each comparison sets the entire
+ series of flags.
+
+ With this technique, `(cc0)' may be validly used in only two
+ contexts: as the destination of an assignment (in test and
+ compare instructions) and in comparison operators comparing
+ against zero (`const_int' with value zero; that is to say,
+ `const0_rtx').
+
+ * To stand for a single flag that is the result of a single
+ condition. This is useful on machines that have only a
+ single flag bit, and in which comparison instructions must
+ specify the condition to test.
+
+ With this technique, `(cc0)' may be validly used in only two
+ contexts: as the destination of an assignment (in test and
+ compare instructions) where the source is a comparison
+ operator, and as the first operand of `if_then_else' (in a
+ conditional branch).
+
+ There is only one expression object of code `cc0'; it is the value
+ of the variable `cc0_rtx'. Any attempt to create an expression of
+ code `cc0' will return `cc0_rtx'.
+
+ Instructions can set the condition code implicitly. On many
+ machines, nearly all instructions set the condition code based on
+ the value that they compute or store. It is not necessary to
+ record these actions explicitly in the RTL because the machine
+ description includes a prescription for recognizing the
+ instructions that do so (by means of the macro
+ `NOTICE_UPDATE_CC'). *Note Condition Code::. Only instructions
+ whose sole purpose is to set the condition code, and instructions
+ that use the condition code, need mention `(cc0)'.
+
+ On some machines, the condition code register is given a register
+ number and a `reg' is used instead of `(cc0)'. This is usually the
+ preferable approach if only a small subset of instructions modify
+ the condition code. Other machines store condition codes in
+ general registers; in such cases a pseudo register should be used.
+
+ Some machines, such as the Sparc and RS/6000, have two sets of
+ arithmetic instructions, one that sets and one that does not set
+ the condition code. This is best handled by normally generating
+ the instruction that does not set the condition code, and making a
+ pattern that both performs the arithmetic and sets the condition
+ code register (which would not be `(cc0)' in this case). For
+ examples, search for `addcc' and `andcc' in `sparc.md'.
+
+`(pc)'
+ This represents the machine's program counter. It has no operands
+ and may not have a machine mode. `(pc)' may be validly used only
+ in certain specific contexts in jump instructions.
+
+ There is only one expression object of code `pc'; it is the value
+ of the variable `pc_rtx'. Any attempt to create an expression of
+ code `pc' will return `pc_rtx'.
+
+ All instructions that do not jump alter the program counter
+ implicitly by incrementing it, but there is no need to mention
+ this in the RTL.
+
+`(mem:M ADDR ALIAS)'
+ This RTX represents a reference to main memory at an address
+ represented by the expression ADDR. M specifies how large a unit
+ of memory is accessed. ALIAS specifies an alias set for the
+ reference. In general two items are in different alias sets if
+ they cannot reference the same memory address.
+
+`(addressof:M REG)'
+ This RTX represents a request for the address of register REG.
+ Its mode is always `Pmode'. If there are any `addressof'
+ expressions left in the function after CSE, REG is forced into the
+ stack and the `addressof' expression is replaced with a `plus'
+ expression for the address of its stack slot.
+
+\1f
+File: gccint.info, Node: Arithmetic, Next: Comparisons, Prev: Regs and Memory, Up: RTL
+
+8.8 RTL Expressions for Arithmetic
+==================================
+
+Unless otherwise specified, all the operands of arithmetic expressions
+must be valid for mode M. An operand is valid for mode M if it has
+mode M, or if it is a `const_int' or `const_double' and M is a mode of
+class `MODE_INT'.
+
+ For commutative binary operations, constants should be placed in the
+second operand.
+
+`(plus:M X Y)'
+ Represents the sum of the values represented by X and Y carried
+ out in machine mode M.
+
+`(lo_sum:M X Y)'
+ Like `plus', except that it represents that sum of X and the
+ low-order bits of Y. The number of low order bits is
+ machine-dependent but is normally the number of bits in a `Pmode'
+ item minus the number of bits set by the `high' code (*note
+ Constants::).
+
+ M should be `Pmode'.
+
+`(minus:M X Y)'
+ Like `plus' but represents subtraction.
+
+`(ss_plus:M X Y)'
+ Like `plus', but using signed saturation in case of an overflow.
+
+`(us_plus:M X Y)'
+ Like `plus', but using unsigned saturation in case of an overflow.
+
+`(ss_minus:M X Y)'
+ Like `minus', but using signed saturation in case of an overflow.
+
+`(us_minus:M X Y)'
+ Like `minus', but using unsigned saturation in case of an overflow.
+
+`(compare:M X Y)'
+ Represents the result of subtracting Y from X for purposes of
+ comparison. The result is computed without overflow, as if with
+ infinite precision.
+
+ Of course, machines can't really subtract with infinite precision.
+ However, they can pretend to do so when only the sign of the
+ result will be used, which is the case when the result is stored
+ in the condition code. And that is the _only_ way this kind of
+ expression may validly be used: as a value to be stored in the
+ condition codes, either `(cc0)' or a register. *Note
+ Comparisons::.
+
+ The mode M is not related to the modes of X and Y, but instead is
+ the mode of the condition code value. If `(cc0)' is used, it is
+ `VOIDmode'. Otherwise it is some mode in class `MODE_CC', often
+ `CCmode'. *Note Condition Code::. If M is `VOIDmode' or
+ `CCmode', the operation returns sufficient information (in an
+ unspecified format) so that any comparison operator can be applied
+ to the result of the `COMPARE' operation. For other modes in
+ class `MODE_CC', the operation only returns a subset of this
+ information.
+
+ Normally, X and Y must have the same mode. Otherwise, `compare'
+ is valid only if the mode of X is in class `MODE_INT' and Y is a
+ `const_int' or `const_double' with mode `VOIDmode'. The mode of X
+ determines what mode the comparison is to be done in; thus it must
+ not be `VOIDmode'.
+
+ If one of the operands is a constant, it should be placed in the
+ second operand and the comparison code adjusted as appropriate.
+
+ A `compare' specifying two `VOIDmode' constants is not valid since
+ there is no way to know in what mode the comparison is to be
+ performed; the comparison must either be folded during the
+ compilation or the first operand must be loaded into a register
+ while its mode is still known.
+
+`(neg:M X)'
+ Represents the negation (subtraction from zero) of the value
+ represented by X, carried out in mode M.
+
+`(mult:M X Y)'
+ Represents the signed product of the values represented by X and Y
+ carried out in machine mode M.
+
+ Some machines support a multiplication that generates a product
+ wider than the operands. Write the pattern for this as
+
+ (mult:M (sign_extend:M X) (sign_extend:M Y))
+
+ where M is wider than the modes of X and Y, which need not be the
+ same.
+
+ For unsigned widening multiplication, use the same idiom, but with
+ `zero_extend' instead of `sign_extend'.
+
+`(div:M X Y)'
+ Represents the quotient in signed division of X by Y, carried out
+ in machine mode M. If M is a floating point mode, it represents
+ the exact quotient; otherwise, the integerized quotient.
+
+ Some machines have division instructions in which the operands and
+ quotient widths are not all the same; you should represent such
+ instructions using `truncate' and `sign_extend' as in,
+
+ (truncate:M1 (div:M2 X (sign_extend:M2 Y)))
+
+`(udiv:M X Y)'
+ Like `div' but represents unsigned division.
+
+`(mod:M X Y)'
+`(umod:M X Y)'
+ Like `div' and `udiv' but represent the remainder instead of the
+ quotient.
+
+`(smin:M X Y)'
+`(smax:M X Y)'
+ Represents the smaller (for `smin') or larger (for `smax') of X
+ and Y, interpreted as signed integers in mode M.
+
+`(umin:M X Y)'
+`(umax:M X Y)'
+ Like `smin' and `smax', but the values are interpreted as unsigned
+ integers.
+
+`(not:M X)'
+ Represents the bitwise complement of the value represented by X,
+ carried out in mode M, which must be a fixed-point machine mode.
+
+`(and:M X Y)'
+ Represents the bitwise logical-and of the values represented by X
+ and Y, carried out in machine mode M, which must be a fixed-point
+ machine mode.
+
+`(ior:M X Y)'
+ Represents the bitwise inclusive-or of the values represented by X
+ and Y, carried out in machine mode M, which must be a fixed-point
+ mode.
+
+`(xor:M X Y)'
+ Represents the bitwise exclusive-or of the values represented by X
+ and Y, carried out in machine mode M, which must be a fixed-point
+ mode.
+
+`(ashift:M X C)'
+ Represents the result of arithmetically shifting X left by C
+ places. X have mode M, a fixed-point machine mode. C be a
+ fixed-point mode or be a constant with mode `VOIDmode'; which mode
+ is determined by the mode called for in the machine description
+ entry for the left-shift instruction. For example, on the VAX,
+ the mode of C is `QImode' regardless of M.
+
+`(lshiftrt:M X C)'
+`(ashiftrt:M X C)'
+ Like `ashift' but for right shift. Unlike the case for left shift,
+ these two operations are distinct.
+
+`(rotate:M X C)'
+`(rotatert:M X C)'
+ Similar but represent left and right rotate. If C is a constant,
+ use `rotate'.
+
+`(abs:M X)'
+ Represents the absolute value of X, computed in mode M.
+
+`(sqrt:M X)'
+ Represents the square root of X, computed in mode M. Most often M
+ will be a floating point mode.
+
+`(ffs:M X)'
+ Represents one plus the index of the least significant 1-bit in X,
+ represented as an integer of mode M. (The value is zero if X is
+ zero.) The mode of X need not be M; depending on the target
+ machine, various mode combinations may be valid.
+
+\1f
+File: gccint.info, Node: Comparisons, Next: Bit-Fields, Prev: Arithmetic, Up: RTL
+
+8.9 Comparison Operations
+=========================
+
+Comparison operators test a relation on two operands and are considered
+to represent a machine-dependent nonzero value described by, but not
+necessarily equal to, `STORE_FLAG_VALUE' (*note Misc::) if the relation
+holds, or zero if it does not. The mode of the comparison operation is
+independent of the mode of the data being compared. If the comparison
+operation is being tested (e.g., the first operand of an
+`if_then_else'), the mode must be `VOIDmode'. If the comparison
+operation is producing data to be stored in some variable, the mode
+must be in class `MODE_INT'. All comparison operations producing data
+must use the same mode, which is machine-specific.
+
+ There are two ways that comparison operations may be used. The
+comparison operators may be used to compare the condition codes `(cc0)'
+against zero, as in `(eq (cc0) (const_int 0))'. Such a construct
+actually refers to the result of the preceding instruction in which the
+condition codes were set. The instruction setting the condition code
+must be adjacent to the instruction using the condition code; only
+`note' insns may separate them.
+
+ Alternatively, a comparison operation may directly compare two data
+objects. The mode of the comparison is determined by the operands; they
+must both be valid for a common machine mode. A comparison with both
+operands constant would be invalid as the machine mode could not be
+deduced from it, but such a comparison should never exist in RTL due to
+constant folding.
+
+ In the example above, if `(cc0)' were last set to `(compare X Y)',
+the comparison operation is identical to `(eq X Y)'. Usually only one
+style of comparisons is supported on a particular machine, but the
+combine pass will try to merge the operations to produce the `eq' shown
+in case it exists in the context of the particular insn involved.
+
+ Inequality comparisons come in two flavors, signed and unsigned.
+Thus, there are distinct expression codes `gt' and `gtu' for signed and
+unsigned greater-than. These can produce different results for the same
+pair of integer values: for example, 1 is signed greater-than -1 but not
+unsigned greater-than, because -1 when regarded as unsigned is actually
+`0xffffffff' which is greater than 1.
+
+ The signed comparisons are also used for floating point values.
+Floating point comparisons are distinguished by the machine modes of
+the operands.
+
+`(eq:M X Y)'
+ `STORE_FLAG_VALUE' if the values represented by X and Y are equal,
+ otherwise 0.
+
+`(ne:M X Y)'
+ `STORE_FLAG_VALUE' if the values represented by X and Y are not
+ equal, otherwise 0.
+
+`(gt:M X Y)'
+ `STORE_FLAG_VALUE' if the X is greater than Y. If they are
+ fixed-point, the comparison is done in a signed sense.
+
+`(gtu:M X Y)'
+ Like `gt' but does unsigned comparison, on fixed-point numbers
+ only.
+
+`(lt:M X Y)'
+`(ltu:M X Y)'
+ Like `gt' and `gtu' but test for "less than".
+
+`(ge:M X Y)'
+`(geu:M X Y)'
+ Like `gt' and `gtu' but test for "greater than or equal".
+
+`(le:M X Y)'
+`(leu:M X Y)'
+ Like `gt' and `gtu' but test for "less than or equal".
+
+`(if_then_else COND THEN ELSE)'
+ This is not a comparison operation but is listed here because it is
+ always used in conjunction with a comparison operation. To be
+ precise, COND is a comparison expression. This expression
+ represents a choice, according to COND, between the value
+ represented by THEN and the one represented by ELSE.
+
+ On most machines, `if_then_else' expressions are valid only to
+ express conditional jumps.
+
+`(cond [TEST1 VALUE1 TEST2 VALUE2 ...] DEFAULT)'
+ Similar to `if_then_else', but more general. Each of TEST1,
+ TEST2, ... is performed in turn. The result of this expression is
+ the VALUE corresponding to the first nonzero test, or DEFAULT if
+ none of the tests are nonzero expressions.
+
+ This is currently not valid for instruction patterns and is
+ supported only for insn attributes. *Note Insn Attributes::.
+
+\1f
+File: gccint.info, Node: Bit-Fields, Next: Vector Operations, Prev: Comparisons, Up: RTL
+
+8.10 Bit-Fields
+===============
+
+Special expression codes exist to represent bit-field instructions.
+These types of expressions are lvalues in RTL; they may appear on the
+left side of an assignment, indicating insertion of a value into the
+specified bit-field.
+
+`(sign_extract:M LOC SIZE POS)'
+ This represents a reference to a sign-extended bit-field contained
+ or starting in LOC (a memory or register reference). The bit-field
+ is SIZE bits wide and starts at bit POS. The compilation option
+ `BITS_BIG_ENDIAN' says which end of the memory unit POS counts
+ from.
+
+ If LOC is in memory, its mode must be a single-byte integer mode.
+ If LOC is in a register, the mode to use is specified by the
+ operand of the `insv' or `extv' pattern (*note Standard Names::)
+ and is usually a full-word integer mode, which is the default if
+ none is specified.
+
+ The mode of POS is machine-specific and is also specified in the
+ `insv' or `extv' pattern.
+
+ The mode M is the same as the mode that would be used for LOC if
+ it were a register.
+
+`(zero_extract:M LOC SIZE POS)'
+ Like `sign_extract' but refers to an unsigned or zero-extended
+ bit-field. The same sequence of bits are extracted, but they are
+ filled to an entire word with zeros instead of by sign-extension.
+
+\1f
+File: gccint.info, Node: Vector Operations, Next: Conversions, Prev: Bit-Fields, Up: RTL
+
+8.11 Vector Operations
+======================
+
+All normal RTL expressions can be used with vector modes; they are
+interpreted as operating on each part of the vector independently.
+Additionally, there are a few new expressions to describe specific
+vector operations.
+
+`(vec_merge:M VEC1 VEC2 ITEMS)'
+ This describes a merge operation between two vectors. The result
+ is a vector of mode M; its elements are selected from either VEC1
+ or VEC2. Which elements are selected is described by ITEMS, which
+ is a bit mask represented by a `const_int'; a zero bit indicates
+ the corresponding element in the result vector is taken from VEC2
+ while a set bit indicates it is taken from VEC1.
+
+`(vec_select:M VEC1 SELECTION)'
+ This describes an operation that selects parts of a vector. VEC1
+ is the source vector, SELECTION is a `parallel' that contains a
+ `const_int' for each of the subparts of the result vector, giving
+ the number of the source subpart that should be stored into it.
+
+`(vec_concat:M VEC1 VEC2)'
+ Describes a vector concat operation. The result is a
+ concatenation of the vectors VEC1 and VEC2; its length is the sum
+ of the lengths of the two inputs.
+
+`(vec_const:M SUBPARTS)'
+ This describes a constant vector. SUBPARTS is a `parallel' that
+ contains a constant for each of the subparts of the vector.
+
+`(vec_duplicate:M VEC)'
+ This operation converts a small vector into a larger one by
+ duplicating the input values. The output vector mode must have
+ the same submodes as the input vector mode, and the number of
+ output parts must be an integer multiple of the number of input
+ parts.
+
+
+\1f
+File: gccint.info, Node: Conversions, Next: RTL Declarations, Prev: Vector Operations, Up: RTL
+
+8.12 Conversions
+================
+
+All conversions between machine modes must be represented by explicit
+conversion operations. For example, an expression which is the sum of
+a byte and a full word cannot be written as `(plus:SI (reg:QI 34)
+(reg:SI 80))' because the `plus' operation requires two operands of the
+same machine mode. Therefore, the byte-sized operand is enclosed in a
+conversion operation, as in
+
+ (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
+
+ The conversion operation is not a mere placeholder, because there
+may be more than one way of converting from a given starting mode to
+the desired final mode. The conversion operation code says how to do
+it.
+
+ For all conversion operations, X must not be `VOIDmode' because the
+mode in which to do the conversion would not be known. The conversion
+must either be done at compile-time or X must be placed into a register.
+
+`(sign_extend:M X)'
+ Represents the result of sign-extending the value X to machine
+ mode M. M must be a fixed-point mode and X a fixed-point value of
+ a mode narrower than M.
+
+`(zero_extend:M X)'
+ Represents the result of zero-extending the value X to machine
+ mode M. M must be a fixed-point mode and X a fixed-point value of
+ a mode narrower than M.
+
+`(float_extend:M X)'
+ Represents the result of extending the value X to machine mode M.
+ M must be a floating point mode and X a floating point value of a
+ mode narrower than M.
+
+`(truncate:M X)'
+ Represents the result of truncating the value X to machine mode M.
+ M must be a fixed-point mode and X a fixed-point value of a mode
+ wider than M.
+
+`(ss_truncate:M X)'
+ Represents the result of truncating the value X to machine mode M,
+ using signed saturation in the case of overflow. Both M and the
+ mode of X must be fixed-point modes.
+
+`(us_truncate:M X)'
+ Represents the result of truncating the value X to machine mode M,
+ using unsigned saturation in the case of overflow. Both M and the
+ mode of X must be fixed-point modes.
+
+`(float_truncate:M X)'
+ Represents the result of truncating the value X to machine mode M.
+ M must be a floating point mode and X a floating point value of a
+ mode wider than M.
+
+`(float:M X)'
+ Represents the result of converting fixed point value X, regarded
+ as signed, to floating point mode M.
+
+`(unsigned_float:M X)'
+ Represents the result of converting fixed point value X, regarded
+ as unsigned, to floating point mode M.
+
+`(fix:M X)'
+ When M is a fixed point mode, represents the result of converting
+ floating point value X to mode M, regarded as signed. How
+ rounding is done is not specified, so this operation may be used
+ validly in compiling C code only for integer-valued operands.
+
+`(unsigned_fix:M X)'
+ Represents the result of converting floating point value X to
+ fixed point mode M, regarded as unsigned. How rounding is done is
+ not specified.
+
+`(fix:M X)'
+ When M is a floating point mode, represents the result of
+ converting floating point value X (valid for mode M) to an
+ integer, still represented in floating point mode M, by rounding
+ towards zero.
+
+\1f
+File: gccint.info, Node: RTL Declarations, Next: Side Effects, Prev: Conversions, Up: RTL
+
+8.13 Declarations
+=================
+
+Declaration expression codes do not represent arithmetic operations but
+rather state assertions about their operands.
+
+`(strict_low_part (subreg:M (reg:N R) 0))'
+ This expression code is used in only one context: as the
+ destination operand of a `set' expression. In addition, the
+ operand of this expression must be a non-paradoxical `subreg'
+ expression.
+
+ The presence of `strict_low_part' says that the part of the
+ register which is meaningful in mode N, but is not part of mode M,
+ is not to be altered. Normally, an assignment to such a subreg is
+ allowed to have undefined effects on the rest of the register when
+ M is less than a word.
+
+\1f
+File: gccint.info, Node: Side Effects, Next: Incdec, Prev: RTL Declarations, Up: RTL
+
+8.14 Side Effect Expressions
+============================
+
+The expression codes described so far represent values, not actions.
+But machine instructions never produce values; they are meaningful only
+for their side effects on the state of the machine. Special expression
+codes are used to represent side effects.
+
+ The body of an instruction is always one of these side effect codes;
+the codes described above, which represent values, appear only as the
+operands of these.
+
+`(set LVAL X)'
+ Represents the action of storing the value of X into the place
+ represented by LVAL. LVAL must be an expression representing a
+ place that can be stored in: `reg' (or `subreg' or
+ `strict_low_part'), `mem', `pc', `parallel', or `cc0'.
+
+ If LVAL is a `reg', `subreg' or `mem', it has a machine mode; then
+ X must be valid for that mode.
+
+ If LVAL is a `reg' whose machine mode is less than the full width
+ of the register, then it means that the part of the register
+ specified by the machine mode is given the specified value and the
+ rest of the register receives an undefined value. Likewise, if
+ LVAL is a `subreg' whose machine mode is narrower than the mode of
+ the register, the rest of the register can be changed in an
+ undefined way.
+
+ If LVAL is a `strict_low_part' of a `subreg', then the part of the
+ register specified by the machine mode of the `subreg' is given
+ the value X and the rest of the register is not changed.
+
+ If LVAL is `(cc0)', it has no machine mode, and X may be either a
+ `compare' expression or a value that may have any mode. The
+ latter case represents a "test" instruction. The expression `(set
+ (cc0) (reg:M N))' is equivalent to `(set (cc0) (compare (reg:M N)
+ (const_int 0)))'. Use the former expression to save space during
+ the compilation.
+
+ If LVAL is a `parallel', it is used to represent the case of a
+ function returning a structure in multiple registers. Each element
+ of the `parallel' is an `expr_list' whose first operand is a `reg'
+ and whose second operand is a `const_int' representing the offset
+ (in bytes) into the structure at which the data in that register
+ corresponds. The first element may be null to indicate that the
+ structure is also passed partly in memory.
+
+ If LVAL is `(pc)', we have a jump instruction, and the
+ possibilities for X are very limited. It may be a `label_ref'
+ expression (unconditional jump). It may be an `if_then_else'
+ (conditional jump), in which case either the second or the third
+ operand must be `(pc)' (for the case which does not jump) and the
+ other of the two must be a `label_ref' (for the case which does
+ jump). X may also be a `mem' or `(plus:SI (pc) Y)', where Y may
+ be a `reg' or a `mem'; these unusual patterns are used to
+ represent jumps through branch tables.
+
+ If LVAL is neither `(cc0)' nor `(pc)', the mode of LVAL must not
+ be `VOIDmode' and the mode of X must be valid for the mode of LVAL.
+
+ LVAL is customarily accessed with the `SET_DEST' macro and X with
+ the `SET_SRC' macro.
+
+`(return)'
+ As the sole expression in a pattern, represents a return from the
+ current function, on machines where this can be done with one
+ instruction, such as VAXen. On machines where a multi-instruction
+ "epilogue" must be executed in order to return from the function,
+ returning is done by jumping to a label which precedes the
+ epilogue, and the `return' expression code is never used.
+
+ Inside an `if_then_else' expression, represents the value to be
+ placed in `pc' to return to the caller.
+
+ Note that an insn pattern of `(return)' is logically equivalent to
+ `(set (pc) (return))', but the latter form is never used.
+
+`(call FUNCTION NARGS)'
+ Represents a function call. FUNCTION is a `mem' expression whose
+ address is the address of the function to be called. NARGS is an
+ expression which can be used for two purposes: on some machines it
+ represents the number of bytes of stack argument; on others, it
+ represents the number of argument registers.
+
+ Each machine has a standard machine mode which FUNCTION must have.
+ The machine description defines macro `FUNCTION_MODE' to expand
+ into the requisite mode name. The purpose of this mode is to
+ specify what kind of addressing is allowed, on machines where the
+ allowed kinds of addressing depend on the machine mode being
+ addressed.
+
+`(clobber X)'
+ Represents the storing or possible storing of an unpredictable,
+ undescribed value into X, which must be a `reg', `scratch',
+ `parallel' or `mem' expression.
+
+ One place this is used is in string instructions that store
+ standard values into particular hard registers. It may not be
+ worth the trouble to describe the values that are stored, but it
+ is essential to inform the compiler that the registers will be
+ altered, lest it attempt to keep data in them across the string
+ instruction.
+
+ If X is `(mem:BLK (const_int 0))', it means that all memory
+ locations must be presumed clobbered. If X is a `parallel', it
+ has the same meaning as a `parallel' in a `set' expression.
+
+ Note that the machine description classifies certain hard
+ registers as "call-clobbered". All function call instructions are
+ assumed by default to clobber these registers, so there is no need
+ to use `clobber' expressions to indicate this fact. Also, each
+ function call is assumed to have the potential to alter any memory
+ location, unless the function is declared `const'.
+
+ If the last group of expressions in a `parallel' are each a
+ `clobber' expression whose arguments are `reg' or `match_scratch'
+ (*note RTL Template::) expressions, the combiner phase can add the
+ appropriate `clobber' expressions to an insn it has constructed
+ when doing so will cause a pattern to be matched.
+
+ This feature can be used, for example, on a machine that whose
+ multiply and add instructions don't use an MQ register but which
+ has an add-accumulate instruction that does clobber the MQ
+ register. Similarly, a combined instruction might require a
+ temporary register while the constituent instructions might not.
+
+ When a `clobber' expression for a register appears inside a
+ `parallel' with other side effects, the register allocator
+ guarantees that the register is unoccupied both before and after
+ that insn. However, the reload phase may allocate a register used
+ for one of the inputs unless the `&' constraint is specified for
+ the selected alternative (*note Modifiers::). You can clobber
+ either a specific hard register, a pseudo register, or a `scratch'
+ expression; in the latter two cases, GCC will allocate a hard
+ register that is available there for use as a temporary.
+
+ For instructions that require a temporary register, you should use
+ `scratch' instead of a pseudo-register because this will allow the
+ combiner phase to add the `clobber' when required. You do this by
+ coding (`clobber' (`match_scratch' ...)). If you do clobber a
+ pseudo register, use one which appears nowhere else--generate a
+ new one each time. Otherwise, you may confuse CSE.
+
+ There is one other known use for clobbering a pseudo register in a
+ `parallel': when one of the input operands of the insn is also
+ clobbered by the insn. In this case, using the same pseudo
+ register in the clobber and elsewhere in the insn produces the
+ expected results.
+
+`(use X)'
+ Represents the use of the value of X. It indicates that the value
+ in X at this point in the program is needed, even though it may
+ not be apparent why this is so. Therefore, the compiler will not
+ attempt to delete previous instructions whose only effect is to
+ store a value in X. X must be a `reg' expression.
+
+ In some situations, it may be tempting to add a `use' of a
+ register in a `parallel' to describe a situation where the value
+ of a special register will modify the behavior of the instruction.
+ An hypothetical example might be a pattern for an addition that can
+ either wrap around or use saturating addition depending on the
+ value of a special control register:
+
+ (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
+ (reg:SI 4)] 0))
+ (use (reg:SI 1))])
+
+ This will not work, several of the optimizers only look at
+ expressions locally; it is very likely that if you have multiple
+ insns with identical inputs to the `unspec', they will be
+ optimized away even if register 1 changes in between.
+
+ This means that `use' can _only_ be used to describe that the
+ register is live. You should think twice before adding `use'
+ statements, more often you will want to use `unspec' instead. The
+ `use' RTX is most commonly useful to describe that a fixed
+ register is implicitly used in an insn. It is also safe to use in
+ patterns where the compiler knows for other reasons that the result
+ of the whole pattern is variable, such as `movstrM' or `call'
+ patterns.
+
+ During the reload phase, an insn that has a `use' as pattern can
+ carry a reg_equal note. These `use' insns will be deleted before
+ the reload phase exits.
+
+ During the delayed branch scheduling phase, X may be an insn.
+ This indicates that X previously was located at this place in the
+ code and its data dependencies need to be taken into account.
+ These `use' insns will be deleted before the delayed branch
+ scheduling phase exits.
+
+`(parallel [X0 X1 ...])'
+ Represents several side effects performed in parallel. The square
+ brackets stand for a vector; the operand of `parallel' is a vector
+ of expressions. X0, X1 and so on are individual side effect
+ expressions--expressions of code `set', `call', `return',
+ `clobber' or `use'.
+
+ "In parallel" means that first all the values used in the
+ individual side-effects are computed, and second all the actual
+ side-effects are performed. For example,
+
+ (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
+ (set (mem:SI (reg:SI 1)) (reg:SI 1))])
+
+ says unambiguously that the values of hard register 1 and the
+ memory location addressed by it are interchanged. In both places
+ where `(reg:SI 1)' appears as a memory address it refers to the
+ value in register 1 _before_ the execution of the insn.
+
+ It follows that it is _incorrect_ to use `parallel' and expect the
+ result of one `set' to be available for the next one. For
+ example, people sometimes attempt to represent a jump-if-zero
+ instruction this way:
+
+ (parallel [(set (cc0) (reg:SI 34))
+ (set (pc) (if_then_else
+ (eq (cc0) (const_int 0))
+ (label_ref ...)
+ (pc)))])
+
+ But this is incorrect, because it says that the jump condition
+ depends on the condition code value _before_ this instruction, not
+ on the new value that is set by this instruction.
+
+ Peephole optimization, which takes place together with final
+ assembly code output, can produce insns whose patterns consist of
+ a `parallel' whose elements are the operands needed to output the
+ resulting assembler code--often `reg', `mem' or constant
+ expressions. This would not be well-formed RTL at any other stage
+ in compilation, but it is ok then because no further optimization
+ remains to be done. However, the definition of the macro
+ `NOTICE_UPDATE_CC', if any, must deal with such insns if you
+ define any peephole optimizations.
+
+`(cond_exec [COND EXPR])'
+ Represents a conditionally executed expression. The EXPR is
+ executed only if the COND is nonzero. The COND expression must
+ not have side-effects, but the EXPR may very well have
+ side-effects.
+
+`(sequence [INSNS ...])'
+ Represents a sequence of insns. Each of the INSNS that appears in
+ the vector is suitable for appearing in the chain of insns, so it
+ must be an `insn', `jump_insn', `call_insn', `code_label',
+ `barrier' or `note'.
+
+ A `sequence' RTX is never placed in an actual insn during RTL
+ generation. It represents the sequence of insns that result from a
+ `define_expand' _before_ those insns are passed to `emit_insn' to
+ insert them in the chain of insns. When actually inserted, the
+ individual sub-insns are separated out and the `sequence' is
+ forgotten.
+
+ After delay-slot scheduling is completed, an insn and all the
+ insns that reside in its delay slots are grouped together into a
+ `sequence'. The insn requiring the delay slot is the first insn
+ in the vector; subsequent insns are to be placed in the delay slot.
+
+ `INSN_ANNULLED_BRANCH_P' is set on an insn in a delay slot to
+ indicate that a branch insn should be used that will conditionally
+ annul the effect of the insns in the delay slots. In such a case,
+ `INSN_FROM_TARGET_P' indicates that the insn is from the target of
+ the branch and should be executed only if the branch is taken;
+ otherwise the insn should be executed only if the branch is not
+ taken. *Note Delay Slots::.
+
+ These expression codes appear in place of a side effect, as the body
+of an insn, though strictly speaking they do not always describe side
+effects as such:
+
+`(asm_input S)'
+ Represents literal assembler code as described by the string S.
+
+`(unspec [OPERANDS ...] INDEX)'
+`(unspec_volatile [OPERANDS ...] INDEX)'
+ Represents a machine-specific operation on OPERANDS. INDEX
+ selects between multiple machine-specific operations.
+ `unspec_volatile' is used for volatile operations and operations
+ that may trap; `unspec' is used for other operations.
+
+ These codes may appear inside a `pattern' of an insn, inside a
+ `parallel', or inside an expression.
+
+`(addr_vec:M [LR0 LR1 ...])'
+ Represents a table of jump addresses. The vector elements LR0,
+ etc., are `label_ref' expressions. The mode M specifies how much
+ space is given to each address; normally M would be `Pmode'.
+
+`(addr_diff_vec:M BASE [LR0 LR1 ...] MIN MAX FLAGS)'
+ Represents a table of jump addresses expressed as offsets from
+ BASE. The vector elements LR0, etc., are `label_ref' expressions
+ and so is BASE. The mode M specifies how much space is given to
+ each address-difference. MIN and MAX are set up by branch
+ shortening and hold a label with a minimum and a maximum address,
+ respectively. FLAGS indicates the relative position of BASE, MIN
+ and MAX to the containing insn and of MIN and MAX to BASE. See
+ rtl.def for details.
+
+`(prefetch:M ADDR RW LOCALITY)'
+ Represents prefetch of memory at address ADDR. Operand RW is 1 if
+ the prefetch is for data to be written, 0 otherwise; targets that
+ do not support write prefetches should treat this as a normal
+ prefetch. Operand LOCALITY specifies the amount of temporal
+ locality; 0 if there is none or 1, 2, or 3 for increasing levels
+ of temporal locality; targets that do not support locality hints
+ should ignore this.
+
+ This insn is used to minimize cache-miss latency by moving data
+ into a cache before it is accessed. It should use only
+ non-faulting data prefetch instructions.
+
+\1f
+File: gccint.info, Node: Incdec, Next: Assembler, Prev: Side Effects, Up: RTL
+
+8.15 Embedded Side-Effects on Addresses
+=======================================
+
+Six special side-effect expression codes appear as memory addresses.
+
+`(pre_dec:M X)'
+ Represents the side effect of decrementing X by a standard amount
+ and represents also the value that X has after being decremented.
+ X must be a `reg' or `mem', but most machines allow only a `reg'.
+ M must be the machine mode for pointers on the machine in use.
+ The amount X is decremented by is the length in bytes of the
+ machine mode of the containing memory reference of which this
+ expression serves as the address. Here is an example of its use:
+
+ (mem:DF (pre_dec:SI (reg:SI 39)))
+
+ This says to decrement pseudo register 39 by the length of a
+ `DFmode' value and use the result to address a `DFmode' value.
+
+`(pre_inc:M X)'
+ Similar, but specifies incrementing X instead of decrementing it.
+
+`(post_dec:M X)'
+ Represents the same side effect as `pre_dec' but a different
+ value. The value represented here is the value X has before being
+ decremented.
+
+`(post_inc:M X)'
+ Similar, but specifies incrementing X instead of decrementing it.
+
+`(post_modify:M X Y)'
+ Represents the side effect of setting X to Y and represents X
+ before X is modified. X must be a `reg' or `mem', but most
+ machines allow only a `reg'. M must be the machine mode for
+ pointers on the machine in use. The amount X is decremented by is
+ the length in bytes of the machine mode of the containing memory
+ reference of which this expression serves as the address. Note
+ that this is not currently implemented.
+
+ The expression Y must be one of three forms:
+ `(plus:M X Z)', `(minus:M X Z)', or `(plus:M X I)',
+ where Z is an index register and I is a constant.
+
+ Here is an example of its use:
+
+ (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
+ (reg:SI 48))))
+
+ This says to modify pseudo register 42 by adding the contents of
+ pseudo register 48 to it, after the use of what ever 42 points to.
+
+`(pre_modify:M X EXPR)'
+ Similar except side effects happen before the use.
+
+ These embedded side effect expressions must be used with care.
+Instruction patterns may not use them. Until the `flow' pass of the
+compiler, they may occur only to represent pushes onto the stack. The
+`flow' pass finds cases where registers are incremented or decremented
+in one instruction and used as an address shortly before or after;
+these cases are then transformed to use pre- or post-increment or
+-decrement.
+
+ If a register used as the operand of these expressions is used in
+another address in an insn, the original value of the register is used.
+Uses of the register outside of an address are not permitted within the
+same insn as a use in an embedded side effect expression because such
+insns behave differently on different machines and hence must be treated
+as ambiguous and disallowed.
+
+ An instruction that can be represented with an embedded side effect
+could also be represented using `parallel' containing an additional
+`set' to describe how the address register is altered. This is not
+done because machines that allow these operations at all typically
+allow them wherever a memory address is called for. Describing them as
+additional parallel stores would require doubling the number of entries
+in the machine description.
+
+\1f
+File: gccint.info, Node: Assembler, Next: Insns, Prev: Incdec, Up: RTL
+
+8.16 Assembler Instructions as Expressions
+==========================================
+
+The RTX code `asm_operands' represents a value produced by a
+user-specified assembler instruction. It is used to represent an `asm'
+statement with arguments. An `asm' statement with a single output
+operand, like this:
+
+ asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
+
+is represented using a single `asm_operands' RTX which represents the
+value that is stored in `outputvar':
+
+ (set RTX-FOR-OUTPUTVAR
+ (asm_operands "foo %1,%2,%0" "a" 0
+ [RTX-FOR-ADDITION-RESULT RTX-FOR-*Z]
+ [(asm_input:M1 "g")
+ (asm_input:M2 "di")]))
+
+Here the operands of the `asm_operands' RTX are the assembler template
+string, the output-operand's constraint, the index-number of the output
+operand among the output operands specified, a vector of input operand
+RTX's, and a vector of input-operand modes and constraints. The mode
+M1 is the mode of the sum `x+y'; M2 is that of `*z'.
+
+ When an `asm' statement has multiple output values, its insn has
+several such `set' RTX's inside of a `parallel'. Each `set' contains a
+`asm_operands'; all of these share the same assembler template and
+vectors, but each contains the constraint for the respective output
+operand. They are also distinguished by the output-operand index
+number, which is 0, 1, ... for successive output operands.
+
+\1f
+File: gccint.info, Node: Insns, Next: Calls, Prev: Assembler, Up: RTL
+
+8.17 Insns
+==========
+
+The RTL representation of the code for a function is a doubly-linked
+chain of objects called "insns". Insns are expressions with special
+codes that are used for no other purpose. Some insns are actual
+instructions; others represent dispatch tables for `switch' statements;
+others represent labels to jump to or various sorts of declarative
+information.
+
+ In addition to its own specific data, each insn must have a unique
+id-number that distinguishes it from all other insns in the current
+function (after delayed branch scheduling, copies of an insn with the
+same id-number may be present in multiple places in a function, but
+these copies will always be identical and will only appear inside a
+`sequence'), and chain pointers to the preceding and following insns.
+These three fields occupy the same position in every insn, independent
+of the expression code of the insn. They could be accessed with `XEXP'
+and `XINT', but instead three special macros are always used:
+
+`INSN_UID (I)'
+ Accesses the unique id of insn I.
+
+`PREV_INSN (I)'
+ Accesses the chain pointer to the insn preceding I. If I is the
+ first insn, this is a null pointer.
+
+`NEXT_INSN (I)'
+ Accesses the chain pointer to the insn following I. If I is the
+ last insn, this is a null pointer.
+
+ The first insn in the chain is obtained by calling `get_insns'; the
+last insn is the result of calling `get_last_insn'. Within the chain
+delimited by these insns, the `NEXT_INSN' and `PREV_INSN' pointers must
+always correspond: if INSN is not the first insn,
+
+ NEXT_INSN (PREV_INSN (INSN)) == INSN
+
+is always true and if INSN is not the last insn,
+
+ PREV_INSN (NEXT_INSN (INSN)) == INSN
+
+is always true.
+
+ After delay slot scheduling, some of the insns in the chain might be
+`sequence' expressions, which contain a vector of insns. The value of
+`NEXT_INSN' in all but the last of these insns is the next insn in the
+vector; the value of `NEXT_INSN' of the last insn in the vector is the
+same as the value of `NEXT_INSN' for the `sequence' in which it is
+contained. Similar rules apply for `PREV_INSN'.
+
+ This means that the above invariants are not necessarily true for
+insns inside `sequence' expressions. Specifically, if INSN is the
+first insn in a `sequence', `NEXT_INSN (PREV_INSN (INSN))' is the insn
+containing the `sequence' expression, as is the value of `PREV_INSN
+(NEXT_INSN (INSN))' if INSN is the last insn in the `sequence'
+expression. You can use these expressions to find the containing
+`sequence' expression.
+
+ Every insn has one of the following six expression codes:
+
+`insn'
+ The expression code `insn' is used for instructions that do not
+ jump and do not do function calls. `sequence' expressions are
+ always contained in insns with code `insn' even if one of those
+ insns should jump or do function calls.
+
+ Insns with code `insn' have four additional fields beyond the three
+ mandatory ones listed above. These four are described in a table
+ below.
+
+`jump_insn'
+ The expression code `jump_insn' is used for instructions that may
+ jump (or, more generally, may contain `label_ref' expressions). If
+ there is an instruction to return from the current function, it is
+ recorded as a `jump_insn'.
+
+ `jump_insn' insns have the same extra fields as `insn' insns,
+ accessed in the same way and in addition contain a field
+ `JUMP_LABEL' which is defined once jump optimization has completed.
+
+ For simple conditional and unconditional jumps, this field contains
+ the `code_label' to which this insn will (possibly conditionally)
+ branch. In a more complex jump, `JUMP_LABEL' records one of the
+ labels that the insn refers to; the only way to find the others is
+ to scan the entire body of the insn. In an `addr_vec',
+ `JUMP_LABEL' is `NULL_RTX'.
+
+ Return insns count as jumps, but since they do not refer to any
+ labels, their `JUMP_LABEL' is `NULL_RTX'.
+
+`call_insn'
+ The expression code `call_insn' is used for instructions that may
+ do function calls. It is important to distinguish these
+ instructions because they imply that certain registers and memory
+ locations may be altered unpredictably.
+
+ `call_insn' insns have the same extra fields as `insn' insns,
+ accessed in the same way and in addition contain a field
+ `CALL_INSN_FUNCTION_USAGE', which contains a list (chain of
+ `expr_list' expressions) containing `use' and `clobber'
+ expressions that denote hard registers and `MEM's used or
+ clobbered by the called function.
+
+ A `MEM' generally points to a stack slots in which arguments passed
+ to the libcall by reference (*note FUNCTION_ARG_PASS_BY_REFERENCE:
+ Register Arguments.) are stored. If the argument is caller-copied
+ (*note FUNCTION_ARG_CALLEE_COPIES: Register Arguments.), the stack
+ slot will be mentioned in `CLOBBER' and `USE' entries; if it's
+ callee-copied, only a `USE' will appear, and the `MEM' may point
+ to addresses that are not stack slots. These `MEM's are used only
+ in libcalls, because, unlike regular function calls, `CONST_CALL's
+ (which libcalls generally are, *note CONST_CALL_P: Flags.) aren't
+ assumed to read and write all memory, so flow would consider the
+ stores dead and remove them. Note that, since a libcall must
+ never return values in memory (*note RETURN_IN_MEMORY: Aggregate
+ Return.), there will never be a `CLOBBER' for a memory address
+ holding a return value.
+
+ `CLOBBER'ed registers in this list augment registers specified in
+ `CALL_USED_REGISTERS' (*note Register Basics::).
+
+`code_label'
+ A `code_label' insn represents a label that a jump insn can jump
+ to. It contains two special fields of data in addition to the
+ three standard ones. `CODE_LABEL_NUMBER' is used to hold the
+ "label number", a number that identifies this label uniquely among
+ all the labels in the compilation (not just in the current
+ function). Ultimately, the label is represented in the assembler
+ output as an assembler label, usually of the form `LN' where N is
+ the label number.
+
+ When a `code_label' appears in an RTL expression, it normally
+ appears within a `label_ref' which represents the address of the
+ label, as a number.
+
+ Besides as a `code_label', a label can also be represented as a
+ `note' of type `NOTE_INSN_DELETED_LABEL'.
+
+ The field `LABEL_NUSES' is only defined once the jump optimization
+ phase is completed and contains the number of times this label is
+ referenced in the current function.
+
+ The field `LABEL_ALTERNATE_NAME' is used to associate a name with
+ a `code_label'. If this field is defined, the alternate name will
+ be emitted instead of an internally generated label name.
+
+`barrier'
+ Barriers are placed in the instruction stream when control cannot
+ flow past them. They are placed after unconditional jump
+ instructions to indicate that the jumps are unconditional and
+ after calls to `volatile' functions, which do not return (e.g.,
+ `exit'). They contain no information beyond the three standard
+ fields.
+
+`note'
+ `note' insns are used to represent additional debugging and
+ declarative information. They contain two nonstandard fields, an
+ integer which is accessed with the macro `NOTE_LINE_NUMBER' and a
+ string accessed with `NOTE_SOURCE_FILE'.
+
+ If `NOTE_LINE_NUMBER' is positive, the note represents the
+ position of a source line and `NOTE_SOURCE_FILE' is the source
+ file name that the line came from. These notes control generation
+ of line number data in the assembler output.
+
+ Otherwise, `NOTE_LINE_NUMBER' is not really a line number but a
+ code with one of the following values (and `NOTE_SOURCE_FILE' must
+ contain a null pointer):
+
+ `NOTE_INSN_DELETED'
+ Such a note is completely ignorable. Some passes of the
+ compiler delete insns by altering them into notes of this
+ kind.
+
+ `NOTE_INSN_DELETED_LABEL'
+ This marks what used to be a `code_label', but was not used
+ for other purposes than taking its address and was
+ transformed to mark that no code jumps to it.
+
+ `NOTE_INSN_BLOCK_BEG'
+ `NOTE_INSN_BLOCK_END'
+ These types of notes indicate the position of the beginning
+ and end of a level of scoping of variable names. They
+ control the output of debugging information.
+
+ `NOTE_INSN_EH_REGION_BEG'
+ `NOTE_INSN_EH_REGION_END'
+ These types of notes indicate the position of the beginning
+ and end of a level of scoping for exception handling.
+ `NOTE_BLOCK_NUMBER' identifies which `CODE_LABEL' or `note'
+ of type `NOTE_INSN_DELETED_LABEL' is associated with the
+ given region.
+
+ `NOTE_INSN_LOOP_BEG'
+ `NOTE_INSN_LOOP_END'
+ These types of notes indicate the position of the beginning
+ and end of a `while' or `for' loop. They enable the loop
+ optimizer to find loops quickly.
+
+ `NOTE_INSN_LOOP_CONT'
+ Appears at the place in a loop that `continue' statements
+ jump to.
+
+ `NOTE_INSN_LOOP_VTOP'
+ This note indicates the place in a loop where the exit test
+ begins for those loops in which the exit test has been
+ duplicated. This position becomes another virtual start of
+ the loop when considering loop invariants.
+
+ `NOTE_INSN_FUNCTION_END'
+ Appears near the end of the function body, just before the
+ label that `return' statements jump to (on machine where a
+ single instruction does not suffice for returning). This
+ note may be deleted by jump optimization.
+
+ `NOTE_INSN_SETJMP'
+ Appears following each call to `setjmp' or a related function.
+
+ These codes are printed symbolically when they appear in debugging
+ dumps.
+
+ The machine mode of an insn is normally `VOIDmode', but some phases
+use the mode for various purposes.
+
+ The common subexpression elimination pass sets the mode of an insn to
+`QImode' when it is the first insn in a block that has already been
+processed.
+
+ The second Haifa scheduling pass, for targets that can multiple
+issue, sets the mode of an insn to `TImode' when it is believed that the
+instruction begins an issue group. That is, when the instruction
+cannot issue simultaneously with the previous. This may be relied on
+by later passes, in particular machine-dependent reorg.
+
+ Here is a table of the extra fields of `insn', `jump_insn' and
+`call_insn' insns:
+
+`PATTERN (I)'
+ An expression for the side effect performed by this insn. This
+ must be one of the following codes: `set', `call', `use',
+ `clobber', `return', `asm_input', `asm_output', `addr_vec',
+ `addr_diff_vec', `trap_if', `unspec', `unspec_volatile',
+ `parallel', `cond_exec', or `sequence'. If it is a `parallel',
+ each element of the `parallel' must be one these codes, except that
+ `parallel' expressions cannot be nested and `addr_vec' and
+ `addr_diff_vec' are not permitted inside a `parallel' expression.
+
+`INSN_CODE (I)'
+ An integer that says which pattern in the machine description
+ matches this insn, or -1 if the matching has not yet been
+ attempted.
+
+ Such matching is never attempted and this field remains -1 on an
+ insn whose pattern consists of a single `use', `clobber',
+ `asm_input', `addr_vec' or `addr_diff_vec' expression.
+
+ Matching is also never attempted on insns that result from an `asm'
+ statement. These contain at least one `asm_operands' expression.
+ The function `asm_noperands' returns a non-negative value for such
+ insns.
+
+ In the debugging output, this field is printed as a number
+ followed by a symbolic representation that locates the pattern in
+ the `md' file as some small positive or negative offset from a
+ named pattern.
+
+`LOG_LINKS (I)'
+ A list (chain of `insn_list' expressions) giving information about
+ dependencies between instructions within a basic block. Neither a
+ jump nor a label may come between the related insns.
+
+`REG_NOTES (I)'
+ A list (chain of `expr_list' and `insn_list' expressions) giving
+ miscellaneous information about the insn. It is often information
+ pertaining to the registers used in this insn.
+
+ The `LOG_LINKS' field of an insn is a chain of `insn_list'
+expressions. Each of these has two operands: the first is an insn, and
+the second is another `insn_list' expression (the next one in the
+chain). The last `insn_list' in the chain has a null pointer as second
+operand. The significant thing about the chain is which insns appear
+in it (as first operands of `insn_list' expressions). Their order is
+not significant.
+
+ This list is originally set up by the flow analysis pass; it is a
+null pointer until then. Flow only adds links for those data
+dependencies which can be used for instruction combination. For each
+insn, the flow analysis pass adds a link to insns which store into
+registers values that are used for the first time in this insn. The
+instruction scheduling pass adds extra links so that every dependence
+will be represented. Links represent data dependencies,
+antidependencies and output dependencies; the machine mode of the link
+distinguishes these three types: antidependencies have mode
+`REG_DEP_ANTI', output dependencies have mode `REG_DEP_OUTPUT', and
+data dependencies have mode `VOIDmode'.
+
+ The `REG_NOTES' field of an insn is a chain similar to the
+`LOG_LINKS' field but it includes `expr_list' expressions in addition
+to `insn_list' expressions. There are several kinds of register notes,
+which are distinguished by the machine mode, which in a register note
+is really understood as being an `enum reg_note'. The first operand OP
+of the note is data whose meaning depends on the kind of note.
+
+ The macro `REG_NOTE_KIND (X)' returns the kind of register note.
+Its counterpart, the macro `PUT_REG_NOTE_KIND (X, NEWKIND)' sets the
+register note type of X to be NEWKIND.
+
+ Register notes are of three classes: They may say something about an
+input to an insn, they may say something about an output of an insn, or
+they may create a linkage between two insns. There are also a set of
+values that are only used in `LOG_LINKS'.
+
+ These register notes annotate inputs to an insn:
+
+`REG_DEAD'
+ The value in OP dies in this insn; that is to say, altering the
+ value immediately after this insn would not affect the future
+ behavior of the program.
+
+ It does not follow that the register OP has no useful value after
+ this insn since OP is not necessarily modified by this insn.
+ Rather, no subsequent instruction uses the contents of OP.
+
+`REG_UNUSED'
+ The register OP being set by this insn will not be used in a
+ subsequent insn. This differs from a `REG_DEAD' note, which
+ indicates that the value in an input will not be used subsequently.
+ These two notes are independent; both may be present for the same
+ register.
+
+`REG_INC'
+ The register OP is incremented (or decremented; at this level
+ there is no distinction) by an embedded side effect inside this
+ insn. This means it appears in a `post_inc', `pre_inc',
+ `post_dec' or `pre_dec' expression.
+
+`REG_NONNEG'
+ The register OP is known to have a nonnegative value when this
+ insn is reached. This is used so that decrement and branch until
+ zero instructions, such as the m68k dbra, can be matched.
+
+ The `REG_NONNEG' note is added to insns only if the machine
+ description has a `decrement_and_branch_until_zero' pattern.
+
+`REG_NO_CONFLICT'
+ This insn does not cause a conflict between OP and the item being
+ set by this insn even though it might appear that it does. In
+ other words, if the destination register and OP could otherwise be
+ assigned the same register, this insn does not prevent that
+ assignment.
+
+ Insns with this note are usually part of a block that begins with a
+ `clobber' insn specifying a multi-word pseudo register (which will
+ be the output of the block), a group of insns that each set one
+ word of the value and have the `REG_NO_CONFLICT' note attached,
+ and a final insn that copies the output to itself with an attached
+ `REG_EQUAL' note giving the expression being computed. This block
+ is encapsulated with `REG_LIBCALL' and `REG_RETVAL' notes on the
+ first and last insns, respectively.
+
+`REG_LABEL'
+ This insn uses OP, a `code_label' or a `note' of type
+ `NOTE_INSN_DELETED_LABEL', but is not a `jump_insn', or it is a
+ `jump_insn' that required the label to be held in a register. The
+ presence of this note allows jump optimization to be aware that OP
+ is, in fact, being used, and flow optimization to build an
+ accurate flow graph.
+
+ The following notes describe attributes of outputs of an insn:
+
+`REG_EQUIV'
+`REG_EQUAL'
+ This note is only valid on an insn that sets only one register and
+ indicates that that register will be equal to OP at run time; the
+ scope of this equivalence differs between the two types of notes.
+ The value which the insn explicitly copies into the register may
+ look different from OP, but they will be equal at run time. If the
+ output of the single `set' is a `strict_low_part' expression, the
+ note refers to the register that is contained in `SUBREG_REG' of
+ the `subreg' expression.
+
+ For `REG_EQUIV', the register is equivalent to OP throughout the
+ entire function, and could validly be replaced in all its
+ occurrences by OP. ("Validly" here refers to the data flow of the
+ program; simple replacement may make some insns invalid.) For
+ example, when a constant is loaded into a register that is never
+ assigned any other value, this kind of note is used.
+
+ When a parameter is copied into a pseudo-register at entry to a
+ function, a note of this kind records that the register is
+ equivalent to the stack slot where the parameter was passed.
+ Although in this case the register may be set by other insns, it
+ is still valid to replace the register by the stack slot
+ throughout the function.
+
+ A `REG_EQUIV' note is also used on an instruction which copies a
+ register parameter into a pseudo-register at entry to a function,
+ if there is a stack slot where that parameter could be stored.
+ Although other insns may set the pseudo-register, it is valid for
+ the compiler to replace the pseudo-register by stack slot
+ throughout the function, provided the compiler ensures that the
+ stack slot is properly initialized by making the replacement in
+ the initial copy instruction as well. This is used on machines
+ for which the calling convention allocates stack space for
+ register parameters. See `REG_PARM_STACK_SPACE' in *note Stack
+ Arguments::.
+
+ In the case of `REG_EQUAL', the register that is set by this insn
+ will be equal to OP at run time at the end of this insn but not
+ necessarily elsewhere in the function. In this case, OP is
+ typically an arithmetic expression. For example, when a sequence
+ of insns such as a library call is used to perform an arithmetic
+ operation, this kind of note is attached to the insn that produces
+ or copies the final value.
+
+ These two notes are used in different ways by the compiler passes.
+ `REG_EQUAL' is used by passes prior to register allocation (such as
+ common subexpression elimination and loop optimization) to tell
+ them how to think of that value. `REG_EQUIV' notes are used by
+ register allocation to indicate that there is an available
+ substitute expression (either a constant or a `mem' expression for
+ the location of a parameter on the stack) that may be used in
+ place of a register if insufficient registers are available.
+
+ Except for stack homes for parameters, which are indicated by a
+ `REG_EQUIV' note and are not useful to the early optimization
+ passes and pseudo registers that are equivalent to a memory
+ location throughout their entire life, which is not detected until
+ later in the compilation, all equivalences are initially indicated
+ by an attached `REG_EQUAL' note. In the early stages of register
+ allocation, a `REG_EQUAL' note is changed into a `REG_EQUIV' note
+ if OP is a constant and the insn represents the only set of its
+ destination register.
+
+ Thus, compiler passes prior to register allocation need only check
+ for `REG_EQUAL' notes and passes subsequent to register allocation
+ need only check for `REG_EQUIV' notes.
+
+`REG_WAS_0'
+ The single output of this insn contained zero before this insn.
+ OP is the insn that set it to zero. You can rely on this note if
+ it is present and OP has not been deleted or turned into a `note';
+ its absence implies nothing.
+
+ These notes describe linkages between insns. They occur in pairs:
+one insn has one of a pair of notes that points to a second insn, which
+has the inverse note pointing back to the first insn.
+
+`REG_RETVAL'
+ This insn copies the value of a multi-insn sequence (for example, a
+ library call), and OP is the first insn of the sequence (for a
+ library call, the first insn that was generated to set up the
+ arguments for the library call).
+
+ Loop optimization uses this note to treat such a sequence as a
+ single operation for code motion purposes and flow analysis uses
+ this note to delete such sequences whose results are dead.
+
+ A `REG_EQUAL' note will also usually be attached to this insn to
+ provide the expression being computed by the sequence.
+
+ These notes will be deleted after reload, since they are no longer
+ accurate or useful.
+
+`REG_LIBCALL'
+ This is the inverse of `REG_RETVAL': it is placed on the first
+ insn of a multi-insn sequence, and it points to the last one.
+
+ These notes are deleted after reload, since they are no longer
+ useful or accurate.
+
+`REG_CC_SETTER'
+`REG_CC_USER'
+ On machines that use `cc0', the insns which set and use `cc0' set
+ and use `cc0' are adjacent. However, when branch delay slot
+ filling is done, this may no longer be true. In this case a
+ `REG_CC_USER' note will be placed on the insn setting `cc0' to
+ point to the insn using `cc0' and a `REG_CC_SETTER' note will be
+ placed on the insn using `cc0' to point to the insn setting `cc0'.
+
+ These values are only used in the `LOG_LINKS' field, and indicate
+the type of dependency that each link represents. Links which indicate
+a data dependence (a read after write dependence) do not use any code,
+they simply have mode `VOIDmode', and are printed without any
+descriptive text.
+
+`REG_DEP_ANTI'
+ This indicates an anti dependence (a write after read dependence).
+
+`REG_DEP_OUTPUT'
+ This indicates an output dependence (a write after write
+ dependence).
+
+ These notes describe information gathered from gcov profile data.
+They are stored in the `REG_NOTES' field of an insn as an `expr_list'.
+
+`REG_EXEC_COUNT'
+ This is used to indicate the number of times a basic block was
+ executed according to the profile data. The note is attached to
+ the first insn in the basic block.
+
+`REG_BR_PROB'
+ This is used to specify the ratio of branches to non-branches of a
+ branch insn according to the profile data. The value is stored as
+ a value between 0 and REG_BR_PROB_BASE; larger values indicate a
+ higher probability that the branch will be taken.
+
+`REG_BR_PRED'
+ These notes are found in JUMP insns after delayed branch scheduling
+ has taken place. They indicate both the direction and the
+ likelihood of the JUMP. The format is a bitmask of ATTR_FLAG_*
+ values.
+
+`REG_FRAME_RELATED_EXPR'
+ This is used on an RTX_FRAME_RELATED_P insn wherein the attached
+ expression is used in place of the actual insn pattern. This is
+ done in cases where the pattern is either complex or misleading.
+
+ For convenience, the machine mode in an `insn_list' or `expr_list'
+is printed using these symbolic codes in debugging dumps.
+
+ The only difference between the expression codes `insn_list' and
+`expr_list' is that the first operand of an `insn_list' is assumed to
+be an insn and is printed in debugging dumps as the insn's unique id;
+the first operand of an `expr_list' is printed in the ordinary way as
+an expression.
+
+\1f
+File: gccint.info, Node: Calls, Next: Sharing, Prev: Insns, Up: RTL
+
+8.18 RTL Representation of Function-Call Insns
+==============================================
+
+Insns that call subroutines have the RTL expression code `call_insn'.
+These insns must satisfy special rules, and their bodies must use a
+special RTL expression code, `call'.
+
+ A `call' expression has two operands, as follows:
+
+ (call (mem:FM ADDR) NBYTES)
+
+Here NBYTES is an operand that represents the number of bytes of
+argument data being passed to the subroutine, FM is a machine mode
+(which must equal as the definition of the `FUNCTION_MODE' macro in the
+machine description) and ADDR represents the address of the subroutine.
+
+ For a subroutine that returns no value, the `call' expression as
+shown above is the entire body of the insn, except that the insn might
+also contain `use' or `clobber' expressions.
+
+ For a subroutine that returns a value whose mode is not `BLKmode',
+the value is returned in a hard register. If this register's number is
+R, then the body of the call insn looks like this:
+
+ (set (reg:M R)
+ (call (mem:FM ADDR) NBYTES))
+
+This RTL expression makes it clear (to the optimizer passes) that the
+appropriate register receives a useful value in this insn.
+
+ When a subroutine returns a `BLKmode' value, it is handled by
+passing to the subroutine the address of a place to store the value.
+So the call insn itself does not "return" any value, and it has the
+same RTL form as a call that returns nothing.
+
+ On some machines, the call instruction itself clobbers some register,
+for example to contain the return address. `call_insn' insns on these
+machines should have a body which is a `parallel' that contains both
+the `call' expression and `clobber' expressions that indicate which
+registers are destroyed. Similarly, if the call instruction requires
+some register other than the stack pointer that is not explicitly
+mentioned it its RTL, a `use' subexpression should mention that
+register.
+
+ Functions that are called are assumed to modify all registers listed
+in the configuration macro `CALL_USED_REGISTERS' (*note Register
+Basics::) and, with the exception of `const' functions and library
+calls, to modify all of memory.
+
+ Insns containing just `use' expressions directly precede the
+`call_insn' insn to indicate which registers contain inputs to the
+function. Similarly, if registers other than those in
+`CALL_USED_REGISTERS' are clobbered by the called function, insns
+containing a single `clobber' follow immediately after the call to
+indicate which registers.
+
+\1f
+File: gccint.info, Node: Sharing, Next: Reading RTL, Prev: Calls, Up: RTL
+
+8.19 Structure Sharing Assumptions
+==================================
+
+The compiler assumes that certain kinds of RTL expressions are unique;
+there do not exist two distinct objects representing the same value.
+In other cases, it makes an opposite assumption: that no RTL expression
+object of a certain kind appears in more than one place in the
+containing structure.
+
+ These assumptions refer to a single function; except for the RTL
+objects that describe global variables and external functions, and a
+few standard objects such as small integer constants, no RTL objects
+are common to two functions.
+
+ * Each pseudo-register has only a single `reg' object to represent
+ it, and therefore only a single machine mode.
+
+ * For any symbolic label, there is only one `symbol_ref' object
+ referring to it.
+
+ * All `const_int' expressions with equal values are shared.
+
+ * There is only one `pc' expression.
+
+ * There is only one `cc0' expression.
+
+ * There is only one `const_double' expression with value 0 for each
+ floating point mode. Likewise for values 1 and 2.
+
+ * There is only one `const_vector' expression with value 0 for each
+ vector mode, be it an integer or a double constant vector.
+
+ * No `label_ref' or `scratch' appears in more than one place in the
+ RTL structure; in other words, it is safe to do a tree-walk of all
+ the insns in the function and assume that each time a `label_ref'
+ or `scratch' is seen it is distinct from all others that are seen.
+
+ * Only one `mem' object is normally created for each static variable
+ or stack slot, so these objects are frequently shared in all the
+ places they appear. However, separate but equal objects for these
+ variables are occasionally made.
+
+ * When a single `asm' statement has multiple output operands, a
+ distinct `asm_operands' expression is made for each output operand.
+ However, these all share the vector which contains the sequence of
+ input operands. This sharing is used later on to test whether two
+ `asm_operands' expressions come from the same statement, so all
+ optimizations must carefully preserve the sharing if they copy the
+ vector at all.
+
+ * No RTL object appears in more than one place in the RTL structure
+ except as described above. Many passes of the compiler rely on
+ this by assuming that they can modify RTL objects in place without
+ unwanted side-effects on other insns.
+
+ * During initial RTL generation, shared structure is freely
+ introduced. After all the RTL for a function has been generated,
+ all shared structure is copied by `unshare_all_rtl' in
+ `emit-rtl.c', after which the above rules are guaranteed to be
+ followed.
+
+ * During the combiner pass, shared structure within an insn can exist
+ temporarily. However, the shared structure is copied before the
+ combiner is finished with the insn. This is done by calling
+ `copy_rtx_if_shared', which is a subroutine of `unshare_all_rtl'.
+
+\1f
+File: gccint.info, Node: Reading RTL, Prev: Sharing, Up: RTL
+
+8.20 Reading RTL
+================
+
+To read an RTL object from a file, call `read_rtx'. It takes one
+argument, a stdio stream, and returns a single RTL object. This routine
+is defined in `read-rtl.c'. It is not available in the compiler
+itself, only the various programs that generate the compiler back end
+from the machine description.
+
+ People frequently have the idea of using RTL stored as text in a
+file as an interface between a language front end and the bulk of GCC.
+This idea is not feasible.
+
+ GCC was designed to use RTL internally only. Correct RTL for a given
+program is very dependent on the particular target machine. And the RTL
+does not contain all the information about the program.
+
+ The proper way to interface GCC to a new language front end is with
+the "tree" data structure, described in the files `tree.h' and
+`tree.def'. The documentation for this structure (*note Trees::) is
+incomplete.
+
+\1f
+File: gccint.info, Node: Machine Desc, Next: Target Macros, Prev: RTL, Up: Top
+
+9 Machine Descriptions
+**********************
+
+A machine description has two parts: a file of instruction patterns
+(`.md' file) and a C header file of macro definitions.
+
+ The `.md' file for a target machine contains a pattern for each
+instruction that the target machine supports (or at least each
+instruction that is worth telling the compiler about). It may also
+contain comments. A semicolon causes the rest of the line to be a
+comment, unless the semicolon is inside a quoted string.
+
+ See the next chapter for information on the C header file.
+
+* Menu:
+
+* Overview:: How the machine description is used.
+* Patterns:: How to write instruction patterns.
+* Example:: An explained example of a `define_insn' pattern.
+* RTL Template:: The RTL template defines what insns match a pattern.
+* Output Template:: The output template says how to make assembler code
+ from such an insn.
+* Output Statement:: For more generality, write C code to output
+ the assembler code.
+* Constraints:: When not all operands are general operands.
+* Standard Names:: Names mark patterns to use for code generation.
+* Pattern Ordering:: When the order of patterns makes a difference.
+* Dependent Patterns:: Having one pattern may make you need another.
+* Jump Patterns:: Special considerations for patterns for jump insns.
+* Looping Patterns:: How to define patterns for special looping insns.
+* Insn Canonicalizations::Canonicalization of Instructions
+* Expander Definitions::Generating a sequence of several RTL insns
+ for a standard operation.
+* Insn Splitting:: Splitting Instructions into Multiple Instructions.
+* Including Patterns:: Including Patterns in Machine Descriptions.
+* Peephole Definitions::Defining machine-specific peephole optimizations.
+* Insn Attributes:: Specifying the value of attributes for generated insns.
+* Conditional Execution::Generating `define_insn' patterns for
+ predication.
+* Constant Definitions::Defining symbolic constants that can be used in the
+ md file.
+
+\1f
+File: gccint.info, Node: Overview, Next: Patterns, Up: Machine Desc
+
+9.1 Overview of How the Machine Description is Used
+===================================================
+
+There are three main conversions that happen in the compiler:
+
+ 1. The front end reads the source code and builds a parse tree.
+
+ 2. The parse tree is used to generate an RTL insn list based on named
+ instruction patterns.
+
+ 3. The insn list is matched against the RTL templates to produce
+ assembler code.
+
+
+ For the generate pass, only the names of the insns matter, from
+either a named `define_insn' or a `define_expand'. The compiler will
+choose the pattern with the right name and apply the operands according
+to the documentation later in this chapter, without regard for the RTL
+template or operand constraints. Note that the names the compiler looks
+for are hard-coded in the compiler--it will ignore unnamed patterns and
+patterns with names it doesn't know about, but if you don't provide a
+named pattern it needs, it will abort.
+
+ If a `define_insn' is used, the template given is inserted into the
+insn list. If a `define_expand' is used, one of three things happens,
+based on the condition logic. The condition logic may manually create
+new insns for the insn list, say via `emit_insn()', and invoke `DONE'.
+For certain named patterns, it may invoke `FAIL' to tell the compiler
+to use an alternate way of performing that task. If it invokes neither
+`DONE' nor `FAIL', the template given in the pattern is inserted, as if
+the `define_expand' were a `define_insn'.
+
+ Once the insn list is generated, various optimization passes convert,
+replace, and rearrange the insns in the insn list. This is where the
+`define_split' and `define_peephole' patterns get used, for example.
+
+ Finally, the insn list's RTL is matched up with the RTL templates in
+the `define_insn' patterns, and those patterns are used to emit the
+final assembly code. For this purpose, each named `define_insn' acts
+like it's unnamed, since the names are ignored.
+
projects / msp430-gcc.git / blobdiff