This is doc/gccint.info, produced by makeinfo version 4.8 from
doc/gccint.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

   Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: gccint.info,  Node: Top,  Next: Contributing,  Up: (DIR)

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
front ends for new languages.  It corresponds to GCC version 3.2.2.
The use of the GNU compilers is documented in a separate manual.  *Note
Introduction: (gcc)Top.

   This manual is mainly a reference manual rather than a tutorial.  It
discusses how to contribute to GCC (*note Contributing::), the
characteristics of the machines supported by GCC as hosts and targets
(*note Portability::), how GCC relates to the ABIs on such systems
(*note Interface::), and the characteristics of the languages for which
GCC front ends are written (*note Languages::).  It then describes the
GCC source tree structure and build system, some of the interfaces to
GCC front ends, and how support for a target system is implemented in
GCC.

   Additional tutorial information is linked to from
`http://gcc.gnu.org/readings.html'.

* Menu:

* Contributing::    How to contribute to testing and developing GCC.
* Portability::     Goals of GCC's portability features.
* Interface::       Function-call interface of GCC output.
* Languages::       Languages for which GCC front ends are written.
* Source Tree::     GCC source tree structure and build system.
* Passes::          Order of passes, what they do, and what each file is for.
* Trees::           The source representation used by the C and C++ front ends.
* RTL::             The intermediate representation that most passes work on.
* Machine Desc::    How to write machine description instruction patterns.
* Target Macros::   How to write the machine description C macros and functions.
* Host Config::     Writing the `xm-MACHINE.h' file.
* Fragments::       Writing the `t-TARGET' and `x-HOST' files.
* Collect2::        How `collect2' works; how it finds `ld'.
* Header Dirs::     Understanding the standard header file directories.

* Funding::         How to help assure funding for free software.
* GNU Project::     The GNU Project and GNU/Linux.

* Copying::         GNU General Public License says
                     how you can copy and share GCC.
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors::    People who have contributed to GCC.

* Option Index::    Index to command line options.
* Index::	    Index of concepts and symbol names.


File: gccint.info,  Node: Contributing,  Next: Portability,  Prev: Top,  Up: Top

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
`http://gcc.gnu.org/cvs.html').  Source and binary snapshots are also
available for FTP; see `http://gcc.gnu.org/snapshots.html'.

   If you would like to work on improvements to GCC, please read the
advice at these URLs:

     `http://gcc.gnu.org/contribute.html'
     `http://gcc.gnu.org/contributewhy.html'

for information on how to make useful contributions and avoid
duplication of effort.  Suggested projects are listed at
`http://gcc.gnu.org/projects/'.


File: gccint.info,  Node: Portability,  Next: Interface,  Prev: Contributing,  Up: Top

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
address 8-bit bytes and have several general registers.  Elegance,
theoretical power and simplicity are only secondary.

   GCC gets most of the information about the target machine from a
machine description which gives an algebraic formula for each of the
machine's instructions.  This is a very clean way to describe the
target.  But when the compiler needs information that is difficult to
express in this fashion, I have not hesitated to define an ad-hoc
parameter to the machine description.  The purpose of portability is to
reduce the total work needed on the compiler; it was not of interest
for its own sake.

   GCC does not contain machine dependent code, but it does contain code
that depends on machine parameters such as endianness (whether the most
significant byte has the highest or lowest address of the bytes in a
word) and the availability of autoincrement addressing.  In the
RTL-generation pass, it is often necessary to have multiple strategies
for generating code for a particular kind of syntax tree, strategies
that are usable for different combinations of parameters.  Often I have
not tried to address all possible cases, but only the common ones or
only the ones that I have encountered.  As a result, a new target may
require additional strategies.  You will know if this happens because
the compiler will call `abort'.  Fortunately, the new strategies can be
added in a machine-independent fashion, and will affect only the target
machines that need them.


File: gccint.info,  Node: Interface,  Next: Languages,  Prev: Portability,  Up: Top

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
machine-description macros described (*note Target Macros::).

   However, returning of structure and union values is done differently
on some target machines.  As a result, functions compiled with PCC
returning such types cannot be called from code compiled with GCC, and
vice versa.  This does not cause trouble often because few Unix library
routines return structures or unions.

   GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
long in the same registers used for `int' or `double' return values.
(GCC typically allocates variables of such types in registers also.)
Structures and unions of other sizes are returned by storing them into
an address passed by the caller (usually in a register).  The
machine-description macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE'
tell GCC where to pass this address.

   By contrast, PCC on most target machines returns structures and
