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