Return to gcc.info-11 CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/gcc.info-11, revision 1.1.1.2

1.1.1.2 ! root        1: This is Info file gcc.info, produced by Makeinfo-1.44 from the input
1.1       root        2: file gcc.texi.
                      3: 
                      4:    This file documents the use and the internals of the GNU compiler.
                      5: 
                      6:    Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
                      7: 
                      8:    Permission is granted to make and distribute verbatim copies of
                      9: this manual provided the copyright notice and this permission notice
                     10: are preserved on all copies.
                     11: 
                     12:    Permission is granted to copy and distribute modified versions of
                     13: this manual under the conditions for verbatim copying, provided also
                     14: that the section entitled "GNU General Public License" is included
                     15: exactly as in the original, and provided that the entire resulting
                     16: derived work is distributed under the terms of a permission notice
                     17: identical to this one.
                     18: 
                     19:    Permission is granted to copy and distribute translations of this
                     20: manual into another language, under the above conditions for modified
                     21: versions, except that the section entitled "GNU General Public
                     22: License" and this permission notice may be included in translations
                     23: approved by the Free Software Foundation instead of in the original
                     24: English.
                     25: 
                     26: 
1.1.1.2 ! root       27: File: gcc.info,  Node: Insn Canonicalizations,  Next: Peephole Definitions,  Prev: Jump Patterns,  Up: Machine Desc
        !            28: 
        !            29: Canonicalization of Instructions
        !            30: ================================
        !            31: 
        !            32:    There are often cases where multiple RTL expressions could
        !            33: represent an operation performed by a single machine instruction. 
        !            34: This situation is most commonly encountered with logical, branch, and
        !            35: multiply-accumulate instructions.  In such cases, the compiler
        !            36: attempts to convert these multiple RTL expressions into a single
        !            37: canonical form to reduce the number of insn patterns required.
        !            38: 
        !            39:    In addition to algebraic simplifications, following
        !            40: canonicalizations are performed:
        !            41: 
        !            42:    * For commutative and comparison operators, a constant is always
        !            43:      made the second operand.  If a machine only supports a constant
        !            44:      as the second operand, only patterns that match a constant in the
        !            45:      second operand need be supplied.
        !            46: 
        !            47:      For these operators, if only one operand is a `neg', `not',
        !            48:      `mult', `plus', or `minus' expression, it will be the first
        !            49:      operand.
        !            50: 
        !            51:    * For the `compare' operator, a constant is always the second
        !            52:      operand on machines where `cc0' is used (*note Jump Patterns::.).
        !            53:       On other machines, there are rare cases where the compiler might
        !            54:      want to construct a `compare' with a constant as the first
        !            55:      operand.  However, these cases are not common enough for it to be
        !            56:      worthwhile to provide a pattern matching a constant as the first
        !            57:      operand unless the machine actually has such an instruction.
        !            58: 
        !            59:      An operand of `neg', `not', `mult', `plus', or `minus' is made
        !            60:      the first operand under the same conditions as above.
        !            61: 
        !            62:    * `(minus X (const_int N))' is converted to `(plus X (const_int
        !            63:      -N))'.
        !            64: 
        !            65:    * Within address computations (i.e., inside `mem'), a left shift is
        !            66:      converted into the appropriate multiplication by a power of two.
        !            67: 
        !            68:      De`Morgan's Law is used to move bitwise negation inside a bitwise
        !            69:      logical-and or logical-or operation.  If this results in only one
        !            70:      operand being a `not' expression, it will be the first one.
        !            71: 
        !            72:      A machine that has an instruction that performs a bitwise
        !            73:      logical-and of one operand with the bitwise negation of the other
        !            74:      should specify the pattern for that instruction as
        !            75: 
        !            76:           (define_insn ""
        !            77:             [(set (match_operand:M 0 ...)
        !            78:                (and:M (not:M (match_operand:M 1 ...))
        !            79:                             (match_operand:M 2 ...)))]
        !            80:             "..."
        !            81:             "...")
        !            82: 
        !            83:      Similarly, a pattern for a "NAND" instruction should be written
        !            84: 
        !            85:           (define_insn ""
        !            86:             [(set (match_operand:M 0 ...)
        !            87:                (ior:M (not:M (match_operand:M 1 ...))
        !            88:                             (not:M (match_operand:M 2 ...))))]
        !            89:             "..."
        !            90:             "...")
        !            91: 
        !            92:      In both cases, it is not necessary to include patterns for the
        !            93:      many logically equivalent RTL expressions.
        !            94: 
        !            95:    * The only possible RTL expressions involving both bitwise
        !            96:      exclusive-or and bitwise negation are `(xor:M X) Y)' and `(not:M
        !            97:      (xor:M X Y))'.
        !            98: 
        !            99:    * The sum of three items, one of which is a constant, will only
        !           100:      appear in the form
        !           101: 
        !           102:           (plus:M (plus:M X Y) CONSTANT)
        !           103: 
        !           104:    * On machines that do not use `cc0', `(compare X (const_int 0))'
        !           105:      will be converted to X.
        !           106: 
        !           107:    * Equality comparisons of a group of bits (usually a single bit)
        !           108:      with zero will be written using `zero_extract' rather than the
        !           109:      equivalent `and' or `sign_extract' operations.
        !           110: 
        !           111: 
        !           112: File: gcc.info,  Node: Peephole Definitions,  Next: Expander Definitions,  Prev: Insn Canonicalizations,  Up: Machine Desc
        !           113: 
        !           114: Defining Machine-Specific Peephole Optimizers
        !           115: =============================================
        !           116: 
        !           117:    In addition to instruction patterns the `md' file may contain
        !           118: definitions of machine-specific peephole optimizations.
        !           119: 
        !           120:    The combiner does not notice certain peephole optimizations when
        !           121: the data flow in the program does not suggest that it should try them.
        !           122:  For example, sometimes two consecutive insns related in purpose can
        !           123: be combined even though the second one does not appear to use a
        !           124: register computed in the first one.  A machine-specific peephole
        !           125: optimizer can detect such opportunities.
        !           126: 
        !           127:    A definition looks like this:
        !           128: 
        !           129:      (define_peephole
        !           130:        [INSN-PATTERN-1
        !           131:         INSN-PATTERN-2
        !           132:         ...]
        !           133:        "CONDITION"
        !           134:        "TEMPLATE"
        !           135:        "OPTIONAL INSN-ATTRIBUTES")
        !           136: 
        !           137: The last string operand may be omitted if you are not using any
        !           138: machine-specific information in this machine description.  If present,
        !           139: it must obey the same rules as in a `define_insn'.
        !           140: 
        !           141:    In this skeleton, INSN-PATTERN-1 and so on are patterns to match
        !           142: consecutive insns.  The optimization applies to a sequence of insns
        !           143: when INSN-PATTERN-1 matches the first one, INSN-PATTERN-2 matches the
        !           144: next, and so on.
        !           145: 
        !           146:    Each of the insns matched by a peephole must also match a
        !           147: `define_insn'.  Peepholes are checked only at the last stage just
        !           148: before code generation, and only optionally.  Therefore, any insn which
        !           149: would match a peephole but no `define_insn' will cause a crash in code
        !           150: generation in an unoptimized compilation, or at various optimization
        !           151: stages.
        !           152: 
        !           153:    The operands of the insns are matched with `match_operands',
        !           154: `match_operator', and `match_dup', as usual.  What is not usual is
        !           155: that the operand numbers apply to all the insn patterns in the
        !           156: definition.  So, you can check for identical operands in two insns by
        !           157: using `match_operand' in one insn and `match_dup' in the other.
        !           158: 
        !           159:    The operand constraints used in `match_operand' patterns do not have
        !           160: any direct effect on the applicability of the peephole, but they will
        !           161: be validated afterward, so make sure your constraints are general
        !           162: enough to apply whenever the peephole matches.  If the peephole matches
        !           163: but the constraints are not satisfied, the compiler will crash.
        !           164: 
        !           165:    It is safe to omit constraints in all the operands of the peephole;
        !           166: or you can write constraints which serve as a double-check on the
        !           167: criteria previously tested.
        !           168: 
        !           169:    Once a sequence of insns matches the patterns, the CONDITION is
        !           170: checked.  This is a C expression which makes the final decision
        !           171: whether to perform the optimization (we do so if the expression is
        !           172: nonzero).  If CONDITION is omitted (in other words, the string is
        !           173: empty) then the optimization is applied to every sequence of insns
        !           174: that matches the patterns.
        !           175: 
        !           176:    The defined peephole optimizations are applied after register
        !           177: allocation is complete.  Therefore, the peephole definition can check
        !           178: which operands have ended up in which kinds of registers, just by
        !           179: looking at the operands.
        !           180: 
        !           181:    The way to refer to the operands in CONDITION is to write
        !           182: `operands[I]' for operand number I (as matched by `(match_operand I
        !           183: ...)').  Use the variable `insn' to refer to the last of the insns
        !           184: being matched; use `prev_nonnote_insn' to find the preceding insns.
        !           185: 
        !           186:    When optimizing computations with intermediate results, you can use
        !           187: CONDITION to match only when the intermediate results are not used
        !           188: elsewhere.  Use the C expression `dead_or_set_p (INSN, OP)', where
        !           189: INSN is the insn in which you expect the value to be used for the last
        !           190: time (from the value of `insn', together with use of
        !           191: `prev_nonnote_insn'), and OP is the intermediate value (from
        !           192: `operands[I]').
        !           193: 
        !           194:    Applying the optimization means replacing the sequence of insns
        !           195: with one new insn.  The TEMPLATE controls ultimate output of assembler
        !           196: code for this combined insn.  It works exactly like the template of a
        !           197: `define_insn'.  Operand numbers in this template are the same ones
        !           198: used in matching the original sequence of insns.
        !           199: 
        !           200:    The result of a defined peephole optimizer does not need to match
        !           201: any of the insn patterns in the machine description; it does not even
        !           202: have an opportunity to match them.  The peephole optimizer definition
        !           203: itself serves as the insn pattern to control how the insn is output.
        !           204: 
        !           205:    Defined peephole optimizers are run as assembler code is being
        !           206: output, so the insns they produce are never combined or rearranged in
        !           207: any way.
        !           208: 
        !           209:    Here is an example, taken from the 68000 machine description:
        !           210: 
        !           211:      (define_peephole
        !           212:        [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
        !           213:         (set (match_operand:DF 0 "register_operand" "f")
        !           214:              (match_operand:DF 1 "register_operand" "ad"))]
        !           215:        "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
        !           216:        "*
        !           217:      {
        !           218:        rtx xoperands[2];
        !           219:        xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
        !           220:      #ifdef MOTOROLA
        !           221:        output_asm_insn (\"move.l %1,(sp)\", xoperands);
        !           222:        output_asm_insn (\"move.l %1,-(sp)\", operands);
        !           223:        return \"fmove.d (sp)+,%0\";
        !           224:      #else
        !           225:        output_asm_insn (\"movel %1,sp@\", xoperands);
        !           226:        output_asm_insn (\"movel %1,sp@-\", operands);
        !           227:        return \"fmoved sp@+,%0\";
        !           228:      #endif
        !           229:      }
        !           230:      ")
        !           231: 
        !           232:    The effect of this optimization is to change
        !           233: 
        !           234:      jbsr _foobar
        !           235:      addql #4,sp
        !           236:      movel d1,sp@-
        !           237:      movel d0,sp@-
        !           238:      fmoved sp@+,fp0
        !           239: 
        !           240: into
        !           241: 
        !           242:      jbsr _foobar
        !           243:      movel d1,sp@
        !           244:      movel d0,sp@-
        !           245:      fmoved sp@+,fp0
        !           246: 
        !           247:    INSN-PATTERN-1 and so on look *almost* like the second operand of
        !           248: `define_insn'.  There is one important difference: the second operand
        !           249: of `define_insn' consists of one or more RTX's enclosed in square
        !           250: brackets.  Usually, there is only one: then the same action can be
        !           251: written as an element of a `define_peephole'.  But when there are
        !           252: multiple actions in a `define_insn', they are implicitly enclosed in a
        !           253: `parallel'.  Then you must explicitly write the `parallel', and the
        !           254: square brackets within it, in the `define_peephole'.  Thus, if an insn
        !           255: pattern looks like this,
        !           256: 
        !           257:      (define_insn "divmodsi4"
        !           258:        [(set (match_operand:SI 0 "general_operand" "=d")
        !           259:              (div:SI (match_operand:SI 1 "general_operand" "0")
        !           260:                      (match_operand:SI 2 "general_operand" "dmsK")))
        !           261:         (set (match_operand:SI 3 "general_operand" "=d")
        !           262:              (mod:SI (match_dup 1) (match_dup 2)))]
        !           263:        "TARGET_68020"
        !           264:        "divsl%.l %2,%3:%0")
        !           265: 
        !           266: then the way to mention this insn in a peephole is as follows:
        !           267: 
        !           268:      (define_peephole
        !           269:        [...
        !           270:         (parallel
        !           271:          [(set (match_operand:SI 0 "general_operand" "=d")
        !           272:                (div:SI (match_operand:SI 1 "general_operand" "0")
        !           273:                        (match_operand:SI 2 "general_operand" "dmsK")))
        !           274:           (set (match_operand:SI 3 "general_operand" "=d")
        !           275:                (mod:SI (match_dup 1) (match_dup 2)))])
        !           276:         ...]
        !           277:        ...)
        !           278: 
        !           279: 
        !           280: File: gcc.info,  Node: Expander Definitions,  Next: Insn Splitting,  Prev: Peephole Definitions,  Up: Machine Desc
        !           281: 
        !           282: Defining RTL Sequences for Code Generation
        !           283: ==========================================
        !           284: 
        !           285:    On some target machines, some standard pattern names for RTL
        !           286: generation cannot be handled with single insn, but a sequence of RTL
        !           287: insns can represent them.  For these target machines, you can write a
        !           288: `define_expand' to specify how to generate the sequence of RTL.
        !           289: 
        !           290:    A `define_expand' is an RTL expression that looks almost like a
        !           291: `define_insn'; but, unlike the latter, a `define_expand' is used only
        !           292: for RTL generation and it can produce more than one RTL insn.
        !           293: 
        !           294:    A `define_expand' RTX has four operands:
        !           295: 
        !           296:    * The name.  Each `define_expand' must have a name, since the only
        !           297:      use for it is to refer to it by name.
        !           298: 
        !           299:    * The RTL template.  This is just like the RTL template for a
        !           300:      `define_peephole' in that it is a vector of RTL expressions each
        !           301:      being one insn.
        !           302: 
        !           303:    * The condition, a string containing a C expression.  This
        !           304:      expression is used to express how the availability of this
        !           305:      pattern depends on subclasses of target machine, selected by
        !           306:      command-line options when GNU CC is run.  This is just like the
        !           307:      condition of a `define_insn' that has a standard name.
        !           308: 
        !           309:    * The preparation statements, a string containing zero or more C
        !           310:      statements which are to be executed before RTL code is generated
        !           311:      from the RTL template.
        !           312: 
        !           313:      Usually these statements prepare temporary registers for use as
        !           314:      internal operands in the RTL template, but they can also generate
        !           315:      RTL insns directly by calling routines such as `emit_insn', etc. 
        !           316:      Any such insns precede the ones that come from the RTL template.
        !           317: 
        !           318:    Every RTL insn emitted by a `define_expand' must match some
        !           319: `define_insn' in the machine description.  Otherwise, the compiler
        !           320: will crash when trying to generate code for the insn or trying to
        !           321: optimize it.
        !           322: 
        !           323:    The RTL template, in addition to controlling generation of RTL
        !           324: insns, also describes the operands that need to be specified when this
        !           325: pattern is used.  In particular, it gives a predicate for each operand.
        !           326: 
        !           327:    A true operand, which needs to be specified in order to generate
        !           328: RTL from the pattern, should be described with a `match_operand' in
        !           329: its first occurrence in the RTL template.  This enters information on
        !           330: the operand's predicate into the tables that record such things.  GNU
        !           331: CC uses the information to preload the operand into a register if that
        !           332: is required for valid RTL code.  If the operand is referred to more
        !           333: than once, subsequent references should use `match_dup'.
        !           334: 
        !           335:    The RTL template may also refer to internal "operands" which are
        !           336: temporary registers or labels used only within the sequence made by the
        !           337: `define_expand'.  Internal operands are substituted into the RTL
        !           338: template with `match_dup', never with `match_operand'.  The values of
        !           339: the internal operands are not passed in as arguments by the compiler
        !           340: when it requests use of this pattern.  Instead, they are computed
        !           341: within the pattern, in the preparation statements.  These statements
        !           342: compute the values and store them into the appropriate elements of
        !           343: `operands' so that `match_dup' can find them.
        !           344: 
        !           345:    There are two special macros defined for use in the preparation
        !           346: statements: `DONE' and `FAIL'.  Use them with a following semicolon,
        !           347: as a statement.
        !           348: 
        !           349: `DONE'
        !           350:      Use the `DONE' macro to end RTL generation for the pattern.  The
        !           351:      only RTL insns resulting from the pattern on this occasion will be
        !           352:      those already emitted by explicit calls to `emit_insn' within the
        !           353:      preparation statements; the RTL template will not be generated.
        !           354: 
        !           355: `FAIL'
        !           356:      Make the pattern fail on this occasion.  When a pattern fails, it
        !           357:      means that the pattern was not truly available.  The calling
        !           358:      routines in the compiler will try other strategies for code
        !           359:      generation using other patterns.
        !           360: 
        !           361:      Failure is currently supported only for binary (addition,
        !           362:      multiplication, shifting, etc.) and bitfield (`extv', `extzv',
        !           363:      and `insv') operations.
        !           364: 
        !           365:    Here is an example, the definition of left-shift for the SPUR chip:
        !           366: 
        !           367:      (define_expand "ashlsi3"
        !           368:        [(set (match_operand:SI 0 "register_operand" "")
        !           369:              (ashift:SI
        !           370:                (match_operand:SI 1 "register_operand" "")
        !           371:                (match_operand:SI 2 "nonmemory_operand" "")))]
        !           372:        ""
        !           373:        "
        !           374:      {
        !           375:        if (GET_CODE (operands[2]) != CONST_INT
        !           376:            || (unsigned) INTVAL (operands[2]) > 3)
        !           377:          FAIL;
        !           378:      }")
        !           379: 
        !           380: This example uses `define_expand' so that it can generate an RTL insn
        !           381: for shifting when the shift-count is in the supported range of 0 to 3
        !           382: but fail in other cases where machine insns aren't available.  When it
        !           383: fails, the compiler tries another strategy using different patterns
        !           384: (such as, a library call).
        !           385: 
        !           386:    If the compiler were able to handle nontrivial condition-strings in
        !           387: patterns with names, then it would be possible to use a `define_insn'
        !           388: in that case.  Here is another case (zero-extension on the 68000)
        !           389: which makes more use of the power of `define_expand':
        !           390: 
        !           391:      (define_expand "zero_extendhisi2"
        !           392:        [(set (match_operand:SI 0 "general_operand" "")
        !           393:              (const_int 0))
        !           394:         (set (strict_low_part
        !           395:                (subreg:HI
        !           396:                  (match_dup 0)
        !           397:                  0))
        !           398:              (match_operand:HI 1 "general_operand" ""))]
        !           399:        ""
        !           400:        "operands[1] = make_safe_from (operands[1], operands[0]);")
        !           401: 
        !           402: Here two RTL insns are generated, one to clear the entire output
        !           403: operand and the other to copy the input operand into its low half. 
        !           404: This sequence is incorrect if the input operand refers to [the old
        !           405: value of] the output operand, so the preparation statement makes sure
        !           406: this isn't so.  The function `make_safe_from' copies the `operands[1]'
        !           407: into a temporary register if it refers to `operands[0]'.  It does this
        !           408: by emitting another RTL insn.
        !           409: 
        !           410:    Finally, a third example shows the use of an internal operand. 
        !           411: Zero-extension on the SPUR chip is done by `and'-ing the result
        !           412: against a halfword mask.  But this mask cannot be represented by a
        !           413: `const_int' because the constant value is too large to be legitimate
        !           414: on this machine.  So it must be copied into a register with
        !           415: `force_reg' and then the register used in the `and'.
        !           416: 
        !           417:      (define_expand "zero_extendhisi2"
        !           418:        [(set (match_operand:SI 0 "register_operand" "")
        !           419:              (and:SI (subreg:SI
        !           420:                        (match_operand:HI 1 "register_operand" "")
        !           421:                        0)
        !           422:                      (match_dup 2)))]
        !           423:        ""
        !           424:        "operands[2]
        !           425:           = force_reg (SImode, gen_rtx (CONST_INT,
        !           426:                                         VOIDmode, 65535)); ")
        !           427: 
        !           428:    *Note:* If the `define_expand' is used to serve a standard binary
        !           429: or unary arithmetic operation or a bitfield operation, then the last
        !           430: insn it generates must not be a `code_label', `barrier' or `note'.  It
        !           431: must be an `insn', `jump_insn' or `call_insn'.  If you don't need a
        !           432: real insn at the end, emit an insn to copy the result of the operation
        !           433: into itself.  Such an insn will generate no code, but it can avoid
        !           434: problems in the compiler.
        !           435: 
        !           436: 
1.1       root      437: File: gcc.info,  Node: Insn Splitting,  Next: Insn Attributes,  Prev: Expander Definitions,  Up: Machine Desc
                    438: 
                    439: Splitting Instructions into Multiple Instructions
                    440: =================================================
                    441: 
                    442:    On machines that have instructions requiring delay slots (*note
                    443: Delay Slots::.) or that have instructions whose output is not
                    444: available for multiple cycles (*note Function Units::.), the compiler
                    445: phases that optimize these cases need to be able to move insns into
                    446: one-cycle delay slots.  However, some insns may generate more than one
                    447: machine instruction.  These insns would be unable to be placed into a
                    448: delay slot.
                    449: 
                    450:    It is often possible to write the single insn as a list of
                    451: individual insns, each corresponding to one machine instruction.  The
                    452: disadvantage of doing so is that it will cause the compilation to be
                    453: slower and require more space.  If the resulting insns are too
                    454: complex, it may also suppress some optimizations.
                    455: 
                    456:    The `define_split' definition tells the compiler how to split a
                    457: complex insn into several simpler insns.  This spilling will be
                    458: performed if there is a reason to believe that it might improve
                    459: instruction or delay slot scheduling.  The definition looks like this:
                    460: 
                    461:      (define_split
                    462:        [INSN-PATTERN]
                    463:        "CONDITION"
                    464:        [NEW-INSN-PATTERN-1
                    465:         NEW-INSN-PATTERN-2
                    466:         ...]
                    467:        "PREPARATION STATEMENTS")
                    468: 
                    469:    INSN-PATTERN is a pattern that needs to be split and CONDITION is
                    470: the final condition to be tested, as in a `define_insn'.  Any insn
                    471: matched by a `define_split' must also be matched by a `define_insn' in
                    472: case it does not need to be split.
                    473: 
                    474:    When an insn matching INSN-PATTERN and satisfying CONDITION is
                    475: found, it is replaced in the insn list with the insns given by
                    476: NEW-INSN-PATTERN-1, NEW-INSN-PATTERN-2, etc.
                    477: 
                    478:    The PREPARATION STATEMENTS are similar to those specified for
                    479: `define_expand' (*note Expander Definitions::.) and are executed
                    480: before the new RTL is generated to prepare for the generated code or
                    481: emit some insns whose pattern is not fixed.
                    482: 
                    483:    As a simple case, consider the following example from the AMD 29000
                    484: machine description, which splits a `sign_extend' from `HImode' to
                    485: `SImode' into a pair of shift insns:
                    486: 
                    487:      (define_split
                    488:        [(set (match_operand:SI 0 "gen_reg_operand" "")
                    489:        (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
                    490:        ""
                    491:        [(set (match_dup 0)
                    492:        (ashift:SI (match_dup 1)
                    493:                   (const_int 16)))
                    494:         (set (match_dup 0)
                    495:        (ashiftrt:SI (match_dup 0)
                    496:                     (const_int 16)))]
                    497:        "
                    498:      { operands[1] = gen_lowpart (SImode, operands[1]); }")
                    499: 
                    500: 
                    501: File: gcc.info,  Node: Insn Attributes,  Prev: Insn Splitting,  Up: Machine Desc
                    502: 
                    503: Instruction Attributes
                    504: ======================
                    505: 
                    506:    In addition to describing the instruction supported by the target
                    507: machine, the `md' file also defines a group of "attributes" and a set
                    508: of values for each.  Every generated insn is assigned a value for each
                    509: attribute.  One possible attribute would be the effect that the insn
                    510: has on the machine's condition code.  This attribute can then be used
                    511: by `NOTICE_UPDATE_CC' to track the condition codes.
                    512: 
                    513: * Menu:
                    514: 
                    515: * Defining Attributes:: Specifying attributes and their values.
                    516: * Expressions::         Valid expressions for attribute values.
                    517: * Tagging Insns::       Assigning attribute values to insns.
                    518: * Attr Example::        An example of assigning attributes.
                    519: * Insn Lengths::        Computing the length of insns.
1.1.1.2 ! root      520: * Constant Attributes:: Defining attributes that are constant.
1.1       root      521: * Delay Slots::         Defining delay slots required for a machine.
                    522: * Function Units::      Specifying information for insn scheduling.
                    523: 
                    524: 
                    525: File: gcc.info,  Node: Defining Attributes,  Next: Expressions,  Prev: Insn Attributes,  Up: Insn Attributes
                    526: 
                    527: Defining Attributes and their Values
                    528: ------------------------------------
                    529: 
                    530:    The `define_attr' expression is used to define each attribute
                    531: required by the target machine.  It looks like:
                    532: 
                    533:      (define_attr NAME LIST-OF-VALUES DEFAULT)
                    534: 
                    535:    NAME is a string specifying the name of the attribute being defined.
                    536: 
                    537:    LIST-OF-VALUES is either a string that specifies a comma-separated
                    538: list of values that can be assigned to the attribute, or a null string
                    539: to indicate that the attribute takes numeric values.
                    540: 
                    541:    DEFAULT is an attribute expression that gives the value of this
                    542: attribute for insns that match patterns whose definition does not
                    543: include an explicit value for this attribute.  *Note Attr Example::,
1.1.1.2 ! root      544: for more information on the handling of defaults.  *Note Constant
        !           545: Attributes::, for information on attributes that do not depend on any
        !           546: particular insn.
1.1       root      547: 
                    548:    For each defined attribute, a number of definitions are written to
                    549: the `insn-attr.h' file.  For cases where an explicit set of values is
                    550: specified for an attribute, the following are defined:
                    551: 
                    552:    * A `#define' is written for the symbol `HAVE_ATTR_NAME'.
                    553: 
                    554:    * An enumeral class is defined for `attr_NAME' with elements of the
                    555:      form `UPPER-NAME_UPPER-VALUE' where the attribute name and value
                    556:      are first converted to upper case.
                    557: 
                    558:    * A function `get_attr_NAME' is defined that is passed an insn and
                    559:      returns the attribute value for that insn.
                    560: 
                    561:    For example, if the following is present in the `md' file:
                    562: 
                    563:      (define_attr "type" "branch,fp,load,store,arith" ...)
                    564: 
                    565: the following lines will be written to the file `insn-attr.h'.
                    566: 
                    567:      #define HAVE_ATTR_type
                    568:      enum attr_type {TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
                    569:                 TYPE_STORE, TYPE_ARITH};
                    570:      extern enum attr_type get_attr_type ();
                    571: 
                    572:    If the attribute takes numeric values, no `enum' type will be
                    573: defined and the function to obtain the attribute's value will return
                    574: `int'.
                    575: 
                    576: 
                    577: File: gcc.info,  Node: Expressions,  Next: Tagging Insns,  Prev: Defining Attributes,  Up: Insn Attributes
                    578: 
                    579: Attribute Expressions
                    580: ---------------------
                    581: 
                    582:    RTL expressions used to define attributes use the codes described
                    583: above plus a few specific to attribute definitions, to be discussed
                    584: below.  Attribute value expressions must have one of the following
                    585: forms:
                    586: 
                    587: `(const_int I)'
                    588:      The integer I specifies the value of a numeric attribute.  I must
                    589:      be non-negative.
                    590: 
                    591:      The value of a numeric attribute can be specified either with a
                    592:      `const_int' or as an integer represented as a string in
                    593:      `const_string', `eq_attr' (see below), and `set_attr' (*note
                    594:      Tagging Insns::.) expressions.
                    595: 
                    596: `(const_string VALUE)'
                    597:      The string VALUE specifies a constant attribute value.  If VALUE
                    598:      is specified as `"*"', it means that the default value of the
                    599:      attribute is to be used for the insn containing this expression. 
                    600:      `"*"' obviously cannot be used in the DEFAULT expression of a
                    601:      `define_attr'.
                    602: 
                    603:      If the attribute whose value is being specified is numeric, VALUE
                    604:      must be a string containing a non-negative integer (normally
                    605:      `const_int' would be used in this case).  Otherwise, it must
                    606:      contain one of the valid values for the attribute.
                    607: 
                    608: `(if_then_else TEST TRUE-VALUE FALSE-VALUE)'
                    609:      TEST specifies an attribute test, whose format is defined below. 
                    610:      The value of this expression is TRUE-VALUE if TEST is true,
                    611:      otherwise it is FALSE-VALUE.
                    612: 
                    613: `(cond [TEST1 VALUE1 ...] DEFAULT)'
                    614:      The first operand of this expression is a vector containing an
                    615:      even number of expressions and consisting of pairs of TEST and
                    616:      VALUE expressions.  The value of the `cond' expression is that of
                    617:      the VALUE corresponding to the first true TEST expression.  If
                    618:      none of the TEST expressions are true, the value of the `cond'
                    619:      expression is that of the DEFAULT expression.
                    620: 
                    621:    TEST expressions can have one of the following forms:
                    622: 
                    623: `(const_int I)'
                    624:      This test is true if I is non-zero and false otherwise.
                    625: 
                    626: `(not TEST)'
                    627: `(ior TEST1 TEST2)'
                    628: `(and TEST1 TEST2)'
                    629:      These tests are true if the indicated logical function is true.
                    630: 
                    631: `(match_operand:M N PRED CONSTRAINTS)'
                    632:      This test is true if operand N of the insn whose attribute value
                    633:      is being determined has mode M (this part of the test is ignored
                    634:      if M is `VOIDmode') and the function specified by the string PRED
                    635:      returns a non-zero value when passed operand N and mode M (this
                    636:      part of the test is ignored if PRED is the null string).
                    637: 
                    638:      The CONSTRAINTS operand is ignored and should be the null string.
                    639: 
                    640: `(le ARITH1 ARITH2)'
                    641: `(leu ARITH1 ARITH2)'
                    642: `(lt ARITH1 ARITH2)'
                    643: `(ltu ARITH1 ARITH2)'
                    644: `(gt ARITH1 ARITH2)'
                    645: `(gtu ARITH1 ARITH2)'
                    646: `(ge ARITH1 ARITH2)'
                    647: `(geu ARITH1 ARITH2)'
                    648: `(ne ARITH1 ARITH2)'
                    649: `(eq ARITH1 ARITH2)'
                    650:      These tests are true if the indicated comparison of the two
                    651:      arithmetic expressions is true.  Arithmetic expressions are
                    652:      formed with `plus', `minus', `mult', `div', `mod', `abs', `neg',
                    653:      `and', `ior', `xor', `not', `lshift', `ashift', `lshiftrt', and
                    654:      `ashiftrt' expressions.
                    655: 
                    656:      `const_int' and `symbol_ref' are always valid terms (*note Insn
                    657:      Lengths::.,for additional forms).  `symbol_ref' is a string
                    658:      denoting a C expression that yields an `int' when evaluated by the
                    659:      `get_attr_...' routine.  It should normally be a global variable.
                    660: 
                    661: `(eq_attr NAME VALUE)'
                    662:      NAME is a string specifying the name of an attribute.
                    663: 
                    664:      VALUE is a string that is either a valid value for attribute
                    665:      NAME, a comma-separated list of values, or `!' followed by a
                    666:      value or list.  If VALUE does not begin with a `!', this test is
                    667:      true if the value of the NAME attribute of the current insn is in
                    668:      the list specified by VALUE.  If VALUE begins with a `!', this
                    669:      test is true if the attribute's value is *not* in the specified
                    670:      list.
                    671: 
                    672:      For example,
                    673: 
                    674:           (eq_attr "type" "load,store")
                    675: 
                    676:      is equivalent to
                    677: 
                    678:           (ior (eq_attr "type" "load") (eq_attr "type" "store"))
                    679: 
                    680:      If NAME specifies an attribute of `alternative', it refers to the
                    681:      value of the compiler variable `which_alternative' (*note Output
                    682:      Statement::.) and the values must be small integers.  For example,
                    683: 
                    684:           (eq_attr "alternative" "2,3")
                    685: 
                    686:      is equivalent to
                    687: 
                    688:           (ior (eq (symbol_ref "which_alternative") (const_int 2))
                    689:                (eq (symbol_ref "which_alternative") (const_int 3)))
                    690: 
                    691:      Note that, for most attributes, an `eq_attr' test is simplified
                    692:      in cases where the value of the attribute being tested is known
                    693:      for all insns matching a particular pattern.  This is by far the
                    694:      most common case.
                    695: 
                    696: 
                    697: File: gcc.info,  Node: Tagging Insns,  Next: Attr Example,  Prev: Expressions,  Up: Insn Attributes
                    698: 
                    699: Assigning Attribute Values to Insns
                    700: -----------------------------------
                    701: 
                    702:    The value assigned to an attribute of an insn is primarily
                    703: determined by which pattern is matched by that insn (or which
                    704: `define_peephole' generated it).  Every `define_insn' and
                    705: `define_peephole' can have an optional last argument to specify the
                    706: values of attributes for matching insns.  The value of any attribute
                    707: not specified in a particular insn is set to the default value for
                    708: that attribute, as specified in its `define_attr'.  Extensive use of
                    709: default values for attributes permits the specification of the values
                    710: for only one or two attributes in the definition of most insn
                    711: patterns, as seen in the example in the next section.
                    712: 
                    713:    The optional last argument of `define_insn' and `define_peephole'
                    714: is a vector of expressions, each of which defines the value for a
                    715: single attribute.  The most general way of assigning an attribute's
                    716: value is to use a `set' expression whose first operand is an `attr'
                    717: expression giving the name of the attribute being set.  The second
                    718: operand of the `set' is an attribute expression (*note Expressions::.)
                    719: giving the value of the attribute.
                    720: 
                    721:    When the attribute value depends on the `alternative' attribute
                    722: (i.e., which is the applicable alternative in the constraint of the
                    723: insn), the `set_attr_alternative' expression can can be used.  It
                    724: allows the specification of a vector of attribute expressions, one for
                    725: each alternative.
                    726: 
                    727:    When the generality of arbitrary attribute expressions is not
                    728: required, the simpler `set_attr' expression can be used, which allows
                    729: specifying a string giving either a single attribute value or a list
                    730: of attribute values, one for each alternative.
                    731: 
                    732:    The form of each of the above specifications is shown below.  In
                    733: each case, NAME is a string specifying the attribute to be set.
                    734: 
                    735: `(set_attr NAME VALUE-STRING)'
                    736:      VALUE-STRING is either a string giving the desired attribute
                    737:      value, or a string containing a comma-separated list giving the
                    738:      values for succeeding alternatives.  The number of elements must
                    739:      match the number of alternatives in the constraint of the insn
                    740:      pattern.
                    741: 
                    742:      Note that it may be useful to specify `*' for some alternative, in
                    743:      which case the attribute will assume its default value for insns
                    744:      matching that alternative.
                    745: 
                    746: `(set_attr_alternative NAME [VALUE1 VALUE2 ...])'
                    747:      Depending on the alternative of the insn, the value will be one
                    748:      of the specified values.  This is a shorthand for using a `cond'
                    749:      with tests on the `alternative' attribute.
                    750: 
                    751: `(set (attr NAME) VALUE)'
                    752:      The first operand of this `set' must be the special RTL expression
                    753:      `attr', whose sole operand is a string giving the name of the
                    754:      attribute being set.  VALUE is the value of the attribute.
                    755: 
                    756:    The following shows three different ways of representing the same
                    757: attribute value specification:
                    758: 
                    759:      (set_attr "type" "load,store,arith")
                    760:      
                    761:      (set_attr_alternative "type"
                    762:                            [(const_string "load") (const_string "store")
                    763:                             (const_string "arith")])
                    764:      
                    765:      (set (attr "type")
                    766:           (cond [(eq_attr "alternative" "1") (const_string "load")
                    767:                  (eq_attr "alternative" "2") (const_string "store")]
                    768:                 (const_string "arith")))
                    769: 
                    770:    The `define_asm_attributes' expression provides a mechanism to
                    771: specify the attributes assigned to insns produced from an `asm'
                    772: statement. It has the form:
                    773: 
                    774:      (define_asm_attributes [ATTR-SETS])
                    775: 
                    776: where ATTR-SETS is specified the same as for `define_insn' and
                    777: `define_peephole' expressions.
                    778: 
                    779:    These values will typically be the "worst case" attribute values. 
                    780: For example, they might indicate that the condition code will be
                    781: clobbered.
                    782: 
                    783:    A specification for a `length' attribute is handled specially.  To
                    784: compute the length of an `asm' insn, the length specified in the
                    785: `define_asm_attributes' expression is multiplied by the number of
                    786: machine instructions specified in the `asm' statement, determined by
                    787: counting the number of semicolons and newlines in the string. 
                    788: Therefore, the value of the `length' attribute specified in a
                    789: `define_asm_attributes' should be the maximum possible length of a
                    790: single machine instruction.
                    791: 
                    792: 
                    793: File: gcc.info,  Node: Attr Example,  Next: Insn Lengths,  Prev: Tagging Insns,  Up: Insn Attributes
                    794: 
                    795: Example of Attribute Specifications
                    796: -----------------------------------
                    797: 
                    798:    The judicious use of defaulting is important in the efficient use of
                    799: insn attributes.  Typically, insns are divided into "types" and an
                    800: attribute, customarily called `type', is used to represent this value.
                    801:  This attribute is normally used only to define the default value for
                    802: other attributes.  An example will clarify this usage.
                    803: 
                    804:    Assume we have a RISC machine with a condition code and in which
                    805: only full-word operations are performed in registers.  Let us assume
                    806: that we can divide all insns into loads, stores, (integer) arithmetic
                    807: operations, floating point operations, and branches.
                    808: 
                    809:    Here we will concern ourselves with determining the effect of an
                    810: insn on the condition code and will limit ourselves to the following
                    811: possible effects:  The condition code can be set unpredictably
                    812: (clobbered), not be changed, be set to agree with the results of the
                    813: operation, or only changed if the item previously set into the
                    814: condition code has been modified.
                    815: 
                    816:    Here is part of a sample `md' file for such a machine:
                    817: 
                    818:      (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
                    819:      
                    820:      (define_attr "cc" "clobber,unchanged,set,change0"
                    821:                   (cond [(eq_attr "type" "load")
                    822:                              (const_string "change0")
                    823:                          (eq_attr "type" "store,branch")
                    824:                              (const_string "unchanged")
                    825:                          (eq_attr "type" "arith")
                    826:                              (if_then_else (match_operand:SI 0 "" "")
                    827:                                            (const_string "set")
                    828:                                            (const_string "clobber"))]
                    829:                         (const_string "clobber")))
                    830:      
                    831:      (define_insn ""
                    832:        [(set (match_operand:SI 0 "general_operand" "=r,r,m")
                    833:              (match_operand:SI 1 "general_operand" "r,m,r"))]
                    834:        ""
                    835:        "@
                    836:         move %0,%1
                    837:         load %0,%1
                    838:         store %0,%1"
                    839:        [(set_attr "type" "arith,load,store")])
                    840: 
                    841:    Note that we assume in the above example that arithmetic operations
                    842: performed on quantities smaller than a machine word clobber the
                    843: condition code since they will set the condition code to a value
                    844: corresponding to the full-word result.
                    845: 
                    846: 
1.1.1.2 ! root      847: File: gcc.info,  Node: Insn Lengths,  Next: Constant Attributes,  Prev: Attr Example,  Up: Insn Attributes
1.1       root      848: 
                    849: Computing the Length of an Insn
                    850: -------------------------------
                    851: 
                    852:    For many machines, multiple types of branch instructions are
                    853: provided, each for different length branch displacements.  In most
                    854: cases, the assembler will choose the correct instruction to use. 
                    855: However, when the assembler cannot do so, GCC can when a special
                    856: attribute, the `length' attribute, is defined.  This attribute must be
                    857: defined to have numeric values by specifying a null string in its
                    858: `define_attr'.
                    859: 
                    860:    In the case of the `length' attribute, two additional forms of
                    861: arithmetic terms are allowed in test expressions:
                    862: 
                    863: `(match_dup N)'
                    864:      This refers to the address of operand N of the current insn, which
                    865:      must be a `label_ref'.
                    866: 
                    867: `(pc)'
                    868:      This refers to the address of the *current* insn.  It might have
                    869:      been more consistent with other usage to make this the address of
                    870:      the *next* insn but this would be confusing because the length of
                    871:      the current insn is to be computed.
                    872: 
                    873:    For normal insns, the length will be determined by value of the
                    874: `length' attribute.  In the case of `addr_vec' and `addr_diff_vec'
                    875: insn patterns, the length will be computed as the number of vectors
                    876: multiplied by the size of each vector.
                    877: 
                    878:    The following macros can be used to refine the length computation:
                    879: 
                    880: `FIRST_INSN_ADDRESS'
                    881:      When the `length' insn attribute is used, this macro specifies the
                    882:      value to be assigned to the address of the first insn in a
                    883:      function.  If not specified, 0 is used.
                    884: 
                    885: `ADJUST_INSN_LENGTH (INSN, LENGTH)'
                    886:      If defined, modifies the length assigned to instruction INSN as a
                    887:      function of the context in which it is used.  LENGTH is an lvalue
                    888:      that contains the initially computed length of the insn and
                    889:      should be updated with the correct length of the insn.  If
                    890:      updating is required, INSN must not be a varying-length insn.
                    891: 
                    892:      This macro will normally not be required.  A case in which it is
                    893:      required is the ROMP.  On this machine, the size of an `addr_vec'
                    894:      insn must be increased by two to compensate for the fact that
                    895:      alignment may be required.
                    896: 
                    897:    The routine that returns the value of the `length' attribute,
1.1.1.2 ! root      898: `get_attr_length', can be used by the output routine to determine the
1.1       root      899: form of the branch instruction to be written, as the example below
                    900: illustrates.
                    901: 
                    902:    As an example of the specification of variable-length branches,
                    903: consider the IBM 360.  If we adopt the convention that a register will
                    904: be set to the starting address of a function, we can jump to labels
                    905: within 4K of the start using a four-byte instruction.  Otherwise, we
                    906: need a six-byte sequence to load the address from memory and then
                    907: branch to it.
                    908: 
                    909:    On such a machine, a pattern for a branch instruction might be
                    910: specified as follows:
                    911: 
                    912:      (define_insn "jump"
                    913:        [(set (pc)
                    914:              (label_ref (match_operand 0 "" "")))]
                    915:        ""
                    916:        "*
                    917:      {
                    918:         return (get_attr_length (insn) == 4
                    919:                 ? \"b %l0\" : \"l r15,=a(%l0); br r15\");
                    920:      }"
                    921:        [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096))
                    922:                                            (const_int 4)
                    923:                                            (const_int 6)))])
                    924: 
                    925: 
1.1.1.2 ! root      926: File: gcc.info,  Node: Constant Attributes,  Next: Delay Slots,  Prev: Insn Lengths,  Up: Insn Attributes
        !           927: 
        !           928: Constant Attributes
        !           929: -------------------
        !           930: 
        !           931:    A special form of DEFINE_ATTR, where the expression for the default
        !           932: value is a CONST expression, indicates an attribute that is constant
        !           933: for a given run of the compiler.  Constant attributes may be used to
        !           934: specify which variety of processor is used.  For example,
        !           935: 
        !           936:      (define_attr "cpu" "m88100,m88110,m88000"
        !           937:       (const
        !           938:        (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
        !           939:         (symbol_ref "TARGET_88110") (const_string "m88110")]
        !           940:        (const_string "m88000"))))
        !           941:      
        !           942:      (define_attr "memory" "fast,slow"
        !           943:       (const
        !           944:        (if_then_else (symbol_ref "TARGET_FAST_MEM")
        !           945:                (const_string "fast")
        !           946:                (const_string "slow"))))
        !           947: 
        !           948:    The routine generated for constant attributes has no parameters as
        !           949: it does not depend on any particular insn.  RTL expressions used to
        !           950: define the value of a constant attribute may use the SYMBOL_REF form,
        !           951: but may not use either the MATCH_OPERAND form or EQ_ATTR forms
        !           952: involving insn attributes.
        !           953: 
        !           954: 
        !           955: File: gcc.info,  Node: Delay Slots,  Next: Function Units,  Prev: Constant Attributes,  Up: Insn Attributes
1.1       root      956: 
                    957: Delay Slot Scheduling
                    958: ---------------------
                    959: 
                    960:    The insn attribute mechanism can be used to specify the
                    961: requirements for delay slots, if any, on a target machine.  An
                    962: instruction is said to require a "delay slot" if some instructions
                    963: that are physically after the instruction are executed as if they were
                    964: located before it.  Classic examples are branch and call instructions,
                    965: which often execute the following instruction before the branch or
                    966: call is performed.
                    967: 
                    968:    On some machines, conditional branch instructions can optionally
                    969: "annul" instructions in the delay slot.  This means that the
                    970: instruction will not be executed for certain branch outcomes.  Both
                    971: instructions that annul if the branch is true and instructions that
                    972: annul if the branch is false are supported.
                    973: 
                    974:    Delay slot scheduling differs from instruction scheduling in that
                    975: determining whether an instruction needs a delay slot is dependent only
                    976: on the type of instruction being generated, not on data flow between
                    977: the instructions.  See the next section for a discussion of
                    978: data-dependent instruction scheduling.
                    979: 
                    980:    The requirement of an insn needing one or more delay slots is
                    981: indicated via the `define_delay' expression.  It has the following
                    982: form:
                    983: 
                    984:      (define_delay TEST
                    985:                    [DELAY-1 ANNUL-TRUE-1 ANNUL-FALSE-1
                    986:                     DELAY-2 ANNUL-TRUE-2 ANNUL-FALSE-2
                    987:                     ...])
                    988: 
                    989:    TEST is an attribute test that indicates whether this
                    990: `define_delay' applies to a particular insn.  If so, the number of
                    991: required delay slots is determined by the length of the vector
                    992: specified as the second argument.  An insn placed in delay slot N must
                    993: satisfy attribute test DELAY-N.  ANNUL-TRUE-N is an attribute test
                    994: that specifies which insns may be annulled if the branch is true. 
                    995: Similarly, ANNUL-FALSE-N specifies which insns in the delay slot may
                    996: be annulled if the branch is false.  If annulling is not supported for
                    997: that delay slot, `(nil)' should be coded.
                    998: 
                    999:    For example, in the common case where branch and call insns require
                   1000: a single delay slot, which may contain any insn other than a branch or
                   1001: call, the following would be placed in the `md' file:
                   1002: 
                   1003:      (define_delay (eq_attr "type" "branch,call")
                   1004:                    [(eq_attr "type" "!branch,call") (nil) (nil)])
                   1005: 
                   1006:    Multiple `define_delay' expressions may be specified.  In this
                   1007: case, each such expression specifies different delay slot requirements
                   1008: and there must be no insn for which tests in two `define_delay'
                   1009: expressions are both true.
                   1010: 
                   1011:    For example, if we have a machine that requires one delay slot for
                   1012: branches but two for calls,  no delay slot can contain a branch or
                   1013: call insn, and any valid insn in the delay slot for the branch can be
                   1014: annulled if the branch is true, we might represent this as follows:
                   1015: 
                   1016:      (define_delay (eq_attr "type" "branch")
                   1017:         [(eq_attr "type" "!branch,call") (eq_attr "type" "!branch,call") (nil)])
                   1018:      
                   1019:      (define_delay (eq_attr "type" "call")
                   1020:                    [(eq_attr "type" "!branch,call") (nil) (nil)
                   1021:                     (eq_attr "type" "!branch,call") (nil) (nil)])
                   1022: 
                   1023: 
                   1024: File: gcc.info,  Node: Function Units,  Prev: Delay Slots,  Up: Insn Attributes
                   1025: 
                   1026: Specifying Function Units
                   1027: -------------------------
                   1028: 
                   1029:    On most RISC machines, there are instructions whose results are not
                   1030: available for a specific number of cycles.  Common cases are
                   1031: instructions that load data from memory.  On many machines, a pipeline
                   1032: stall will result if the data is referenced too soon after the load
                   1033: instruction.
                   1034: 
                   1035:    In addition, many newer microprocessors have multiple function
                   1036: units, usually one for integer and one for floating point, and often
                   1037: will incur pipeline stalls when a result that is needed is not yet
                   1038: ready.
                   1039: 
                   1040:    The descriptions in this section allow the specification of how much
                   1041: time must elapse between the execution of an instruction and the time
                   1042: when its result is used.  It also allows specification of when the
                   1043: execution of an instruction will delay execution of similar
                   1044: instructions due to function unit conflicts.
                   1045: 
                   1046:    For the purposes of the specifications in this section, a machine is
                   1047: divided into "function units", each of which execute a specific class
                   1048: of instructions.  Function units that accept one instruction each
                   1049: cycle and allow a result to be used in the succeeding instruction
                   1050: (usually via forwarding) need not be specified.  Classic RISC
                   1051: microprocessors will normally have a single function unit, which we can
                   1052: call `memory'.  The newer "superscalar" processors will often have
                   1053: function units for floating point operations, usually at least a
                   1054: floating point adder and multiplier.
                   1055: 
                   1056:    Each usage of a function units by a class of insns is specified
                   1057: with a `define_function_unit' expression, which looks like this:
                   1058: 
                   1059:      (define_function_unit NAME MULTIPLICITY SIMULTANEITY
                   1060:                      TEST READY-DELAY BUSY-DELAY
                   1061:                     [CONFLICT-LIST])
                   1062: 
                   1063:    NAME is a string giving the name of the function unit.
                   1064: 
                   1065:    MULTIPLICITY is an integer specifying the number of identical units
                   1066: in the processor.  If more than one unit is specified, they will be
                   1067: scheduled independently.  Only truly independent units should be
                   1068: counted; a pipelined unit should be specified as a single unit.  (The
                   1069: only common example of a machine that has multiple function units for a
                   1070: single instruction class that are truly independent and not pipelined
                   1071: are the two multiply and two increment units of the CDC 6600.)
                   1072: 
                   1073:    SIMULTANEITY specifies the maximum number of insns that can be
                   1074: executing in each instance of the function unit simultaneously or zero
                   1075: if the unit is pipelined and has no limit.
                   1076: 
                   1077:    All `define_function_unit' definitions referring to function unit
                   1078: NAME must have the same name and values for MULTIPLICITY and
                   1079: SIMULTANEITY.
                   1080: 
                   1081:    TEST is an attribute test that selects the insns we are describing
                   1082: in this definition.  Note that an insn may use more than one function
                   1083: unit and a function unit may be specified in more than one
                   1084: `define_function_unit'.
                   1085: 
                   1086:    READY-DELAY is an integer that specifies the number of cycles after
                   1087: which the result of the instruction can be used without introducing
                   1088: any stalls.
                   1089: 
                   1090:    BUSY-DELAY is an integer that represents the default cost if an
                   1091: insn is scheduled for this unit while the unit is active with another
                   1092: insn.  If SIMULTANEITY is zero, this specification is ignored. 
                   1093: Otherwise, a zero value indicates that these insns execute on NAME in
                   1094: a fully pipelined fashion, even if SIMULTANEITY is non-zero.  A
                   1095: non-zero value indicates that scheduling a new insn on this unit while
                   1096: another is active will incur a cost.  A cost of two indicates a single
                   1097: cycle delay.  For a normal non-pipelined function unit, BUSY-DELAY
                   1098: will be twice READY-DELAY.
                   1099: 
                   1100:    CONFLICT-LIST is an optional list giving detailed conflict costs
                   1101: for this unit.  If specified, it is a list of condition test
                   1102: expressions which are applied to insns already executing in NAME.  For
                   1103: each insn that is in the list, BUSY-DELAY will be used for the conflict
                   1104: cost, while a value of zero will be used for insns not in the list.
                   1105: 
                   1106:    Typical uses of this vector are where a floating point function
                   1107: unit can pipeline either single- or double-precision operations, but
                   1108: not both, or where a memory unit can pipeline loads, but not stores,
                   1109: etc.
                   1110: 
                   1111:    As an example, consider a classic RISC machine where the result of a
                   1112: load instruction is not available for two cycles (a single "delay"
                   1113: instruction is required) and where only one load instruction can be
                   1114: executed simultaneously.  This would be specified as:
                   1115: 
                   1116:      (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 4)
                   1117: 
                   1118:    For the case of a floating point function unit that can pipeline
                   1119: either single or double precision, but not both, the following could
                   1120: be specified:
                   1121: 
                   1122:      (define_function_unit
                   1123:         "fp" 1 1 (eq_attr "type" "sp_fp") 4 8 (eq_attr "type" "dp_fp")]
                   1124:      (define_function_unit
                   1125:         "fp" 1 1 (eq_attr "type" "dp_fp") 4 8 (eq_attr "type" "sp_fp")]
                   1126: 
                   1127:    *Note:* No code currently exists to avoid function unit conflicts,
                   1128: only data conflicts.  Hence MULTIPLICITY, SIMULTANEITY, BUSY-COST, and
                   1129: CONFLICT-LIST are currently ignored.  When such code is written, it is
                   1130: possible that the specifications for these values may be changed.  It
                   1131: has recently come to our attention that these specifications may not
                   1132: allow modeling of some of the newer "superscalar" processors that have
                   1133: insns using multiple pipelined units.  These insns will cause a
                   1134: potential conflict for the second unit used during their execution and
                   1135: there is no way of representing that conflict.  We welcome any
                   1136: examples of how function unit conflicts work in such processors and
                   1137: suggestions for their representation.
                   1138: 
                   1139: 
1.1.1.2 ! root     1140: File: gcc.info,  Node: Target Macros,  Next: Config,  Prev: Machine Desc,  Up: Top
1.1       root     1141: 
1.1.1.2 ! root     1142: Target Description Macros
        !          1143: *************************
1.1       root     1144: 
                   1145:    In addition to the file `MACHINE.md', a machine description
                   1146: includes a C header file conventionally given the name `MACHINE.h'. 
                   1147: This header file defines numerous macros that convey the information
                   1148: about the target machine that does not fit into the scheme of the
                   1149: `.md' file.  The file `tm.h' should be a link to `MACHINE.h'.  The
                   1150: header file `config.h' includes `tm.h' and most compiler source files
                   1151: include `config.h'.
                   1152: 
                   1153: * Menu:
                   1154: 
                   1155: * Driver::              Controlling how the driver runs the compilation passes.
                   1156: * Run-time Target::     Defining `-m' options like `-m68000' and `-m68020'.
                   1157: * Storage Layout::      Defining sizes and alignments of data.
                   1158: * Type Layout::         Defining sizes and properties of basic user data types.
                   1159: * Registers::           Naming and describing the hardware registers.
                   1160: * Register Classes::    Defining the classes of hardware registers.
                   1161: * Stack and Calling::   Defining which way the stack grows and by how much.
                   1162: * Varargs::            Defining the varargs macros.
                   1163: * Trampolines::         Code set up at run time to enter a nested function.
                   1164: * Library Calls::       Controlling how library routines are implicitly called.
                   1165: * Addressing Modes::    Defining addressing modes valid for memory operands.
                   1166: * Condition Code::      Defining how insns update the condition code.
                   1167: * Costs::               Defining relative costs of different operations.
                   1168: * Sections::            Dividing storage into text, data, and other sections.
                   1169: * PIC::                        Macros for position independent code.
                   1170: * Assembler Format::    Defining how to write insns and pseudo-ops to output.
                   1171: * Debugging Info::      Defining the format of debugging output.
                   1172: * Cross-compilation::   Handling floating point for cross-compilers.
                   1173: * Misc::                Everything else.
                   1174: 
                   1175: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.