unions of any size by copying the data into an area of static storage,
and then returning the address of that storage as if it were a pointer
value.  The caller must copy the data from that memory area to the
place where the value is wanted.  This is slower than the method used
by GCC, and fails to be reentrant.

   On some target machines, such as RISC machines and the 80386, the
standard system convention is to pass to the subroutine the address of
where to return the value.  On these machines, GCC has been configured
to be compatible with the standard compiler, when this method is used.
It may not be compatible for structures of 1, 2, 4 or 8 bytes.

   GCC uses the system's standard convention for passing arguments.  On
some machines, the first few arguments are passed in registers; in
others, all are passed on the stack.  It would be possible to use
registers for argument passing on any machine, and this would probably
result in a significant speedup.  But the result would be complete
incompatibility with code that follows the standard convention.  So this
change is practical only if you are switching to GCC as the sole C
compiler for the system.  We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
compile the libraries with GCC.

   On some machines (particularly the Sparc), certain types of arguments
are passed "by invisible reference".  This means that the value is
stored in memory, and the address of the memory location is passed to
the subroutine.

   If you use `longjmp', beware of automatic variables.  ISO C says that
automatic variables that are not declared `volatile' have undefined
values after a `longjmp'.  And this is all GCC promises to do, because
it is very difficult to restore register variables correctly, and one
of GCC's features is that it can put variables in registers without
your asking it to.

   If you want a variable to be unaltered by `longjmp', and you don't
want to write `volatile' because old C compilers don't accept it, just
take the address of the variable.  If a variable's address is ever
taken, even if just to compute it and ignore it, then the variable
cannot go in a register:

     {
       int careful;
       &careful;
       ...
     }

   Code compiled with GCC may call certain library routines.  Most of
them handle arithmetic for which there are no instructions.  This
includes multiply and divide on some machines, and floating point
operations on any machine for which floating point support is disabled
with `-msoft-float'.  Some standard parts of the C library, such as
`bcopy' or `memcpy', are also called automatically.  The usual function
call interface is used for calling the library routines.

   Some of these routines can be defined in mostly machine-independent
C; they appear in `libgcc2.c'.  Others must be hand-written in assembly
language for each processor.  Wherever they are defined, they are
compiled into the support library, `libgcc.a', which is automatically
searched when you link programs with GCC.


File: gccint.info,  Node: Languages,  Next: Source Tree,  Prev: Interface,  Up: Top

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
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
GCC.

   Writing a compiler as a front end for GCC, rather than compiling
directly to assembler or generating C code which is then compiled by
GCC, has several advantages:

   * GCC front ends benefit from the support for many different target
     machines already present in GCC.

   * GCC front ends benefit from all the optimizations in GCC.  Some of
     these, such as alias analysis, may work better when GCC is
     compiling directly from source code then when it is compiling from
     generated C code.

   * Better debugging information is generated when compiling directly
     from source code than when going via intermediate generated C code.

   Because of the advantages of writing a compiler as a GCC front end,
GCC front ends have also been created for languages very different from
those for which GCC was designed, such as the declarative
logic/functional language Mercury.  For these reasons, it may also be
useful to implement compilers created for specialized purposes (for
example, as part of a research project) as GCC front ends.


File: gccint.info,  Node: Source Tree,  Next: Passes,  Prev: Languages,  Up: Top

5 Source Tree Structure and Build System
****************************************

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.

* Menu:

* Configure Terms:: Configuration terminology and history.
* Top Level::       The top level source directory.
* gcc Directory::   The `gcc' subdirectory.
* Test Suites::     The GCC test suites.


File: gccint.info,  Node: Configure Terms,  Next: Top Level,  Up: Source Tree

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.

   There are three system names that the build knows about: the machine
you are building on ("build"), the machine that you are building for
("host"), and the machine that GCC will produce code for ("target").
When you configure GCC, you specify these with `--build=', `--host=',
and `--target='.

   Specifying the host without specifying the build should be avoided,
as `configure' may (and once did) assume that the host you specify is
also the build, which may not be true.

   If build, host, and target are all the same, this is called a
"native".  If build and host are the same but target is different, this
is called a "cross".  If build, host, and target are all different this
is called a "canadian" (for obscure reasons dealing with Canada's
political party and the background of the person working on the build
at that time).  If host and target are the same, but build is
different, you are using a cross-compiler to build a native for a
different system.  Some people call this a "host-x-host", "crossed
native", or "cross-built native".  If build and target are the same,
but host is different, you are using a cross compiler to build a cross
compiler that produces code for the machine you're building on.  This
is rare, so there is no common way of describing it (although I propose
calling it a "crossback").

   If build and host are the same, the GCC you are building will also be
