gnu1987/gnu1988/gcc-1.21/internals-5

Info file internals, produced by Makeinfo, -*- Text -*-
from input file internals.texinfo.



This file documents the internals of the GNU compiler.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU CC General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.






File: internals,  Node: Peephole Definitions,  Next: Expander Definitions,  Prev: Jump Patterns,  Up: Machine Desc

Defining Machine-Specific Peephole Optimizers
=============================================

In addition to instruction patterns the `md' file may contain definitions
of machine-specific peephole optimizations.

The combiner does not notice certain peephole optimizations when the data
flow in the program does not suggest that it should try them.  For example,
sometimes two consecutive insns related in purpose can be combined even
though the second one does not appear to use a register computed in the
first one.  A machine-specific peephole optimizer can detect such
opportunities.

A definition looks like this:

     (define_peephole
       [INSN-PATTERN-1
        INSN-PATTERN-2
        ...]
       "CONDITION"
       "TEMPLATE")


In this skeleton, INSN-PATTERN-1 and so on are patterns to match
consecutive instructions.  The optimization applies to a sequence of
instructions when INSN-PATTERN-1 matches the first one, INSN-PATTERN-2
matches the next, and so on.

INSN-PATTERN-1 and so on look *almost* like the second operand of
`define_insn'.  There is one important difference: this pattern is an RTX,
not a vector.  If the `define_insn' pattern would be a vector of one
element, the INSN-PATTERN should be just that element, no vector.  If the
`define_insn' pattern would have multiple elements then the INSN-PATTERN
must place the vector inside an explicit `parallel' RTX.

The operands of the instructions are matched with `match_operands' and
`match_dup', as usual).  What is not usual is that the operand numbers
apply to all the instruction patterns in the definition.  So, you can check
for identical operands in two instructions by using `match_operand' in one
instruction and `match_dup' in the other.

The operand constraints used in `match_operand' patterns do not have any
direct effect on the applicability of the optimization, but they will be
validated afterward, so write constraints that are sure to fit whenever the
optimization is applied.  It is safe to use `"g"' for each operand.

Once a sequence of instructions matches the patterns, the CONDITION is
checked.  This is a C expression which makes the final decision whether to
perform the optimization (do so if the expression is nonzero).  If
CONDITION is omitted (in other words, the string is empty) then the
optimization is applied to every sequence of instructions that matches the
patterns.

The defined peephole optimizations are applied after register allocation is
complete.  Therefore, the optimizer can check which operands have ended up
in which kinds of registers, just by looking at the operands.

The way to refer to the operands in CONDITION is to write `operands[I]' for
operand number I (as matched by `(match_operand I ...)').  Use the variable
`insn' to refer to the last of the insns being matched; use `PREV_INSN' to
find the preceding insns (but be careful to skip over any `note' insns that
intervene).

When optimizing computations with intermediate results, you can use
CONDITION to match only when the intermediate results are not used
elsewhere.  Use the C expression `dead_or_set_p (INSN, OP)', where INSN is
the insn in which you expect the value to be used for the last time (from
the value of `insn', together with use of `PREV_INSN'), and OP is the
intermediate value (from `operands[I]').

Applying the optimization means replacing the sequence of instructions with
one new instruction.  The TEMPLATE controls ultimate output of assembler
code for this combined instruction.  It works exactly like the template of
a `define_insn'.  Operand numbers in this template are the same ones used
in matching the original sequence of instructions.

The result of a defined peephole optimizer does not need to match any of
the instruction patterns, and it does not have an opportunity to match
them.  The peephole optimizer definition itself serves as the instruction
pattern to control how the instruction is output.

Defined peephole optimizers are run in the last jump optimization pass, so
the instructions they produce are never combined or rearranged
automatically in any way.

Here is an example, taken from the 68000 machine description:

     (define_peephole
       [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
        (set (match_operand:DF 0 "register_operand" "f")
             (match_operand:DF 1 "register_operand" "ad"))]
       "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
       "*
     {
       rtx xoperands[2];
       xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
     #ifdef MOTOROLA
       output_asm_insn (\"move.l %1,(sp)\", xoperands);
       output_asm_insn (\"move.l %1,-(sp)\", operands);
       return \"fmove.d (sp)+,%0\";
     #else
       output_asm_insn (\"movel %1,sp@\", xoperands);
       output_asm_insn (\"movel %1,sp@-\", operands);
       return \"fmoved sp@+,%0\";
     #endif
     }
     ")


The effect of this optimization is to change

     jbsr _foobar
     addql #4,sp
     movel d1,sp@-
     movel d0,sp@-
     fmoved sp@+,fp0


into

     jbsr _foobar
     movel d1,sp@
     movel d0,sp@-
     fmoved sp@+,fp0



File: internals,  Node: Expander Definitions,  Prev: Peephole Definitions,  Up: Machine Desc

Defining RTL Sequences for Code Generation
==========================================

On some target machines, some standard pattern names for RTL generation
cannot be handled with single insn, but a sequence of RTL insns can
represent them.  For these target machines, you can write a `define_expand'
to specify how to generate the sequence of RTL.

A `define_expand' is an RTL expression that looks almost like a
`define_insn'; but, unlike the latter, a `define_expand' is used only for
RTL generation and it can produce more than one RTL insn.

A `define_expand' RTX has four operands:

   * The name.  Each `define_expand' must have a name, since the only use
     for it is to refer to it by name.

   * The RTL template.  This is just like the RTL template for a
     `define_peephole' in that it is a vector of RTL expressions each being
     one insn.

   * The condition, a string containing a C expression.  This expression is
     used to express how the availability of this pattern depends on
     subclasses of target machine, selected by command-line options when
     GNU CC is run.  This is just like the condition of a `define_insn'
     that has a standard name.

   * The preparation statements, a string containing zero or more C
     statements which are to be executed before RTL code is generated from
     the RTL template.

     Usually these statements prepare temporary registers for use as
     internal operands in the RTL template, but they can also generate RTL
     insns directly by calling routines such as `emit_insn', etc.  Any such
     insns precede the ones that come from the RTL template.

The RTL template, in addition to controlling generation of RTL insns, also
describes the operands that need to be specified when this pattern is used.
 In particular, it gives a predicate for each operand.

A true operand, which need to be specified in order to generate RTL from
the pattern, should be described with a `match_operand' in its first
occurrence in the RTL template.  This enters information on the operand's
predicate into the tables that record such things.  GNU CC uses the
information to preload the operand into a register if that is required for
valid RTL code.  If the operand is referred to more than once, subsequent
references should use `match_dup'.

The RTL template may also refer to internal ``operands'' which are
temporary registers or labels used only within the sequence made by the
`define_expand'.  Internal operands are substituted into the RTL template
with `match_dup', never with `match_operand'.  The values of the internal
operands are not passed in as arguments by the compiler when it requests
use of this pattern.  Instead, they are computed within the pattern, in the
preparation statements.  These statements compute the values and store them
into the appropriate elements of `operands' so that `match_dup' can find
them.

There are two special macros defined for use in the preparation statements:
`DONE' and `FAIL'.  Use them with a following semicolon, as a statement.

`DONE'
     Use the `DONE' macro to end RTL generation for the pattern.  The only
     RTL insns resulting from the pattern on this occasion will be those
     already emitted by explicit calls to `emit_insn' within the
     preparation statements; the RTL template will not be generated.

`FAIL'
     Make the pattern fail on this occasion.  When a pattern fails, it
     means that the pattern was not truly available.  The calling routines
     in the compiler will try other strategies for code generation using
     other patterns.

     Failure is currently supported only for binary operations (addition,
     multiplication, shifting, etc.).

     Do not emit any insns explicitly with `emit_insn' before failing.

Here is an example, the definition of left-shift for the SPUR chip:

     (define_expand "ashlsi3"
       [(set (match_operand:SI 0 "register_operand" "")
             (ashift:SI
               (match_operand:SI 1 "register_operand" "")
               (match_operand:SI 2 "nonmemory_operand" "")))]
       ""
       "
     {
       if (GET_CODE (operands[2]) != CONST_INT
           || (unsigned) INTVAL (operands[2]) > 3)
         FAIL;
     }")


This example uses `define_expand' so that it can generate an RTL insn for
shifting when the shift-count is in the supported range of 0 to 3 but fail
in other cases where machine insns aren't available.  When it fails, the
compiler tries another strategy using different patterns (such as, a
library call).

If the compiler were able to handle nontrivial condition-strings in
patterns with names, then there would be possible to use a `define_insn' in
that case.  Here is another case (zero-extension on the 68000) which makes
more use of the power of `define_expand':

     (define_expand "zero_extendhisi2"
       [(set (match_operand:SI 0 "general_operand" "")
             (const_int 0))
        (set (strict_low_part 
               (subreg:HI
                 (match_operand:SI 0 "general_operand" "")
                 0))
             (match_operand:HI 1 "general_operand" ""))]
       ""
       "operands[1] = make_safe_from (operands[1], operands[0]);")


Here two RTL insns are generated, one to clear the entire output operand
and the other to copy the input operand into its low half.  This sequence
is incorrect if the input operand refers to [the old value of] the output
operand, so the preparation statement makes sure this isn't so.  The
function `make_safe_from' copies the `operands[1]' into a temporary
register if it refers to `operands[0]'.  It does this by emitting another
RTL insn.

Finally, a third example shows the use of an internal operand. 
Zero-extension on the SPUR chip is done by `and'-ing the result against a
halfword mask.  But this mask cannot be represented by a `const_int'
because the constant value is too large to be legitimate on this machine. 
So it must be copied into a register with `force_reg' and then the register
used in the `and'.

     (define_expand "zero_extendhisi2"
       [(set (match_operand:SI 0 "register_operand" "")
             (and:SI (subreg:SI
                       (match_operand:HI 1 "register_operand" "")
                       0)
                     (match_dup 2)))]
       ""
       "operands[2]
          = force_reg (SImode, gen_rtx (CONST_INT,
                                        VOIDmode, 65535)); ")



File: internals,  Node: Machine Macros,  Next: Config,  Prev: Machine Desc,  Up: Top

Machine Description Macros
**************************

The other half of the machine description is a C header file conventionally
given the name `tm-MACHINE.h'.  The file `tm.h' should be a link to it. 
The header file `config.h' includes `tm.h' and most compiler source files
include `config.h'.


* Menu:

* Run-time Target::     Defining -m options like -m68000 and -m68020.
* Storage Layout::      Defining sizes and alignments of data types.
* Registers::           Naming and describing the hardware registers.
* Register Classes::    Defining the classes of hardware registers.
* Stack Layout::        Defining which way the stack grows and by how much.
* Library Names::       Specifying names of subroutines to call automatically.
* Addressing Modes::    Defining addressing modes valid for memory operands.
* Condition Code::      Defining how insns update the condition code.
* Assembler Format::    Defining how to write insns and pseudo-ops to output.
* Misc::                Everything else.



File: internals,  Node: Run-time Target,  Next: Storage Layout,  Prev: Machine Macros,  Up: Machine Macros

Run-time Target Specification
=============================

`CPP_PREDEFINES'
     Define this to be a string constant containing `-D' options to define
     the predefined macros that identify this machine and system.

     For example, on the Sun, one can use the value

          "-Dmc68000 -Dsun -Dunix"


`extern int target_flags;'
     This declaration should be present.

`TARGET_...'
     This series of macros is to allow compiler command arguments to enable
     or disable the use of optional features of the target machine.  For
     example, one machine description serves both the 68000 and the 68020;
     a command argument tells the compiler whether it should use 68020-only
     instructions or not.  This command argument works by means of a macro
     `TARGET_68020' that tests a bit in `target_flags'.

     Define a macro `TARGET_FEATURENAME' for each such option.  Its
     definition should test a bit in `target_flags'; for example:

          #define TARGET_68020 (target_flags & 1)


     One place where these macros are used is in the condition-expressions
     of instruction patterns.  Note how `TARGET_68020' appears frequently
     in the 68000 machine description file, `m68k.md'.  Another place they
     are used is in the definitions of the other macros in the
     `tm-MACHINE.h' file.

`TARGET_SWITCHES'
     This macro defines names of command options to set and clear bits in
     `target_flags'.  Its definition is an initializer with a subgrouping
     for each command option.

     Each subgrouping contains a string constant, that defines the option
     name, and a number, which contains the bits to set in `target_flags'. 
     A negative number says to clear bits instead; the negative of the
     number is which bits to clear.  The actual option name is made by
     appending `-m' to the specified name.

     One of the subgroupings should have a null string.  The number in this
     grouping is the default value for `target_flags'.  Any target options
     act starting with that value.

     Here is an example which defines `-m68000' and `-m68020' with opposite
     meanings, and picks the latter as the default:

          #define TARGET_SWITCHES \
            { { "68020", 1},      \
              { "68000", -1},     \
              { "", 1}}


Sometimes certain combinations of command options do not make sense on a
particular target machine.  You can define a macro `OVERRIDE_OPTIONS' to
take account of this.  This macro, if defined, is executed once just after
all the command options have been parsed.


File: internals,  Node: Storage Layout,  Next: Registers,  Prev: Run-time Target,  Up: Machine Macros

Storage Layout
==============

Note that the definitions of the macros in this table which are sizes or
alignments measured in bits do not need to be constant.  They can be C
expressions that refer to static variables, such as the `target_flags'. 
*note Run-time Target::.

`BITS_BIG_ENDIAN'
     Define this macro if the most significant bit in a byte has the lowest
     number.  This means that bit-field instructions count from the most
     significant bit.  If the machine has no bit-field instructions, this
     macro is irrelevant.

`BYTES_BIG_ENDIAN'
     Define this macro if the most significant byte in a word has the
     lowest number.

`WORDS_BIG_ENDIAN'
     Define this macro if, in a multiword object, the most significant word
     has the lowest number.

`BITS_PER_UNIT'
     Number of bits in an addressable storage unit (byte); normally 8.

`BITS_PER_WORD'
     Number of bits in a word; normally 32.

`UNITS_PER_WORD'
     Number of storage units in a word; normally 4.

`POINTER_SIZE'
     Width of a pointer, in bits.

`PARM_BOUNDARY'
     Alignment required for function parameters on the stack, in bits.

`STACK_BOUNDARY'
     Define this macro if you wish to preserve a certain alignment for the
     stack pointer at all times.  The definition is a C expression for the
     desired alignment (measured in bits).

`FUNCTION_BOUNDARY'
     Alignment required for a function entry point, in bits.

`BIGGEST_ALIGNMENT'
     Biggest alignment that any data type can require on this machine, in
     bits.

`EMPTY_FIELD_ALIGNMENT'
     Alignment in bits to be given to a structure bit field that follows an
     empty field such as `int : 0;'.

`STRUCTURE_SIZE_BOUNDARY'
     Number of bits which any structure or union's size must be a multiple
     of.  Each structure or union's size is rounded up to a multiple of this.

     If you do not define this macro, the default is the same as
     `BITS_PER_UNIT'.

`STRICT_ALIGNMENT'
     Define this if instructions will fail to work if given data not on the
     nominal alignment.  If instructions will merely go slower in that
     case, do not define this macro.


File: internals,  Node: Registers,  Next: Register Classes,  Prev: Storage Layout,  Up: Machine Macros

Register Usage
==============

`FIRST_PSEUDO_REGISTER'
     Number of hardware registers known to the compiler.  They receive
     numbers 0 through `FIRST_PSEUDO_REGISTER-1'; thus, the first pseudo
     register's number really is assigned the number `FIRST_PSEUDO_REGISTER'.

`FIXED_REGISTERS'
     An initializer that says which registers are used for fixed purposes
     all throughout the compiled code and are therefore not available for
     general allocation.  These would include the stack pointer, the frame
     pointer, the program counter on machines where that is considered one
     of the addressable registers, and any other numbered register with a
     standard use.

     This information is expressed as a sequence of numbers, separated by
     commas and surrounded by braces.  The Nth number is 1 if register N is
     fixed, 0 otherwise.

     The table initialized from this macro, and the table initialized by
     the following one, may be overridden at run time either automatically,
     by the actions of the macro `CONDITIONAL_REGISTER_USAGE', or by the
     user with the command options `-ffixed-REG', `-fcall-used-REG' and
     `-fcall-saved-REG'.

`CALL_USED_REGISTERS'
     Like `FIXED_REGISTERS' but has 1 for each register that is clobbered
     (in general) by function calls as well as for fixed registers.  This
     macro therefore identifies the registers that are not available for
     general allocation of values that must live across function calls.

     If a register has 0 in `CALL_USED_REGISTERS', the compiler
     automatically saves it on function entry and restores it on function
     exit, if the register is used within the function.

`CONDITIONAL_REGISTER_USAGE'
     Zero or more C statements that may conditionally modify two variables
     `fixed_regs' and `call_used_regs' (both of type `char []') after they
     have been initialized from the two preceding macros.

     This is necessary in case the fixed or call-clobbered registers depend
     on target flags.

     You need not define this macro if it has no work to do.

`HARD_REGNO_REGS (REGNO, MODE)'
     A C expression for the number of consecutive hard registers, starting
     at register number REGNO, required to hold a value of mode MODE.

     On a machine where all registers are exactly one word, a suitable
     definition of this macro is

          #define HARD_REGNO_NREGS(REGNO, MODE)            \
             ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1)  \
              / UNITS_PER_WORD))


`HARD_REGNO_MODE_OK (REGNO, MODE)'
     A C expression that is nonzero if it is permissible to store a value
     of mode MODE in hard register number REGNO (or in several registers
     starting with that one).  For a machine where all registers are
     equivalent, a suitable definition is

          #define HARD_REGNO_MODE_OK(REGNO, MODE) 1


     It is not necessary for this macro to check for fixed register numbers
     because the allocation mechanism considers them to be always occupied.

     Many machines have special registers for floating point arithmetic. 
     Often people assume that floating point machine modes are allowed only
     in floating point registers.  This is not true.  Any registers that
     can hold integers can safely *hold* a floating point machine mode,
     whether or not floating arithmetic can be done on it in those registers.

     The true significance of special floating registers is rather than
     non-floating-point machine modes *may not* go in those registers. 
     This is true if the floating registers normalize any value stored in
     them, because storing a non-floating value there would garble it.  If
     the floating registers do not automatically normalize, if you can
     store any bit pattern in one and retrieve it unchanged without a trap,
     then any machine mode may go in a floating register and this macro
     should say so.

     Sometimes there are floating registers that are especially slow to
     access, so that it is better to store a value in a stack frame than in
     such a register if floating point arithmetic is not being done.  As
     long as the floating registers are not in class `GENERAL_REGS', they
     will not be used unless some insn's constraint asks for one.

     It is obligatory to support floating point `move' instructions into
     and out of general registers, because unions and structures (which
     have modes `SImode' or `DImode') can be in those registers and they
     may have floating point members.

`MODES_TIEABLE_P (MODE1, MODE2)'
     A C expression that is nonzero if it is desirable to choose register
     allocation so as to avoid move instructions between a value of mode
     MODE1 and a value of mode MODE2.

     If `HARD_REGNO_MODE_OK (R, MODE1)' and `HARD_REGNO_MODE_OK (R, MODE2)'
     are ever different for any R, then `MODES_TIEABLE_P (MODE1, MODE2)'
     must be zero.

`PC_REGNUM'
     If the program counter has a register number, define this as that
     register number.  Otherwise, do not define it.

`STACK_POINTER_REGNUM'
     The register number of the stack pointer register, which must also be
     a fixed register according to `FIXED_REGISTERS'.  On many machines,
     the hardware determines which register this is.

`FRAME_POINTER_REGNUM'
     The register number of the frame pointer register, which is used to
     access automatic variables in the stack frame.  On some machines, the
     hardware determines which register this is.  On other machines, you
     can choose any register you wish for this purpose.

`FRAME_POINTER_REQUIRED'
     A C expression which is nonzero if a function must have and use a
     frame pointer.  This expression is evaluated in the reload pass, in
     the function `reload', and it can in principle examine the current
     function and decide according to the facts, but on most machines the
     constant 0 or the constant 1 suffices.  Use 0 when the machine allows
     code to be generated with no frame pointer, and doing so saves some
     time or space.  Use 1 when there is no possible advantage to avoiding
     a frame pointer.

     In certain cases, the compiler does not know how to do without a frame
     pointer.  The compiler recognizes those cases and automatically gives
     the function a frame pointer regardless of what
     `FRAME_POINTER_REQUIRED' says.  You don't need to worry about them.

     In a function that does not require a frame pointer, the frame pointer
     register can be allocated for ordinary usage, provided it is not
     marked as a fixed register.  See `FIXED_REGISTERS' for more information.

`ARG_POINTER_REGNUM'
     The register number of the arg pointer register, which is used to
     access the function's argument list.  On some machines, this is the
     same as the frame pointer register.  On some machines, the hardware
     determines which register this is.  On other machines, you can choose
     any register you wish for this purpose.  It must in any case be a
     fixed register according to `FIXED_REGISTERS'.

`STATIC_CHAIN_REGNUM'
     The register number used for passing a function's static chain
     pointer.  This is needed for languages such as Pascal and Algol where
     functions defined within other functions can access the local
     variables of the outer functions; it is not currently used because C
     does not provide this feature.

     The static chain register need not be a fixed register.

`STRUCT_VALUE_REGNUM'
     When a function's value's mode is `BLKmode', the value is not returned
     according to `FUNCTION_VALUE'.  Instead, the caller passes the address
     of a block of memory in which the value should be stored. 
     `STRUCT_VALUE_REGNUM' is the register in which this address is passed.


File: internals,  Node: Register Classes,  Next: Stack Layout,  Prev: Registers,  Up: Machine Macros

Register Classes
================

On many machines, the numbered registers are not all equivalent.  For
example, certain registers may not be allowed for indexed addressing;
certain registers may not be allowed in some instructions.  These machine
restrictions are described to the compiler using "register classes".

You define a number of register classes, giving each one a name and saying
which of the registers belong to it.  Then you can specify register classes
that are allowed as operands to particular instruction patterns.

In general, each register will belong to several classes.  In fact, one
class must be named `ALL_REGS' and contain all the registers.  Another
class must be named `NO_REGS' and contain no registers.  Often the union of
two classes will be another class; however, this is not required.

One of the classes must be named `GENERAL_REGS'.  There is nothing terribly
special about the name, but the operand constraint letters `r' and `g'
specify this class.  If `GENERAL_REGS' is the same as `ALL_REGS', just
define it as a macro which expands to `ALL_REGS'.

The way classes other than `GENERAL_REGS' are specified in operand
constraints is through machine-dependent operand constraint letters.  You
can define such letters to correspond to various classes, then use them in
operand constraints.

You should define a class for the union of two classes whenever some
instruction allows both classes.  For example, if an instruction allows
either a floating-point (coprocessor) register or a general register for a
certain operand, you should define a class `FLOAT_OR_GENERAL_REGS' which
includes both of them.  Otherwise you will get suboptimal code.

You must also specify certain redundant information about the register
classes: for each class, which classes contain it and which ones are
contained in it; for each pair of classes, the largest class contained in
their union.

`enum reg_class'
     An enumeral type that must be defined with all the register class
     names as enumeral values.  `NO_REGS' must be first.  `ALL_REGS' must
     be the last register class, followed by one more enumeral value,
     `LIM_REG_CLASSES', which is not a register class but rather tells how
     many classes there are.

     Each register class has a number, which is the value of casting the
     class name to type `int'.  The number serves as an index in many of
     the tables described below.

`REG_CLASS_NAMES'
     An initializer containing the names of the register classes as C
     string constants.  These names are used in writing some of the
     debugging dumps.

`REG_CLASS_CONTENTS'
     An initializer containing the contents of the register classes, as
     integers which are bit masks.  The Nth integer specifies the contents
     of class N.  The way the integer MASK is interpreted is that register
     R is in the class if `MASK & (1 << R)' is 1.

     When the machine has more than 32 registers, an integer does not
     suffice.  Then the integers are replaced by sub-initializers, braced
     groupings containing several integers.  Each sub-initializer must be
     suitable as an initializer for the type `HARD_REG_SET' which is
     defined in `hard-reg-set.h'.

`REGNO_REG_CLASS (REGNO)'
     A C expression whose value is a register class containing hard
     regiSTER REGNO.  In general there is more that one such class; choose
     a class which is "minimal", meaning that no smaller class also
     contains the register.

`INDEX_REG_CLASS'
     A macro whose definition is the name of the class to which a valid
     index register must belong.

`REG_CLASS_FROM_LETTER (CHAR)'
     A C expression which defines the machine-dependent operand constraint
     letters for register classes.  If CHAR is such a letter, the value
     should be the register class corresponding to it.  Otherwise, the
     value should be `NO_REGS'.

`REGNO_OK_FOR_BASE_P (NUM)'
     A C expression which is nonzero if register number NUM is suitable for
     use as a base register in operand addresses.  It may be either a
     suitable hard register or a pseudo register that has been allocated
     such a hard register.

`REGNO_OK_FOR_INDEX_P (NUM)'
     A C expression which is nonzero if register number NUM is suitable for
     use as an index register in operand addresses.  It may be either a
     suitable hard register or a pseudo register that has been allocated
     such a hard register.

     The difference between an index register and a base register is that
     the index register may be scaled.  If an address involves the sum of
     two registers, neither one of them scaled, then either one may be
     labeled the ``base'' and the other the ``index''; but whichever
     labeling is used must fit the machine's constraints of which registers
     may serve in each capacity.  The compiler will try both labelings,
     looking for one that is valid, and reload one or both registers only
     if neither labeling works.

`PREFERRED_RELOAD_CLASS (X, CLASS)'
     A C expression that places additional restrictions on the register
     class to use when it is necessary to copy value X into a register in
     class CLASS.  The value is a register class; perhaps CLASS, or perhaps
     another, smaller class.  CLASS is always safe as a value.  In fact,
     the definition

          #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS


     is always safe.  However, sometimes returning a more restrictive class
     makes better code.  For example, on the 68000, when X is an integer
     constant that is in range for a `moveq' instruction, the value of this
     macro is always `DATA_REGS' as long as CLASS includes the data
     registers.  Requiring a data register guarantees that a `moveq' will
     be used.

`CLASS_MAX_NREGS (CLASS, MODE)'
     A C expression for the maximum number of consecutive registers of
     cLASS CLASS needed to hold a value of mode MODE.

     This is closely related to the macro `HARD_REGNO_NREGS'.  In fact, the
     value of the macro `CLASS_MAX_NREGS (CLASS, MODE)' should be the
     maximum value of `HARD_REGNO_NREGS (REGNO, MODE)' for all REGNO values
     in the class CLASS.

     This macro helps control the handling of multiple-word values in the
     reload pass.

Two other special macros describe which constants fit which constraint
letters.

`CONST_OK_FOR_LETTER_P (VALUE, C)'
     A C expression that defines the machine-dependent operand constraint
     letters that specify particular ranges of integer values.  If C is one
     of those letters, the expression should check that VALUE, an integer,
     is in the appropriate range and return 1 if so, 0 otherwise.  If C is
     not one of those letters, the value should be 0 regardless of VALUE.

`CONST_DOUBLE_OK_FOR_LETTER_P (VALUE, C)'
     A C expression that defines the machine-dependent operand constraint
     letters that specify particular ranges of floating values.  If C is
     one of those letters, the expression should check that VALUE, an RTX
     of code `const_double', is in the appropriate range and return 1 if
     so, 0 otherwise.  If C is not one of those letters, the value should
     be 0 regardless of VALUE.


File: internals,  Node: Stack Layout,  Next: Library Names,  Prev: Register Classes,  Up: Machine Macros

Describing Stack Layout
=======================

`STACK_GROWS_DOWNWARD'
     Define this macro if pushing a word onto the stack moves the stack
     pointer to a smaller address.

     When we say, ``define this macro if ...,'' it means that the compiler
     checks this macro only with `#ifdef' so the precise definition used
     does not matter.

`FRAME_GROWS_DOWNWARD'
     Define this macro if the addresses of local variable slots are at
     negative offsets from the frame pointer.

`STARTING_FRAME_OFFSET'
     Offset from the frame pointer to the first local variable slot to be
     allocated.

     If `FRAME_GROWS_DOWNWARD', the next slot's offset is found by
     subtracting the length of the first slot from `STARTING_FRAME_OFFSET'.
      Otherwise, it is found by adding the length of the first slot to the
     value `STARTING_FRAME_OFFSET'.

`PUSH_ROUNDING (NPUSHED)'
     A C expression that is the number of bytes actually pushed onto the
     stack when an instruction attempts to push NPUSHED bytes.

     If the target machine does not have a push instruction, do not define
     this macro.  That directs GNU CC to use an alternate strategy: to
     allocate the entire argument block and then store the arguments into it.

     On some machines, the definition

          #define PUSH_ROUNDING(BYTES) (BYTES)


     will suffice.  But on other machines, instructions that appear to push
     one byte actually push two bytes in an attempt to maintain alignment. 
     Then the definition should be

          #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)


`FIRST_PARM_OFFSET'
     Offset from the argument pointer register to the first argument's
     address.

`RETURN_POPS_ARGS (FUNTYPE)'
     A C expression that should be 1 if a function pops its own arguments
     on returning, or 0 if the function pops no arguments and the caller
     must therefore pop them all after the function returns.

     FUNTYPE is a C variable whose value is a tree node that describes the
     function in question.  Normally it is a node of type `FUNCTION_TYPE'
     that describes the data type of the function.  From this it is
     possible to obtain the data types of the value and arguments (if known).

     When a call to a library function is being considered, FUNTYPE will
     contain an identifier node for the library function.  Thus, if you
     need to distinguish among various library functions, you can do so by
     their names.  Note that ``library function'' in this context means a
     function used to perform arithmetic, whose name is known specially in
     the compiler and was not mentioned in the C code being compiled.

     On the Vax, all functions always pop their arguments, so the
     definition of this macro is 1.  On the 68000, using the standard
     calling convention, no functions pop their arguments, so the value of
     the macro is always 0 in this case.  But an alternative calling
     convention is available in which functions that take a fixed number of
     arguments pop them but other functions (such as `printf') pop nothing
     (the caller pops all).  When this convention is in use, FUNTYPE is
     examined to determine whether a function takes a fixed number of
     arguments.

`FUNCTION_VALUE (VALTYPE, FUNC)'
     A C expression to create an RTX representing the place where a
     function returns a value of data type VALTYPE.  VALTYPE is a tree node
     representing a data type.  Write `TYPE_MODE (VALTYPE)' to get the
     machine mode used to represent that type.  On many machines, only the
     mode is relevant.  (Actually, on most machines, scalar values are
     returned in the same place regardless of mode).

     If the precise function being called is known, FUNC is a tree node
     (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer.  This
     makes it possible to use a different value-returning convention for
     specific functions when all their calls are known.

`FUNCTION_OUTGOING_VALUE (VALTYPE, FUNC)'
     Define this macro if the target machine has ``register windows'' so
     that the register in which a function returns its value is not the
     same as the one in which the caller sees the value.

     For such machines, `FUNCTION_VALUE' computes the register in which the
     caller will see the value, and `FUNCTION_OUTGOING_VALUE' should be
     defined in a similar fashion to tell the function where to put the
     value.

     If `FUNCTION_OUTGOING_VALUE' is not defined, `FUNCTION_VALUE' serves
     both purposes.

`LIBCALL_VALUE (MODE)'
     A C expression to create an RTX representing the place where a library
     function returns a value of mode MODE.  If the precise function being
     called is known, FUNC is a tree node (`FUNCTION_DECL') for it;
     otherwise, FUNC is a null pointer.  This makes it possible to use a
     different value-returning convention for specific functions when all
     their calls are known.

     Note that ``library function'' in this context means a compiler
     support routine, used to perform arithmetic, whose name is known
     specially by the compiler and was not mentioned in the C code being
     compiled.

`FUNCTION_VALUE_REGNO_P (REGNO)'
     A C expression that is nonzero if REGNO is the number of a hard
     register in which function values are sometimes returned.

     A register whose use for returning values is limited to serving as the
     second of a pair (for a value of type `double', say) need not be
     recognized by this macro.  So for most machines, this definition
     suffices:

          #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)


`FUNCTION_ARG (CUM, MODE, TYPE, NAMED)'
     A C expression that controls whether a function argument is passed in
     a register, and which register.

     The arguments are CUM, which summarizes all the previous arguments;
     MODE, the machine mode of the argument; TYPE, the data type of the
     argument as a tree node or 0 if that is not known (which happens for C
     support library functions); and NAMED, which is 1 for an ordinary
     argument and 0 for nameless arguments that correspond to `...' in the
     called function's prototype.

     The value of the expression should either be a `reg' RTX for the hard
     register in which to pass the argument, or zero to pass the argument
     on the stack.

     For the Vax and 68000, where normally all arguments are pushed, zero
     suffices as a definition.

`FUNCTION_INCOMING_ARG (CUM, MODE, TYPE, NAMED)'
     Define this macro if the target machine has ``register windows'', so
     that the register in which a function sees an arguments is not
     necessarily the same as the one in which the caller passed the argument.

     For such machines, `FUNCTION_ARG' computes the register in which the
     caller passes the value, and `FUNCTION_INCOMING_ARG' should be defined
     in a similar fashion to tell the function being called where the
     arguments will arrive.

     If `FUNCTION_INCOMING_ARG' is not defined, `FUNCTION_ARG' serves both
     purposes.

`FUNCTION_ARG_PARTIAL_NREGS (CUM, MODE, TYPE, NAMED)'
     A C expression for the number of words, at the beginning of an
     argument, must be put in registers.  The value must be zero for
     arguments that are passed entirely in registers or that are entirely
     pushed on the stack.

     On some machines, certain arguments must be passed partially in
     registers and partially in memory.  On these machines, typically the
     first N words of arguments are passed in registers, and the rest on
     the stack.  If a multi-word argument (a `double' or a structure)
     crosses that boundary, its first few words must be passed in registers
     and the rest must be pushed.  This macro tells the compiler when this
     occurs, and how many of the words should go in registers.

     `FUNCTION_ARG' for these arguments should return the first register to
     be used by the caller for this argument; likewise
     `FUNCTION_INCOMING_ARG', for the called function.

`CUMULATIVE_ARGS'
     A C type for declaring a variable that is used as the first argument
     of `FUNCTION_ARG' and other related values.  For some target machines,
     the type `int' suffices and can hold the number of bytes of argument
     so far.

`INIT_CUMULATIVE_ARGS (CUM)'
     A C statement (sans semicolon) for initializing the variable CUM for
     the state at the beginning of the argument list.  The variable has
     type `CUMULATIVE_ARGS'.

`FUNCTION_ARG_ADVANCE (CUM, MODE, TYPE, NAMED)'
     Update the summarizer variable CUM to advance past an argument in the
     argument list.  The values MODE, TYPE and NAMED describe that
     argument.  Once this is done, the variable CUM is suitable for
     analyzing the *following* argument with `FUNCTION_ARG', etc.

`FUNCTION_ARG_REGNO_P (REGNO)'
     A C expression that is nonzero if REGNO is the number of a hard
     register in which function arguments are sometimes passed.  This does
     *not* include implicit arguments such as the static chain and the
     structure-value address.  On many machines, no registers can be used
     for this purpose since all function arguments are pushed on the stack.

`FUNCTION_PROLOGUE (FILE, SIZE)'
     A C compound statement that outputs the assembler code for entry to a
     function.  The prologue is responsible for setting up the stack frame,
     initializing the frame pointer register, saving registers that must be
     saved, and allocating SIZE additional bytes of storage for the local
     variables.  SIZE is an integer.  FILE is a stdio stream to which the
     assembler code should be output.

     The label for the beginning of the function need not be output by this
     macro.  That has already been done when the macro is run.

     To determine which registers to save, the macro can refer to the array
     `regs_ever_live': element R is nonzero if hard register R is used
     anywhere within the function.  This implies the function prologue
     should save register R, but not if it is one of the call-used registers.

     On machines where functions may or may not have frame-pointers, the
     function entry code must vary accordingly; it must set up the frame
     pointer if one is wanted, and not otherwise.  To determine whether a
     frame pointer is in wanted, the macro can refer to the variable
     `frame_pointer_needed'.  The variable's value will be 1 at run time in
     a function that needs a frame pointer.

`FUNCTION_PROFILER (FILE, LABELNO)'
     A C statement or compound statement to output to FILE some assembler
     code to call the profiling subroutine `mcount'.  Before calling, the
     assembler code must load the address of a counter variable into a
     register where `mcount' expects to find the address.  The name of this
     variable is `LP' followed by the number LABELNO, so you would generate
     the name using `LP%d' in a `fprintf'.

     The details of how the address should be passed to `mcount' are
     determined by your operating system environment, not by GNU CC.  To
     figure them out, compile a small program for profiling using the
     system's installed C compiler and look at the assembler code that
     results.

`EXIT_IGNORES_STACK'
     Define this macro as a C expression that is nonzero if the return
     instruction or the function epilogue ignores the value of the stack
     pointer; in other words, if it is safe to delete an instruction to
     adjust the stack pointer before a return from the function.

     Note that this macro's value is relevant only for for which frame
     pointers are maintained.  It is never possible to delete a final stack
     adjustment in a function that has no frame pointer, and the compiler
     knows this regardless of `EXIT_IGNORES_STACK'.

`FUNCTION_EPILOGUE (FILE, SIZE)'
     A C compound statement that outputs the assembler code for exit from a
     function.  The epilogue is responsible for restoring the saved
     registers and stack pointer to their values when the function was
     called, and returning control to the caller.  This macro takes the
     same arguments as the macro `FUNCTION_PROLOGUE', and the registers to
     restore are determined from `regs_ever_live' and `CALL_USED_REGISTERS'
     in the same way.

     On some machines, there is a single instruction that does all the work
     of returning from the function.  On these machines, give that
     instruction the name `return' and do not define the macro
     `FUNCTION_EPILOGUE' at all.

     On machines where functions may or may not have frame-pointers, the
     function exit code must vary accordingly.  Sometimes the code for
     these two cases is completely different.  To determine whether a frame
     pointer is in wanted, the macro can refer to the variable
     `frame_pointer_needed'.  The variable's value will be 1 at run time in
     a function that needs a frame pointer.

     On some machines, some functions pop their arguments on exit while
     others leave that for the caller to do.  For example, the 68020 when
     given `-mrtd' pops arguments in functions that take a fixed number of
     arguments.

     Your definition of the macro `RETURN_POPS_ARGS' decides which
     functions pop their own arguments.  `FUNCTION_EPILOGUE' needs to know
     what was decided.  The variable `current_function_pops_args' is
     nonzero if the function should pop its own arguments.  If so, use the
     variable `current_function_args_size' as the number of bytes to pop.

`FIX_FRAME_POINTER_ADDRESS (ADDR, DEPTH)'
     A C compound statement to alter a memory address that uses the frame
     pointer register so that it uses the stack pointer register instead. 
     This must be done in the instructions that load parameter values into
     registers, when the reload pass determines that a frame pointer is not
     necessary for the function.  ADDR will be a C variable name, and the
     updated address should be stored in that variable.  DEPTH will be the
     current depth of stack temporaries (number of bytes of arguments
     currently pushed).  The change in offset between a
     frame-pointer-relative address and a stack-pointer-relative address
     must include DEPTH.

     Even if your machine description specifies there will always be a
     frame pointer in the frame pointer register, you must still define
     `FIX_FRAME_POINTER_ADDRESS', but the definition will never be executed
     at run time, so it may be empty.


File: internals,  Node: Library Names,  Next: Addressing Modes,  Prev: Stack Layout,  Up: Machine Macros

Library Subroutine Names
========================

`UDIVSI3_LIBCALL'
     A C string constant giving the name of the function to call for
     division of a full-word by a full-word.  If you do not define this
     macro, the default name is used, which is `_udivsi3', a function
     defined in `gnulib'.

`UMODSI3_LIBCALL'
     A C string constant giving the name of the function to call for the
     remainder in division of a full-word by a full-word.  If you do not
     define this macro, the default name is used, which is `_umodsi3', a
     function defined in `gnulib'.

`TARGET_MEM_FUNCTIONS'
     Define this macro if GNU CC should generate calls to the System V (and
     ANSI C) library functions `memcpy' and `memset' rather than the BSD
     functions `bcopy' and `bzero'.


File: internals,  Node: Addressing Modes,  Next: Misc,  Prev: Library Names,  Up: Machine Macros

Addressing Modes
================

`HAVE_POST_INCREMENT'
     Define this macro if the machine supports post-increment addressing.

`HAVE_PRE_INCREMENT'
`HAVE_POST_DECREMENT'
`HAVE_PRE_DECREMENT'
     Similar for other kinds of addressing.

`CONSTANT_ADDRESS_P (X)'
     A C expression that is 1 if the RTX X is a constant whose value is an
     integer.  This includes integers whose values are not explicitly
     known, such as `symbol_ref' and `label_ref' expressions and `const'
     arithmetic expressions.

     On most machines, this can be defined as `CONSTANT_P (X)', but a few
     machines are more restrictive in which constant addresses are supported.

`MAX_REGS_PER_ADDRESS'
     A number, the maximum number of registers that can appear in a valid
     memory address.

`GO_IF_LEGITIMATE_ADDRESS (MODE, X, LABEL)'
     A C compound statement with a conditional `goto LABEL;' executed if X
     (an RTX) is a legitimate memory address on the target machine for a
     memory operand of mode MODE.

     It usually pays to define several simpler macros to serve as
     subroutines for this one.  Otherwise it may be too complicated to
     understand.

     This macro must exist in two variants: a strict variant and a
     non-strict one.  The strict variant is used in the reload pass.  It
     must be defined so that any pseudo-register that has not been
     allocated a hard register is considered a memory reference.  In
     contexts where some kind of register is required, a pseudo-register
     with no hard register must be rejected.

     The non-strict variant is used in other passes.  It must be defined to
     accept all pseudo-registers in every context where some kind of
     register is required.

     Compiler source files that want to use the strict variant of this
     macro define the macro `REG_OK_STRICT'.  You should use an `#ifdef
     REG_OK_STRICT' conditional to define the strict variant in that case
     and the non-strict variant otherwise.

     Typically among the subroutines used to define
     `GO_IF_LEGITIMATE_ADDRESS' are subroutines to check for acceptable
     registers for various purposes (one for base registers, one for index
     registers, and so on).  Then only these subroutine macros need have
     two variants; the higher levels of macros may be the same whether
     strict or not.

`LEGITIMIZE_ADDRESS (X, OLDX, MODE, WIN)'
     A C compound statement that attempts to replace X with a valid memory
     address for an operand of mode MODE.  WIN will be a C statement label
     elsewhere in the code; the macro definition may use

          GO_IF_LEGITIMATE_ADDRESS (MODE, X, WIN);


     to avoid further processing if the address has become legitimate.

     X will always be the result of a call to `break_out_memory_refs', and
     OLDX will be the operand that was given to that function to produce X.

     The code generated by this macro should not alter the substructure of
     X.  If it transforms X into a more legitimate form, it should assign X
     (which will always be a C variable) a new value.

     It is not necessary for this macro to come up with a legitimate
     address.  The compiler has standard ways of doing so in all cases.  In
     fact, it is safe for this macro to do nothing.  But often a
     machine-dependent strategy can generate better code.

`GO_IF_MODE_DEPENDENT_ADDRESS (ADDR, LABEL)'
     A C statement or compound statement with a conditional `goto LABEL;'
     executed if memory address X (an RTX) can have different meanings
     depending on the machine mode of the memory reference it is used for.

     Autoincrement and autodecrement addresses typically have
     mode-dependent effects because the amount of the increment or
     decrement is the size of the operand being addressed.  Some machines
     have other mode-dependent addresses.  Many RISC machines have no
     mode-dependent addresses.

     You may assume that ADDR is a valid address for the machine.

`LEGITIMATE_CONSTANT_P (X)'
     A C expression that is nonzero if X is a legitimate constant for an
     immediate operand on the target machine.  You can assume that either X
     is a `const_double' or it satisfies `CONSTANT_P', so you need not
     check these things.  In fact, `1' is a suitable definition for this
     macro on machines where any `const_double' is valid and anything
     `CONSTANT_P' is valid.