used to build the target libraries (like `libstdc++').  If build and
host are different, you must have already build and installed a cross
compiler that will be used to build the target libraries (if you
configured with `--target=foo-bar', this compiler will be called
`foo-bar-gcc').

   In the case of target libraries, the machine you're building for is
the machine you specified with `--target'.  So, build is the machine
you're building on (no change there), host is the machine you're
building for (the target libraries are built for the target, so host is
the target you specified), and target doesn't apply (because you're not
building a compiler, you're building libraries).  The configure/make
process will adjust these variables as needed.  It also sets
`$with_cross_host' to the original `--host' value in case you need it.

   The `libiberty' support library is built up to three times: once for
the host, once for the target (even if they are the same), and once for
the build if build and host are different.  This allows it to be used
by all programs which are generated in the course of the build process.


File: gccint.info,  Node: Top Level,  Next: gcc Directory,  Prev: Configure Terms,  Up: Source Tree

5.2 Top Level Source Directory
==============================

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:

`boehm-gc'
     The Boehm conservative garbage collector, used as part of the Java
     runtime library.

`contrib'
     Contributed scripts that may be found useful in conjunction with
     GCC.  One of these, `contrib/texi2pod.pl', is used to generate man
     pages from Texinfo manuals as part of the GCC build process.

`fastjar'
     An implementation of the `jar' command, used with the Java front
     end.

`gcc'
     The main sources of GCC itself (except for runtime libraries),
     including optimizers, support for different target architectures,
     language front ends, and test suites.  *Note The `gcc'
     Subdirectory: gcc Directory, for details.

`include'
     Headers for the `libiberty' library.

`libf2c'
     The Fortran runtime library.

`libffi'
     The `libffi' library, used as part of the Java runtime library.

`libiberty'
     The `libiberty' library, used for portability and for some
     generally useful data structures and algorithms.  *Note
     Introduction: (libiberty)Top, for more information about this
     library.

`libjava'
     The Java runtime library.

`libobjc'
     The Objective-C runtime library.

`libstdc++-v3'
     The C++ runtime library.

`maintainer-scripts'
     Scripts used by the `gccadmin' account on `gcc.gnu.org'.

`zlib'
     The `zlib' compression library, used by the Java front end and as
     part of the Java runtime library.

   The build system in the top level directory, including how recursion
into subdirectories works and how building runtime libraries for
multilibs is handled, is documented in a separate manual, included with
GNU Binutils.  *Note GNU configure and build system: (configure)Top,
for details.


File: gccint.info,  Node: gcc Directory,  Next: Test Suites,  Prev: Top Level,  Up: Source Tree

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
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.

* Menu:

* Subdirectories:: Subdirectories of `gcc'.
* Configuration::  The configuration process, and the files it uses.
* Build::          The build system in the `gcc' directory.
* Makefile::       Targets in `gcc/Makefile'.
* Library Files::  Library source files and headers under `gcc/'.
* Headers::        Headers installed by GCC.
* Documentation::  Building documentation in GCC.
* Front End::      Anatomy of a language front end.
* Back End::       Anatomy of a target back end.


File: gccint.info,  Node: Subdirectories,  Next: Configuration,  Up: gcc Directory

5.3.1 Subdirectories of `gcc'
-----------------------------

The `gcc' directory contains the following subdirectories:

`LANGUAGE'
     Subdirectories for various languages.  Directories containing a
     file `config-lang.in' are language subdirectories.  The contents of
     the subdirectories `cp' (for C++) and `objc' (for Objective-C) are
     documented in this manual (*note Passes and Files of the Compiler:
     Passes.); those for other languages are not.  *Note Anatomy of a
     Language Front End: Front End, for details of the files in these
     directories.

`config'
     Configuration files for supported architectures and operating
     systems.  *Note Anatomy of a Target Back End: Back End, for
     details of the files in thie directory.

`doc'
     Texinfo documentation for GCC, together with automatically
     generated man pages and support for converting the installation
     manual to HTML.  *Note Documentation::.

`fixinc'
     The support for fixing system headers to work with GCC.  See
     `fixinc/README' for more information.  The headers fixed by this
     mechanism are installed in `LIBSUBDIR/include'.  Along with those
     headers, `README-fixinc' is also installed, as
     `LIBSUBDIR/include/README'.

`ginclude'
     System headers installed by GCC, mainly those required by the C
     standard of freestanding implementations.  *Note Headers Installed
     by GCC: Headers, for details of when these and other headers are
     installed.

`intl'
     GNU `libintl', from GNU `gettext', for systems which do not
     include it in libc.  Properly, this directory should be at top
     level, parallel to the `gcc' directory.

`po'
     Message catalogs with translations of messages produced by GCC into
     various languages, `LANGUAGE.po'.  This directory also contains
     `gcc.pot', the template for these message catalogues, `exgettext',
     a wrapper around `gettext' to extract the messages from the GCC
     sources and create `gcc.pot', which is run by `make gcc.pot', and
     `EXCLUDES', a list of files from which messages should not be
     extracted.

`testsuite'
     The GCC test suites (except for those for runtime libraries).
     *Note Test Suites::.


File: gccint.info,  Node: Configuration,  Next: Build,  Prev: Subdirectories,  Up: gcc Directory

5.3.2 Configuration in the `gcc' Directory
------------------------------------------

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
used as a timestamp.

* Menu:

* Config Fragments::     Scripts used by `configure'.
* System Config::        The `config.gcc' file.
* Configuration Files::  Files created by running `configure'.


File: gccint.info,  Node: Config Fragments,  Next: System Config,  Up: Configuration

5.3.2.1 Scripts Used by `configure'
...................................

`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
     `config.guess' file in the `gcc' directory (that just calls the
     top level one) used?

   * The file `config.gcc' is used to handle configuration specific to
     the particular build, host or target machine.  (In general, this
     should only be used for features that cannot reasonably be tested
     in Autoconf feature tests.)  *Note The `config.gcc' File: System
     Config, for details of the contents of this file.

   * Each language subdirectory has a file `LANGUAGE/config-lang.in'
     that is used for front-end-specific configuration.  *Note The
     Front End `config-lang.in' File: Front End Config, for details of
     this file.

   * A helper script `configure.frag' is used as part of creating the
     output of `configure'.


File: gccint.info,  Node: System Config,  Next: Configuration Files,  Prev: Config Fragments,  Up: Configuration

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.


File: gccint.info,  Node: Configuration Files,  Prev: System Config,  Up: Configuration

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.

   * `Makefile' is constructed from `Makefile.in', together with the
     host and target fragments (*note Makefile Fragments: Fragments.)
     `t-TARGET' and `x-HOST' from `config', if any, and language
     Makefile fragments `LANGUAGE/Make-lang.in'.

   * `auto-host.h' contains information about the host machine
     determined by `configure'.  If the host machine is different from
     the build machine, then `auto-build.h' is also created, containing
     such information about the build machine.

   * `config.status' is a script that may be run to recreate the
     current configuration.

   * `configargs.h' is a header containing details of the arguments
     passed to `configure' to configure GCC, and of the thread model
     used.

   * `cstamp-h' is used as a timestamp.

   * `fixinc/Makefile' is constructed from `fixinc/Makefile.in'.

   * `gccbug', a script for reporting bugs in GCC, is constructed from
     `gccbug.in'.

   * `intl/Makefile' is constructed from `intl/Makefile.in'.

   * `mklibgcc', a shell script to create a Makefile to build libgcc,
     is constructed from `mklibgcc.in'.

   * If a language `config-lang.in' file (*note The Front End
     `config-lang.in' File: Front End Config.) sets `outputs', then the
     files listed in `outputs' there are also generated.

   The following configuration headers are created from the Makefile,
using `mkconfig.sh', rather than directly by `configure'.  `config.h',
`hconfig.h' and `tconfig.h' all contain the `xm-MACHINE.h' header, if
any, appropriate to the host, build and target machines respectively,
the configuration headers for the target, and some definitions; for the
host and build machines, these include the autoconfigured headers
generated by `configure'.  The other configuration headers are
determined by `config.gcc'.  They also contain the typedefs for `rtx',
`rtvec' and `tree'.

   * `config.h', for use in programs that run on the host machine.

   * `hconfig.h', for use in programs that run on the build machine.

   * `tconfig.h', for use in programs and libraries for the target
     machine.

   * `tm_p.h', which includes the header `MACHINE-protos.h' that
     contains prototypes for functions in the target `.c' file.  FIXME:
     why is such a separate header necessary?


File: gccint.info,  Node: Build,  Next: Makefile,  Prev: Configuration,  Up: gcc Directory

5.3.3 Build System in the `gcc' Directory
-----------------------------------------

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::).


File: gccint.info,  Node: Makefile,  Next: Library Files,  Prev: Build,  Up: gcc Directory

5.3.4 Makefile Targets
----------------------

`all'
     This is the default target.  Depending on what your
     build/host/target configuration is, it coordinates all the things
     that need to be built.

`doc'
     Produce info-formatted documentation.  Also, `make dvi' is
     available for DVI-formatted documentation, and `make
     generated-manpages' to generate man pages.

`mostlyclean'
     Delete the files made while building the compiler.

`clean'
     That, and all the other files built by `make all'.

`distclean'
     That, and all the files created by `configure'.

`extraclean'
     That, and any temporary or intermediate files, like emacs backup
     files.

`maintainer-clean'
     Distclean plus any file that can be generated from other files.
     Note that additional tools may be required beyond what is normally
     needed to build gcc.

`install'
     Installs gcc.

`uninstall'
     Deletes installed files.

`check'
     Run the testsuite.  This creates a `testsuite' subdirectory that
     has various `.sum' and `.log' files containing the results of the
     testing.  You can run subsets with, for example, `make check-gcc'.
     You can specify specific tests by setting RUNTESTFLAGS to be the
     name of the `.exp' file, optionally followed by (for some tests)
     an equals and a file wildcard, like:

          make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"

     Note that running the testsuite may require additional tools be
     installed, such as TCL or dejagnu.

`bootstrap'
     Builds gcc three times--once with the native compiler, once with
     the native-built compiler it just built, and once with the
     compiler it built the second time.  In theory, the last two should
     produce the same results, which `make compare' can check.  Each
     step of this process is called a "stage", and the results of each
     stage N (N = 1...3) are copied to a subdirectory `stageN/'.

`bootstrap-lean'
     Like `bootstrap', except that the various stages are removed once
     they're no longer needed.  This saves disk space.

`bubblestrap'
     Once bootstrapped, this incrementally rebuilds each of the three
     stages, one at a time.  It does this by "bubbling" the stages up
     from their subdirectories, rebuilding them, and copying them back
     to their subdirectories.  This will allow you to, for example,
     quickly rebuild a bootstrapped compiler after changing the
     sources, without having to do a full bootstrap.

`quickstrap'
     Rebuilds the most recently built stage.  Since each stage requires
     special invocation, using this target means you don't have to keep
     track of which stage you're on or what invocation that stage needs.

`cleanstrap'
     Removed everything (`make clean') and rebuilds (`make bootstrap').

`stageN (N = 1...4)'
     For each stage, moves the appropriate files to the `stageN'
     subdirectory.

`unstageN (N = 1...4)'
     Undoes the corresponding `stageN'.

`restageN (N = 1...4)'
     Undoes the corresponding `stageN' and rebuilds it with the
     appropriate flags.

`compare'
     Compares the results of stages 2 and 3.  This ensures that the
     compiler is running properly, since it should produce the same
     object files regardless of how it itself was compiled.



File: gccint.info,  Node: Library Files,  Next: Headers,  Prev: Makefile,  Up: 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.


File: gccint.info,  Node: Headers,  Next: Documentation,  Prev: Library Files,  Up: gcc Directory

5.3.6 Headers Installed by GCC
------------------------------

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
in `LIBSUBDIR/include'.  Headers for non-C runtime libraries are also
installed by GCC; these are not documented here.  (FIXME: document them
somewhere.)

   Several of the headers GCC installs are in the `ginclude' directory.
These headers, `iso646.h', `stdarg.h', `stdbool.h', `stddef.h' and
`varargs.h', are installed in `LIBSUBDIR/include', unless the target
Makefile fragment (*note Target Fragment::) overrides this by setting
`USER_H'.

   In addition to these headers and those generated by fixing system
headers to work with GCC, some other headers may also be installed in
`LIBSUBDIR/include'.  `config.gcc' may set `extra_headers'; this
specifies additional headers under `config' to be installed on some
systems.  GCC normally installs a `<float.h>' file; these are kept as
`config/float-FORMAT.h', where FORMAT is specified by a `float_format'
setting in `config.gcc', and a setting `float_format=none' disables
installation of this header.  GCC also installs its own version of
`<limits.h>'; this is generated from `glimits.h', together with
`limitx.h' and `limity.h' if the system also has its own version of
`<limits.h>'.  (GCC provides its own header because it is required of
ISO C freestanding implementations, but needs to include the system
header from its own header as well because other standards such as
POSIX specify additional values to be defined in `<limits.h>'.)  The
system's `<limits.h>' header is used via
`LIBSUBDIR/include/syslimits.h', which is copied from `gsyslimits.h' if
it does not need fixing to work with GCC; if it needs fixing,
`syslimits.h' is the fixed copy.


File: gccint.info,  Node: Documentation,  Next: Front End,  Prev: Headers,  Up: gcc Directory

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.

* Menu:

* Texinfo Manuals::      GCC manuals in Texinfo format.
* Man Page Generation::  Generating man pages from Texinfo manuals.
* Miscellaneous Docs::   Miscellaneous text files with documentation.


File: gccint.info,  Node: Texinfo Manuals,  Next: Man Page Generation,  Up: Documentation

5.3.7.1 Texinfo Manuals
.......................

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
`doc/include':

`fdl.texi'
     The GNU Free Documentation License.

`funding.texi'
     The section "Funding Free Software".

`gcc-common.texi'
     Common definitions for manuals.

`gpl.texi'
     The GNU General Public License.

`texinfo.tex'
     A copy of `texinfo.tex' known to work with the GCC manuals.

   DVI formatted manuals are generated by `make dvi', which uses
`texi2dvi' (via the Makefile macro `$(TEXI2DVI)').  Info manuals are
generated by `make info' (which is run as part of a bootstrap); this
generates the manuals in the source directory, using `makeinfo' via the
Makefile macro `$(MAKEINFO)', and they are included in release
distributions.

   Manuals are also provided on the GCC web site, in both HTML and
PostScript forms.  This is done via the script
`maintainer-scripts/update_web_docs'.  Each manual to be provided
online must be listed in the definition of `MANUALS' in that file; a
file `NAME.texi' must only appear once in the source tree, and the
output manual must have the same name as the source file.  (However,
other Texinfo files, included in manuals but not themselves the root
files of manuals, may have names that appear more than once in the
source tree.)  The manual file `NAME.texi' should only include other
files in its own directory or in `doc/include'.  HTML manuals will be
generated by `makeinfo --html' and PostScript manuals by `texi2dvi' and
`dvips'.  All Texinfo files that are parts of manuals must be checked
into CVS, even if they are generated files, for the generation of
online manuals to work.

   The installation manual, `doc/install.texi', is also provided on the
GCC web site.  The HTML version is generated by the script
`doc/install.texi2html'.


File: gccint.info,  Node: Man Page Generation,  Next: Miscellaneous Docs,  Prev: Texinfo Manuals,  Up: Documentation

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
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
other man pages are generated from Texinfo manuals.)

   Because many systems may not have the necessary tools installed to
generate the man pages, they are only generated if the `configure'
script detects that recent enough tools are installed, and the
Makefiles allow generating man pages to fail without aborting the
build.  Man pages are also included in release distributions.  They are
generated in the source directory.

   Magic comments in Texinfo files starting `@c man' control what parts
of a Texinfo file go into a man page.  Only a subset of Texinfo is
supported by `texi2pod.pl', and it may be necessary to add support for
more Texinfo features to this script when generating new man pages.  To
improve the man page output, some special Texinfo macros are provided
in `doc/include/gcc-common.texi' which `texi2pod.pl' understands:

`@gcctabopt'
     Use in the form `@table @gcctabopt' for tables of options, where
     for printed output the effect of `@code' is better than that of
     `@option' but for man page output a different effect is wanted.

`@gccoptlist'
     Use for summary lists of options in manuals.

`@gol'
     Use at the end of each line inside `@gccoptlist'.  This is
     necessary to avoid problems with differences in how the
     `@gccoptlist' macro is handled by different Texinfo formatters.

   FIXME: describe the `texi2pod.pl' input language and magic comments
in more detail.


File: gccint.info,  Node: Miscellaneous Docs,  Prev: Man Page Generation,  Up: 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:

`ABOUT-GCC-NLS'
     Notes on GCC's Native Language Support.  FIXME: this should be
     part of this manual rather than a separate file.

`ABOUT-NLS'
     Notes on the Free Translation Project.

`COPYING'
     The GNU General Public License.

`COPYING.LIB'
     The GNU Lesser General Public License.

`*ChangeLog*'
`*/ChangeLog*'
     Change log files for various parts of GCC.

`LANGUAGES'
     Details of a few changes to the GCC front-end interface.  FIXME:
     the information in this file should be part of general
     documentation of the front-end interface in this manual.

`ONEWS'
     Information about new features in old versions of GCC.  (For recent
     versions, the information is on the GCC web site.)

`README.Portability'
     Information about portability issues when writing code in GCC.
     FIXME: why isn't this part of this manual or of the GCC Coding
     Conventions?

`SERVICE'
     A pointer to the GNU Service Directory.

   FIXME: document such files in subdirectories, at least `config',
`cp', `objc', `testsuite'.


File: gccint.info,  Node: Front End,  Next: Back End,  Prev: Documentation,  Up: gcc Directory

5.3.8 Anatomy of a Language Front End
-------------------------------------

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
     End Directory, for details.

   * A mention of the language in the list of supported languages in
     `gcc/doc/install.texi'.

   * Details of contributors to that front end in
     `gcc/doc/contrib.texi'.  If the details are in that front end's
     own manual then there should be a link to that manual's list in
     `contrib.texi'.

   * Information about support for that language in
     `gcc/doc/frontends.texi'.

   * Information about standards for that language, and the front end's
     support for them, in `gcc/doc/standards.texi'.  This may be a link
     to such information in the front end's own manual.

   * Details of source file suffixes for that language and `-x LANG'
     options supported, in `gcc/doc/invoke.texi'.

   * Entries in `default_compilers' in `gcc.c' for source file suffixes
     for that language.

   * Preferably test suites, which may be under `gcc/testsuite' or
     runtime library directories.  FIXME: document somewhere how to
     write test suite harnesses.

   * Probably a runtime library for the language, outside the `gcc'
     directory.  FIXME: document this further.

   * Details of the directories of any runtime libraries in
     `gcc/doc/sourcebuild.texi'.

   If the front end is added to the official GCC CVS repository, the
following are also necessary:

   * At least one GNATS category for bugs in that front end and runtime
     libraries.  This category needs to be mentioned in
     `gcc/gccbug.in', and in `gnats.html' on the GCC web site, as well
     as being added to the GNATS database.

   * Normally, one or more maintainers of that front end listed in
     `MAINTAINERS'.

   * Mentions on the GCC web site in `index.html' and `frontends.html',
     with any relevant links on `readings.html'.  (Front ends that are
     not an official part of GCC may also be listed on
     `frontends.html', with relevant links.)

   * A news item on `index.html', and possibly an announcement on the
     <gcc-announce@gcc.gnu.org> mailing list.

   * The front end's manuals should be mentioned in
     `maintainer-scripts/update_web_docs' (*note Texinfo Manuals::) and
     the online manuals should be linked to from
     `onlinedocs/index.html'.

   * Any old releases or CVS repositories of the front end, before its
     inclusion in GCC, should be made available on the GCC FTP site
     `ftp://gcc.gnu.org/pub/gcc/old-releases/'.

   * The release and snapshot script `maintainer-scripts/gcc_release'
     should be updated to generate appropriate tarballs for this front
     end.

   * If this front end includes its own version files that include the
     current date, `maintainer-scripts/update_version' should be
     updated accordingly.

   * `CVSROOT/modules' in the GCC CVS repository should be updated.

* Menu:

* Front End Directory::  The front end `LANGUAGE' directory.
* Front End Config::     The front end `config-lang.in' file.


File: gccint.info,  Node: Front End Directory,  Next: Front End Config,  Up: Front End

5.3.8.1 The Front End `LANGUAGE' Directory
..........................................

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
special and other parts of the compiler depend on their names:

`config-lang.in'
     This file is required in all language subdirectories.  *Note The
     Front End `config-lang.in' File: Front End Config, for details of
     its contents

`Make-lang.in'
     This file is required in all language subdirectories.  It contains
     targets `LANG.HOOK' (where `LANG' is the setting of `language' in
     `config-lang.in') for the following values of `HOOK', and any
     other Makefile rules required to build those targets (which may if
     necessary use other Makefiles specified in `outputs' in
     `config-lang.in', although this is deprecated).

    `all.build'
    `all.cross'
    `start.encap'
    `rest.encap'
          FIXME: exactly what goes in each of these targets?

    `info'
          Build info documentation for the front end, in the source
          directory.  This target is only called by `make bootstrap' if
          a suitable version of `makeinfo' is available, so does not
          need to check for this, and should fail if an error occurs.

    `dvi'
          Build DVI documentation for the front end, in the build
          directory.  This should be done using `$(TEXI2DVI)', with
          appropriate `-I' arguments pointing to directories of
          included files.

    `generated-manpages'
          Build generated man pages for the front end from Texinfo
          manuals (*note Man Page Generation::), in the source
          directory.  This target is only called if the necessary tools
          are available, but should ignore errors so as not to stop the
          build if errors occur; man pages are optional and the tools
          involved may be installed in a broken way.

    `install-normal'
          FIXME: what is this target for?

    `install-common'
          Install everything that is part of the front end, apart from
          the compiler executables listed in `compilers' in
          `config-lang.in' that are installed in `LIBSUBDIR' by the
          main `Makefile'.

    `install-info'
          Install info documentation for the front end, if it is
          present in the source directory.  (It may not be present if a
          suitable version of `makeinfo' was not installed.)  This
          target should run the command `install-info' to update the
          info directory, but should ignore errors when running that
          command.

    `install-man'
          Install man pages for the front end.  This target should
          ignore errors.

    `uninstall'
          Uninstall files installed by installing the compiler.  This is
          currently documented not to be supported, so the hook need
          not do anything.

    `mostlyclean'
    `clean'
    `distclean'
    `extraclean'
    `maintainer-clean'
          Except for `extraclean', the language parts of the standard
          GNU `*clean' targets. *Note Standard Targets for Users:
          (standards)Standard Targets, for details of the standard
          targets.  `extraclean' does `distclean' and also deletes
          anything likely to be found in the source directory that
          shouldn't be in the distribution.  For GCC,
          `maintainer-clean' should delete all generated files in the
          source directory that are not checked into CVS, but should
          not delete anything checked into CVS.

    `stage1'
    `stage2'
    `stage3'
    `stage4'
          Move to the stage directory files not included in
          `stagestuff' in `config-lang.in' or otherwise moved by the
          main `Makefile'.

`lang-options.h'
     This file provides entries for `documented_lang_options' in
     `toplev.c' describing command-line options the front end accepts
     for `--help' output.

`lang-specs.h'
     This file provides entries for `default_compilers' in `gcc.c'
     which override the default of giving an error that a compiler for
     that language is not installed.

`LANGUAGE-tree.def'
     This file, which need not exist, defines any language-specific tree
     codes.


File: gccint.info,  Node: Front End Config,  Prev: Front End Directory,  Up: Front End

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
language:

`language'
     This definition must be present, and gives the name of the language
     for some purposes such as arguments to `--enable-languages'.

`lang_requires'
     If defined, this variable lists (space-separated) language front
     ends other than C that this front end requires to be enabled (with
     the names given being their `language' settings).  For example, the
     Java front end depends on the C++ front end, so sets
     `lang_requires=c++'.

`target_libs'
     If defined, this variable lists (space-separated) targets in the
     top level `Makefile' to build the runtime libraries for this
     language, such as `target-libobjc'.

`lang_dirs'
     If defined, this variable lists (space-separated) top level
     directories (parallel to `gcc'), apart from the runtime libraries,
     that should not be configured if this front end is not built.

`build_by_default'
     If defined to `no', this language front end is not built unless
     enabled in a `--enable-languages' argument.  Otherwise, front ends
     are built by default, subject to any special logic in
     `configure.in' (as is present to disable the Ada front end if the
     Ada compiler is not already installed).

`boot_language'
     If defined to `yes', this front end is built in stage 1 of the
     bootstrap.  This is only relevant to front ends written in their
     own languages.

`compilers'
     If defined, a space-separated list of compiler executables that
     should be installed in `LIBSUBDIR'.  The names here will each end
     with `\$(exeext)'.

`stagestuff'
     If defined, a space-separated list of files that should be moved to
     the `stageN' directories in each stage of bootstrap.

`outputs'
     If defined, a space-separated list of files that should be
     generated by `configure' substituting values in them.  This
     mechanism can be used to create a file `LANGUAGE/Makefile' from
     `LANGUAGE/Makefile.in', but this is deprecated, building
     everything from the single `gcc/Makefile' is preferred.


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.


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.


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.


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.


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.


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.

   * Jump optimization is repeated, this time including cross-jumping
     and deletion of no-op move instructions.

     The option `-dJ' causes a debugging dump of the RTL code after
     this pass.  This dump file's name is made by appending `.jump2' 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'.


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'.


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.


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.


File: gccint.info,  Node: Macros and Functions,  Next: Identifiers,  Up: Tree overview

7.2.1 Trees
-----------

This section is not here yet.


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.



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.


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'.


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.


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.



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.



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.



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.


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[]'.



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.



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.


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.



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.


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)'.


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.


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.


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'.


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.


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'.


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.


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.


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::.


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.


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.



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.


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.


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.


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.


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.


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.


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.


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'.


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.


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.


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.

