Return to internals-4 CVS log

Up to [GCC 1.x] / gcc

Annotation of gcc/internals-4, revision 1.1

1.1     ! root        1: Info file internals, produced by Makeinfo, -*- Text -*-
        !             2: from input file internals.texinfo.
        !             3: 
        !             4: 
        !             5: 
        !             6: This file documents the internals of the GNU compiler.
        !             7: 
        !             8: Copyright (C) 1988 Free Software Foundation, Inc.
        !             9: 
        !            10: Permission is granted to make and distribute verbatim copies of
        !            11: this manual provided the copyright notice and this permission notice
        !            12: are preserved on all copies.
        !            13: 
        !            14: Permission is granted to copy and distribute modified versions of this
        !            15: manual under the conditions for verbatim copying, provided also that the
        !            16: section entitled ``GNU CC General Public License'' is included exactly as
        !            17: in the original, and provided that the entire resulting derived work is
        !            18: distributed under the terms of a permission notice identical to this one.
        !            19: 
        !            20: Permission is granted to copy and distribute translations of this manual
        !            21: into another language, under the above conditions for modified versions,
        !            22: except that the section entitled ``GNU CC General Public License'' and
        !            23: this permission notice may be included in translations approved by the
        !            24: Free Software Foundation instead of in the original English.
        !            25: 
        !            26: 
        !            27: 
        !            28: 
        !            29: 
        !            30: 
        !            31: File: internals,  Node: Sharing,  Prev: Calls,  Up: RTL
        !            32: 
        !            33: Structure Sharing Assumptions
        !            34: =============================
        !            35: 
        !            36: The compiler assumes that certain kinds of RTL expressions are unique;
        !            37: there do not exist two distinct objects representing the same value.  In
        !            38: other cases, it makes an opposite assumption: that no RTL expression object
        !            39: of a certain kind appears in more than one place in the containing structure.
        !            40: 
        !            41: These assumptions refer to a single function; except for the RTL objects
        !            42: that describe global variables and external functions, no RTL objects are
        !            43: common to two functions.
        !            44: 
        !            45:    * Each pseudo-register has only a single `reg' object to represent it,
        !            46:      and therefore only a single machine mode.
        !            47: 
        !            48:    * For any symbolic label, there is only one `symbol_ref' object
        !            49:      referring to it.
        !            50: 
        !            51:    * There is only one `const_int' expression with value zero, and only one
        !            52:      with value one.
        !            53: 
        !            54:    * There is only one `pc' expression.
        !            55: 
        !            56:    * There is only one `cc0' expression.
        !            57: 
        !            58:    * There is only one `const_double' expression with mode `SFmode' and
        !            59:      value zero, and only one with mode `DFmode' and value zero.
        !            60: 
        !            61:    * No `label_ref' appears in more than one place in the RTL structure; in
        !            62:      other words, it is safe to do a tree-walk of all the insns in the
        !            63:      function and assume that each time a `label_ref' is seen it is
        !            64:      distinct from all others that are seen.
        !            65: 
        !            66:    * Only one `mem' object is normally created for each static variable or
        !            67:      stack slot, so these objects are frequently shared in all the places
        !            68:      they appear.  However, separate but equal objects for these variables
        !            69:      are occasionally made.
        !            70: 
        !            71:    * No RTL object appears in more than one place in the RTL structure
        !            72:      except as described above.  Many passes of the compiler rely on this
        !            73:      by assuming that they can modify RTL objects in place without unwanted
        !            74:      side-effects on other insns.
        !            75: 
        !            76:    * During initial RTL generation, shared structure is freely introduced. 
        !            77:      After all the RTL for a function has been generated, all shared
        !            78:      structure is copied by `unshare_all_rtl' in `emit-rtl.c', after which
        !            79:      the above rules are guaranteed to be followed.
        !            80: 
        !            81:    * During the combiner pass, shared structure with an insn can exist
        !            82:      temporarily.  However, the shared structure is copied before the
        !            83:      combiner is finished with the insn.  This is done by
        !            84:      `copy_substitutions' in `combine.c'.
        !            85: 
        !            86: 
        !            87: File: internals,  Node: Machine Desc,  Next: Machine Macros,  Prev: RTL,  Up: Top
        !            88: 
        !            89: Machine Descriptions
        !            90: ********************
        !            91: 
        !            92: A machine description has two parts: a file of instruction patterns (`.md'
        !            93: file) and a C header file of macro definitions.
        !            94: 
        !            95: The `.md' file for a target machine contains a pattern for each instruction
        !            96: that the target machine supports (or at least each instruction that is
        !            97: worth telling the compiler about).  It may also contain comments.  A
        !            98: semicolon causes the rest of the line to be a comment, unless the semicolon
        !            99: is inside a quoted string.
        !           100: 
        !           101: See the next chapter for information on the C header file.
        !           102: 
        !           103: 
        !           104: * Menu:
        !           105: 
        !           106: * Patterns::            How to write instruction patterns.
        !           107: * Example::             An explained example of a `define_insn' pattern.
        !           108: * RTL Template::        The RTL template defines what insns match a pattern.
        !           109: * Output Template::     The output template says how to make assembler code
        !           110:                           from such an insn.
        !           111: * Output Statement::    For more generality, write C code to output 
        !           112:                           the assembler code.
        !           113: * Constraints::         When not all operands are general operands.
        !           114: * Standard Names::      Names mark patterns to use for code generation.
        !           115: * Pattern Ordering::    When the order of patterns makes a difference.
        !           116: * Dependent Patterns::  Having one pattern may make you need another.
        !           117: * Jump Patterns::       Special considerations for patterns for jump insns.
        !           118: * Peephole Definitions::Defining machine-specific peephole optimizations.
        !           119: * Expander Definitions::Generating a sequence of several RTL insns
        !           120:                          for a standard operation.
        !           121: 
        !           122: 
        !           123: 
        !           124: File: internals,  Node: Patterns,  Next: Example,  Prev: Machine Desc,  Up: Machine Desc
        !           125: 
        !           126: Everything about Instruction Patterns
        !           127: =====================================
        !           128: 
        !           129: Each instruction pattern contains an incomplete RTL expression, with pieces
        !           130: to be filled in later, operand constraints that restrict how the pieces can
        !           131: be filled in, and an output pattern or C code to generate the assembler
        !           132: output, all wrapped up in a `define_insn' expression.
        !           133: 
        !           134: A `define_insn' is an RTL expression containing four operands:
        !           135: 
        !           136:   1. An optional name.  The presence of a name indicate that this instruction
        !           137:      pattern can perform a certain standard job for the RTL-generation pass
        !           138:      of the compiler.  This pass knows certain names and will use the
        !           139:      instruction patterns with those names, if the names are defined in the
        !           140:      machine description.
        !           141: 
        !           142:      The absence of a name is indicated by writing an empty string where
        !           143:      the name should go.  Nameless instruction patterns are never used for
        !           144:      generating RTL code, but they may permit several simpler insns to be
        !           145:      combined later on.
        !           146: 
        !           147:      Names that are not thus known and used in RTL-generation have no
        !           148:      effect; they are equivalent to no name at all.
        !           149: 
        !           150:   2. The "RTL template" (*Note RTL Template::.) is a vector of incomplete RTL
        !           151:      expressions which show what the instruction should look like.  It is
        !           152:      incomplete because it may contain `match_operand' and `match_dup'
        !           153:      expressions that stand for operands of the instruction.
        !           154: 
        !           155:      If the vector has only one element, that element is what the
        !           156:      instruction should look like.  If the vector has multiple elements,
        !           157:      then the instruction looks like a `parallel' expression containing
        !           158:      that many elements as described.
        !           159: 
        !           160:   3. A condition.  This is a string which contains a C expression that is the
        !           161:      final test to decide whether an insn body matches this pattern.
        !           162: 
        !           163:      For a named pattern, the condition (if present) may not depend on the
        !           164:      data in the insn being matched, but only the target-machine-type
        !           165:      flags.  The compiler needs to test these conditions during
        !           166:      initialization in order to learn exactly which named instructions are
        !           167:      available in a particular run.
        !           168: 
        !           169:      For nameless patterns, the condition is applied only when matching an
        !           170:      individual insn, and only after the insn has matched the pattern's
        !           171:      recognition template.  The insn's operands may be found in the vector
        !           172:      `operands'.
        !           173: 
        !           174:   4. The "output template": a string that says how to output matching insns
        !           175:      as assembler code.  `%' in this string specifies where to substitute
        !           176:      the value of an operand.  *note Output Template::.
        !           177: 
        !           178:      When simple substitution isn't general enough, you can specify a piece
        !           179:      of C code to compute the output.  *note Output Statement::.
        !           180: 
        !           181: 
        !           182: File: internals,  Node: Example,  Next: RTL Template,  Prev: Patterns,  Up: Machine Desc
        !           183: 
        !           184: Example of `define_insn'
        !           185: ========================
        !           186: 
        !           187: Here is an actual example of an instruction pattern, for the 68000/68020.
        !           188: 
        !           189:      (define_insn "tstsi"
        !           190:        [(set (cc0)
        !           191:              (match_operand:SI 0 "general_operand" "rm"))]
        !           192:        ""
        !           193:        "*
        !           194:      { if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
        !           195:          return \"tstl %0\";
        !           196:        return \"cmpl #0,%0\"; }")
        !           197: 
        !           198: 
        !           199: This is an instruction that sets the condition codes based on the value of
        !           200: a general operand.  It has no condition, so any insn whose RTL description
        !           201: has the form shown may be handled according to this pattern.  The name
        !           202: `tstsi' means ``test a `SImode' value'' and tells the RTL generation pass
        !           203: that, when it is necessary to test such a value, an insn to do so can be
        !           204: constructed using this pattern.
        !           205: 
        !           206: The output control string is a piece of C code which chooses which output
        !           207: template to return based on the kind of operand and the specific type of
        !           208: CPU for which code is being generated.
        !           209: 
        !           210: `"rm"' is an operand constraint.  Its meaning is explained below.
        !           211: 
        !           212: 
        !           213: File: internals,  Node: RTL Template,  Next: Output Template,  Prev: Example,  Up: Machine Desc
        !           214: 
        !           215: RTL Template for Generating and Recognizing Insns
        !           216: =================================================
        !           217: 
        !           218: The RTL template is used to define which insns match the particular pattern
        !           219: and how to find their operands.  For named patterns, the RTL template also
        !           220: says how to construct an insn from specified operands.
        !           221: 
        !           222: Construction involves substituting specified operands into a copy of the
        !           223: template.  Matching involves determining the values that serve as the
        !           224: operands in the insn being matched.  Both of these activities are
        !           225: controlled by special expression types that direct matching and
        !           226: substitution of the operands.
        !           227: 
        !           228: `(match_operand:M N TESTFN CONSTRAINT)'
        !           229:      This expression is a placeholder for operand number N of the insn. 
        !           230:      When constructing an insn, operand number N will be substituted at
        !           231:      this point.  When matching an insn, whatever appears at this position
        !           232:      in the insn will be taken as operand number N; but it must satisfy
        !           233:      TESTFN or this instruction pattern will not match at all.
        !           234: 
        !           235:      Operand numbers must be chosen consecutively counting from zero in
        !           236:      each instruction pattern.  There may be only one `match_operand'
        !           237:      expression in the pattern for each expression number, and they must
        !           238:      appear in order of increasing expression number.
        !           239: 
        !           240:      TESTFN is a string that is the name of a C function that accepts two
        !           241:      arguments, a machine mode and an expression.  During matching, the
        !           242:      function will be called with M as the mode argument and the putative
        !           243:      operand as the other argument.  If it returns zero, this instruction
        !           244:      pattern fails to match.  TESTFN may be an empty string; then it means
        !           245:      no test is to be done on the operand.
        !           246: 
        !           247:      Most often, TESTFN is `"general_operand"'.  It checks that the
        !           248:      putative operand is either a constant, a register or a memory
        !           249:      reference, and that it is valid for mode M.
        !           250: 
        !           251:      For an operand that must be a register, TESTFN should be
        !           252:      `"register_operand"'.  This prevents GNU CC from creating insns that
        !           253:      have memory references in these operands, insns which would only have
        !           254:      to be taken apart in the reload pass.
        !           255: 
        !           256:      For an operand that must be a constant, either TESTFN should be
        !           257:      `"immediate_operand"', or the instruction pattern's extra condition
        !           258:      should check for constants, or both.
        !           259: 
        !           260:      CONSTRAINT is explained later (*Note Constraints::.).
        !           261: 
        !           262: `(match_dup N)'
        !           263:      This expression is also a placeholder for operand number N.  It is
        !           264:      used when the operand needs to appear more than once in the insn.
        !           265: 
        !           266:      In construction, `match_dup' behaves exactly like `match_operand': the
        !           267:      operand is substituted into the insn being constructed.  But in
        !           268:      matching, `match_dup' behaves differently.  It assumes that operand
        !           269:      number N has already been determined by a `match_operand' appearing
        !           270:      earlier in the recognition template, and it matches only an
        !           271:      identical-looking expression.
        !           272: 
        !           273: `(address (match_operand:M N "address_operand" ""))'
        !           274:      This complex of expressions is a placeholder for an operand number N
        !           275:      in a ``load address'' instruction: an operand which specifies a memory
        !           276:      location in the usual way, but for which the actual operand value used
        !           277:      is the address of the location, not the contents of the location.
        !           278: 
        !           279:      `address' expressions never appear in RTL code, only in machine
        !           280:      descriptions.  And they are used only in machine descriptions that do
        !           281:      not use the operand constraint feature.  When operand constraints are
        !           282:      in use, the letter `p' in the constraint serves this purpose.
        !           283: 
        !           284:      M is the machine mode of the *memory location being addressed*, not
        !           285:      the machine mode of the address itself.  That mode is always the same
        !           286:      on a given target machine (it is `Pmode', which normally is `SImode'),
        !           287:      so there is no point in mentioning it; thus, no machine mode is
        !           288:      written in the `address' expression.  If some day support is added for
        !           289:      machines in which addresses of different kinds of objects appear
        !           290:      differently or are used differently (such as the PDP-10), different
        !           291:      formats would perhaps need different machine modes and these modes
        !           292:      might be written in the `address' expression.
        !           293: 
        !           294: 
        !           295: File: internals,  Node: Output Template,  Next: Output Statement,  Prev: RTL Template,  Up: Machine Desc
        !           296: 
        !           297: Output Templates and Operand Substitution
        !           298: =========================================
        !           299: 
        !           300: The "output template" is a string which specifies how to output the
        !           301: assembler code for an instruction pattern.  Most of the template is a fixed
        !           302: string which is output literally.  The character `%' is used to specify
        !           303: where to substitute an operand; it can also be used to identify places
        !           304: different variants of the assembler require different syntax.
        !           305: 
        !           306: In the simplest case, a `%' followed by a digit N says to output operand N
        !           307: at that point in the string.
        !           308: 
        !           309: `%' followed by a letter and a digit says to output an operand in an
        !           310: alternate fashion.  Four letters have standard, built-in meanings described
        !           311: below.  The machine description macro `PRINT_OPERAND' can define additional
        !           312: letters with nonstandard meanings.
        !           313: 
        !           314: `%cDIGIT' can be used to substitute an operand that is a constant value
        !           315: without the syntax that normally indicates an immediate operand.
        !           316: 
        !           317: `%nDIGIT' is like `%cDIGIT' except that the value of the constant is
        !           318: negated before printing.
        !           319: 
        !           320: `%aDIGIT' can be used to substitute an operand as if it were a memory
        !           321: reference, with the actual operand treated as the address.  This may be
        !           322: useful when outputting a ``load address'' instruction, because often the
        !           323: assembler syntax for such an instruction requires you to write the operand
        !           324: as if it were a memory reference.
        !           325: 
        !           326: `%lDIGIT' is used to substitute a `label_ref' into a jump instruction.
        !           327: 
        !           328: `%' followed by a punctuation character specifies a substitution that does
        !           329: not use an operand.  Only one case is standard: `%%' outputs a `%' into the
        !           330: assembler code.  Other nonstandard cases can be defined in the
        !           331: `PRINT_OPERAND' macro.
        !           332: 
        !           333: The template may generate multiple assembler instructions.  Write the text
        !           334: for the instructions, with `\;' between them.
        !           335: 
        !           336: When the RTL contains two operand which are required by constraint to match
        !           337: each other, the output template must refer only to the lower-numbered
        !           338: operand.  Matching operands are not always identical, and the rest of the
        !           339: compiler arranges to put the proper RTL expression for printing into the
        !           340: lower-numbered operand.
        !           341: 
        !           342: One use of nonstandard letters or punctuation following `%' is to
        !           343: distinguish between different assembler languages for the same machine; for
        !           344: example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
        !           345: requires periods in most opcode names, while MIT syntax does not.  For
        !           346: example, the opcode `movel' in MIT syntax is `move.l' in Motorola syntax. 
        !           347: The same file of patterns is used for both kinds of output syntax, but the
        !           348: character sequence `%.' is used in each place where Motorola syntax wants a
        !           349: period.  The `PRINT_OPERAND' macro for Motorola syntax defines the sequence
        !           350: to output a period; the macro for MIT syntax defines it to do nothing.
        !           351: 
        !           352: 
        !           353: File: internals,  Node: Output Statement,  Next: Constraints,  Prev: Output Template,  Up: Machine Desc
        !           354: 
        !           355: C Statements for Generating Assembler Output
        !           356: ============================================
        !           357: 
        !           358: Often a single fixed template string cannot produce correct and efficient
        !           359: assembler code for all the cases that are recognized by a single
        !           360: instruction pattern.  For example, the opcodes may depend on the kinds of
        !           361: operands; or some unfortunate combinations of operands may require extra
        !           362: machine instructions.
        !           363: 
        !           364: If the output control string starts with a `*', then it is not an output
        !           365: template but rather a piece of C program that should compute a template. 
        !           366: It should execute a `return' statement to return the template-string you
        !           367: want.  Most such templates use C string literals, which require doublequote
        !           368: characters to delimit them.  To include these doublequote characters in the
        !           369: string, prefix each one with `\'.
        !           370: 
        !           371: The operands may be found in the array `operands', whose C data type is
        !           372: `rtx []'.
        !           373: 
        !           374: It is possible to output an assembler instruction and then go on to output
        !           375: or compute more of them, using the subroutine `output_asm_insn'.  This
        !           376: receives two arguments: a template-string and a vector of operands.  The
        !           377: vector may be `operands', or it may be another array of `rtx' that you
        !           378: declare locally and initialize yourself.
        !           379: 
        !           380: When an insn pattern has multiple alternatives in its constraints, often
        !           381: the appearance of the assembler code determined mostly by which alternative
        !           382: was matched.  When this is so, the C code can test the variable
        !           383: `which_alternative', which is the ordinal number of the alternative that
        !           384: was actually satisfied (0 for the first, 1 for the second alternative, etc.).
        !           385: 
        !           386: For example, suppose there are two opcodes for storing zero, `clrreg' for
        !           387: registers and `clrmem' for memory locations.  Here is how a pattern could
        !           388: use `which_alternative' to choose between them:
        !           389: 
        !           390:      (define_insn ""
        !           391:        [(set (match_operand:SI 0 "general_operand" "r,m")
        !           392:              (const_int 0))]
        !           393:        ""
        !           394:        "*
        !           395:        return (which_alternative == 0
        !           396:                ? \"clrreg %0\" : \"clrmem %0\");
        !           397:        ")
        !           398: 
        !           399: 
        !           400: 
        !           401: File: internals,  Node: Constraints,  Next: Standard Names,  Prev: Output Statement,  Up: Machine Desc
        !           402: 
        !           403: Operand Constraints
        !           404: ===================
        !           405: 
        !           406: Each `match_operand' in an instruction pattern can specify a constraint for
        !           407: the type of operands allowed.  Constraints can say whether an operand may
        !           408: be in a register, and which kinds of register; whether the operand can be a
        !           409: memory reference, and which kinds of address; whether the operand may be an
        !           410: immediate constant, and which possible values it may have.  Constraints can
        !           411: also require two operands to match.
        !           412: 
        !           413: 
        !           414: * Menu:
        !           415: 
        !           416: * Simple Constraints::  Basic use of constraints.
        !           417: * Multi-Alternative::   When an insn has two alternative constraint-patterns.
        !           418: * Class Preferences::   Constraints guide which hard register to put things in.
        !           419: * Modifiers::           More precise control over effects of constraints.
        !           420: * No Constraints::      Describing a clean machine without constraints.
        !           421: 
        !           422: 
        !           423: 
        !           424: File: internals,  Node: Simple Constraints,  Next: Multi-Alternative,  Prev: Constraints,  Up: Constraints
        !           425: 
        !           426: Simple Constraints
        !           427: ------------------
        !           428: 
        !           429: The simplest kind of constraint is a string full of letters, each of which
        !           430: describes one kind of operand that is permitted.  Here are the letters that
        !           431: are allowed:
        !           432: 
        !           433: `m'
        !           434:      A memory operand is allowed, with any kind of address that the machine
        !           435:      supports in general.
        !           436: 
        !           437: `o'
        !           438:      A memory operand is allowed, but only if the address is "offsetable". 
        !           439:      This means that adding a small integer (actually, the width in bytes
        !           440:      of the operand, as determined by its machine mode) may be added to the
        !           441:      address and the result is also a valid memory address.
        !           442: 
        !           443:      For example, an address which is constant is offsetable; so is an
        !           444:      address that is the sum of a register and a constant (as long as a
        !           445:      slightly larger constant is also within the range of address-offsets
        !           446:      supported by the machine); but an autoincrement or autodecrement
        !           447:      address is not offsetable.  More complicated indirect/indexed
        !           448:      addresses may or may not be offsetable depending on the other
        !           449:      addressing modes that the machine supports.
        !           450: 
        !           451:      Note that in an output operand which can be matched by another
        !           452:      operand, the constraint letter `o' is valid only when accompanied by
        !           453:      both `<' (if the target machine has predecrement addressing) and `>'
        !           454:      (if the target machine has preincrement addressing).
        !           455: 
        !           456: `<'
        !           457:      A memory operand with autodecrement addressing (either predecrement or
        !           458:      postdecrement) is allowed.
        !           459: 
        !           460: `>'
        !           461:      A memory operand with autoincrement addressing (either preincrement or
        !           462:      postincrement) is allowed.
        !           463: 
        !           464: `r'
        !           465:      A register operand is allowed provided that it is in a general register.
        !           466: 
        !           467: `d', `a', `f', ...
        !           468:       Other letters can be defined in machine-dependent fashion to stand for
        !           469:      particular classes of registers.  `d', `a' and `f' are defined on the
        !           470:      68000/68020 to stand for data, address and floating point registers.
        !           471: 
        !           472: `i'
        !           473:      An immediate integer operand (one with constant value) is allowed. 
        !           474:      This includes symbolic constants whose values will be known only at
        !           475:      assembly time.
        !           476: 
        !           477: `n'
        !           478:      An immediate integer operand with a known numeric value is allowed. 
        !           479:      Many systems cannot support assembly-time constants for operands less
        !           480:      than a word wide.  Constraints for these operands should use `n'
        !           481:      rather than `i'.
        !           482: 
        !           483: `I', `J', `K', ...
        !           484:       Other letters in the range `I' through `M' may be defined in a
        !           485:      machine-dependent fashion to permit immediate integer operands with
        !           486:      explicit integer values in specified ranges.  For example, on the
        !           487:      68000, `I' is defined to stand for the range of values 1 to 8.  This
        !           488:      is the range permitted as a shift count in the shift instructions.
        !           489: 
        !           490: `F'
        !           491:      An immediate floating operand (expression code `const_double') is
        !           492:      allowed.
        !           493: 
        !           494: `G', `H'
        !           495:      `G' and `H' may be defined in a machine-dependent fashion to permit
        !           496:      immediate floating operands in particular ranges of values.
        !           497: 
        !           498: `s'
        !           499:      An immediate integer operand whose value is not an explicit integer is
        !           500:      allowed.
        !           501: 
        !           502:      This might appear strange; if an insn allows a constant operand with a
        !           503:      value not known at compile time, it certainly must allow any known
        !           504:      value.  So why use `s' instead of `i'?  Sometimes it allows better
        !           505:      code to be generated.
        !           506: 
        !           507:      For example, on the 68000 in a fullword instruction it is possible to
        !           508:      use an immediate operand; but if the immediate value is between -32
        !           509:      and 31, better code results from loading the value into a register and
        !           510:      using the register.  This is because the load into the register can be
        !           511:      done with a `moveq' instruction.  We arrange for this to happen by
        !           512:      defining the letter `K' to mean ``any integer outside the range -32 to
        !           513:      31'', and then specifying `Ks' in the operand constraints.
        !           514: 
        !           515: `g'
        !           516:      Any register, memory or immediate integer operand is allowed, except
        !           517:      for registers that are not general registers.
        !           518: 
        !           519: `N' (a digit)
        !           520:      An operand that matches operand number N is allowed.  If a digit is
        !           521:      used together with letters, the digit should come last.
        !           522: 
        !           523:      This is called a "matching constraint" and what it really means is
        !           524:      that the assembler has only a single operand that fills two roles
        !           525:      considered separate in the RTL insn.  For example, an add insn has two
        !           526:      input operands and one output operand in the RTL, but on most machines
        !           527:      an add instruction really has only two operands, one of them an
        !           528:      input-output operand.
        !           529: 
        !           530:      Matching constraints work only in circumstances like that add insn. 
        !           531:      More precisely, the matching constraint must appear in an input-only
        !           532:      operand and the operand that it matches must be an output-only operand
        !           533:      with a lower number.
        !           534: 
        !           535:      For operands to match in a particular case usually means that they are
        !           536:      identical-looking RTL expressions.  But in a few special cases
        !           537:      specific kinds of dissimilarity are allowed.  For example, `*x' as an
        !           538:      input operand will match `*x++' as an output operand.  For proper
        !           539:      results in such cases, the output template should always use the
        !           540:      output-operand's number when printing the operand.
        !           541: 
        !           542: `p'
        !           543:      An operand that is a valid memory address is allowed.  This is for
        !           544:      ``load address'' and ``push address'' instructions.
        !           545: 
        !           546:      If `p' is used in the constraint, the test-function in the
        !           547:      `match_operand' must be `address_operand'.
        !           548: 
        !           549: In order to have valid assembler code, each operand must satisfy its
        !           550: constraint.  But a failure to do so does not prevent the pattern from
        !           551: applying to an insn.  Instead, it directs the compiler to modify the code
        !           552: so that the constraint will be satisfied.  Usually this is done by copying
        !           553: an operand into a register.
        !           554: 
        !           555: Contrast, therefore, the two instruction patterns that follow:
        !           556: 
        !           557:      (define_insn ""
        !           558:        [(set (match_operand:SI 0 "general_operand" "r")
        !           559:              (plus:SI (match_dup 0)
        !           560:                       (match_operand:SI 1 "general_operand" "r")))]
        !           561:        ""
        !           562:        "...")
        !           563: 
        !           564: 
        !           565: which has two operands, one of which must appear in two places, and
        !           566: 
        !           567:      (define_insn ""
        !           568:        [(set (match_operand:SI 0 "general_operand" "r")
        !           569:              (plus:SI (match_operand:SI 1 "general_operand" "0")
        !           570:                       (match_operand:SI 2 "general_operand" "r")))]
        !           571:        ""
        !           572:        "...")
        !           573: 
        !           574: 
        !           575: which has three operands, two of which are required by a constraint to be
        !           576: identical.  If we are considering an insn of the form
        !           577: 
        !           578:      (insn N PREV NEXT
        !           579:        (set (reg:SI 3)
        !           580:             (plus:SI (reg:SI 6) (reg:SI 109)))
        !           581:        ...)
        !           582: 
        !           583: 
        !           584: the first pattern would not apply at all, because this insn does not
        !           585: contain two identical subexpressions in the right place.  The pattern would
        !           586: say, ``That does not look like an add instruction; try other patterns.''
        !           587: The second pattern would say, ``Yes, that's an add instruction, but there
        !           588: is something wrong with it.''  It would direct the reload pass of the
        !           589: compiler to generate additional insns to make the constraint true.  The
        !           590: results might look like this:
        !           591: 
        !           592:      (insn N2 PREV N
        !           593:        (set (reg:SI 3) (reg:SI 6))
        !           594:        ...)
        !           595:      
        !           596:      (insn N N2 NEXT
        !           597:        (set (reg:SI 3)
        !           598:             (plus:SI (reg:SI 3) (reg:SI 109)))
        !           599:        ...)
        !           600: 
        !           601: 
        !           602: Because insns that don't fit the constraints are fixed up by loading
        !           603: operands into registers, every instruction pattern's constraints must
        !           604: permit the case where all the operands are in registers.  It need not
        !           605: permit all classes of registers; the compiler knows how to copy registers
        !           606: into other registers of the proper class in order to make an instruction
        !           607: valid.  But if no registers are permitted, the compiler will be stymied: it
        !           608: does not know how to save a register in memory in order to make an
        !           609: instruction valid.  Instruction patterns that reject registers can be made
        !           610: valid by attaching a condition-expression that refuses to match an insn at
        !           611: all if the crucial operand is a register.
        !           612: 
        !           613: 
        !           614: File: internals,  Node: Multi-Alternative,  Next: Class Preferences,  Prev: Simple Constraints,  Up: Constraints
        !           615: 
        !           616: Multiple Alternative Constraints
        !           617: --------------------------------
        !           618: 
        !           619: Sometimes a single instruction has multiple alternative sets of possible
        !           620: operands.  For example, on the 68000, a logical-or instruction can combine
        !           621: register or an immediate value into memory, or it can combine any kind of
        !           622: operand into a register; but it cannot combine one memory location into
        !           623: another.
        !           624: 
        !           625: These constraints are represented as multiple alternatives.  An alternative
        !           626: can be described by a series of letters for each operand.  The overall
        !           627: constraint for an operand is made from the letters for this operand from
        !           628: the first alternative, a comma, the letters for this operand from the
        !           629: second alternative, a comma, and so on until the last alternative.  Here is
        !           630: how it is done for fullword logical-or on the 68000:
        !           631: 
        !           632:      (define_insn "iorsi3"
        !           633:        [(set (match_operand:SI 0 "general_operand" "=%m,d")
        !           634:              (ior:SI (match_operand:SI 1 "general_operand" "0,0")
        !           635:                      (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
        !           636:        ...)
        !           637: 
        !           638: 
        !           639: The first alternative has `m' (memory) for operand 0, `0' for operand 1
        !           640: (meaning it must match operand 0), and `dKs' for operand 2.  The second
        !           641: alternative has `d' (data register) for operand 0, `0' for operand 1, and
        !           642: `dmKs' for operand 2.  The `=' and `%' in the constraint for operand 0 are
        !           643: not part of any alternative; their meaning is explained in the next section.
        !           644: 
        !           645: If all the operands fit any one alternative, the instruction is valid. 
        !           646: Otherwise, for each alternative, the compiler counts how many instructions
        !           647: must be added to copy the operands so that that alternative applies.  The
        !           648: alternative requiring the least copying is chosen.  If two alternatives
        !           649: need the same amount of copying, the one that comes first is chosen.  These
        !           650: choices can be altered with the `?' and `!' characters:
        !           651: 
        !           652: `?'
        !           653:      Disparage slightly the alternative that the `?' appears in, as a
        !           654:      choice when no alternative applies exactly.  The compiler regards this
        !           655:      alternative as one unit more costly for each `?' that appears in it.
        !           656: 
        !           657: `!'
        !           658:      Disparage severely the alternative that the `!' appears in.  When
        !           659:      operands must be copied into registers, the compiler will never choose
        !           660:      this alternative as the one to strive for.
        !           661: 
        !           662: When an insn pattern has multiple alternatives in its constraints, often
        !           663: the appearance of the assembler code determined mostly by which alternative
        !           664: was matched.  When this is so, the C code for writing the assembler code
        !           665: can use the variable `which_alternative', which is the ordinal number of
        !           666: the alternative that was actually satisfied (0 for the first, 1 for the
        !           667: second alternative, etc.).  For example:
        !           668: 
        !           669:      (define_insn ""
        !           670:        [(set (match_operand:SI 0 "general_operand" "r,m")
        !           671:              (const_int 0))]
        !           672:        ""
        !           673:        "*
        !           674:        return (which_alternative == 0
        !           675:                ? \"clrreg %0\" : \"clrmem %0\");
        !           676:        ")
        !           677: 
        !           678: 
        !           679: 
        !           680: File: internals,  Node: Class Preferences,  Next: Modifiers,  Prev: Multi-Alternative,  Up: Constraints
        !           681: 
        !           682: Register Class Preferences
        !           683: --------------------------
        !           684: 
        !           685: The operand constraints have another function: they enable the compiler to
        !           686: decide which kind of hardware register a pseudo register is best allocated
        !           687: to.  The compiler examines the constraints that apply to the insns that use
        !           688: the pseudo register, looking for the machine-dependent letters such as `d'
        !           689: and `a' that specify classes of registers.  The pseudo register is put in
        !           690: whichever class gets the most ``votes''.  The constraint letters `g' and
        !           691: `r' also vote: they vote in favor of a general register.  The machine
        !           692: description says which registers are considered general.
        !           693: 
        !           694: Of course, on some machines all registers are equivalent, and no register
        !           695: classes are defined.  Then none of this complexity is relevant.
        !           696: 
        !           697: 
        !           698: File: internals,  Node: Modifiers,  Next: No Constraints,  Prev: Class Preferences,  Up: Constraints
        !           699: 
        !           700: Constraint Modifier Characters
        !           701: ------------------------------
        !           702: 
        !           703: `='
        !           704:      Means that this operand is write-only for this instruction: the
        !           705:      previous value is discarded and replaced by output data.
        !           706: 
        !           707: `+'
        !           708:      Means that this operand is both read and written by the instruction.
        !           709: 
        !           710:      When the compiler fixes up the operands to satisfy the constraints, it
        !           711:      needs to know which operands are inputs to the instruction and which
        !           712:      are outputs from it.  `=' identifies an output; `+' identifies an
        !           713:      operand that is both input and output; all other operands are assumed
        !           714:      to be input only.
        !           715: 
        !           716: `&'
        !           717:      Means (in a particular alternative) that this operand is written
        !           718:      before the instruction is finished using the input operands. 
        !           719:      Therefore, this operand may not lie in a register that is used as an
        !           720:      input operand or as part of any memory address.
        !           721: 
        !           722:      `&' applies only to the alternative in which it is written.  In
        !           723:      constraints with multiple alternatives, sometimes one alternative
        !           724:      requires `&' while others do not.  See, for example, the `movdf' insn
        !           725:      of the 68000.
        !           726: 
        !           727:      `&' does not obviate the need to write `='.
        !           728: 
        !           729: `%'
        !           730:      Declares the instruction to be commutative for this operand and the
        !           731:      following operand.  This means that the compiler may interchange the
        !           732:      two operands if that is the cheapest way to make all operands fit the
        !           733:      constraints.  This is often used in patterns for addition instructions
        !           734:      that really have only two operands: the result must go in one of the
        !           735:      arguments.  Here for example, is how the 68000 halfword-add
        !           736:      instruction is defined:
        !           737: 
        !           738:           (define_insn "addhi3"
        !           739:             [(set (match_operand:HI 0 "general_operand" "=m,r")
        !           740:                (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
        !           741:                         (match_operand:HI 2 "general_operand" "di,g")))]
        !           742:             ...)
        !           743: 
        !           744: 
        !           745:      Note that in previous versions of GNU CC the `%' constraint modifier
        !           746:      always applied to operands 1 and 2 regardless of which operand it was
        !           747:      written in.  The usual custom was to write it in operand 0.  Now it
        !           748:      must be in operand 1 if the operands to be exchanged are 1 and 2.
        !           749: 
        !           750: `#'
        !           751:      Says that all following characters, up to the next comma, are to be
        !           752:      ignored as a constraint.  They are significant only for choosing
        !           753:      register preferences.
        !           754: 
        !           755: `*'
        !           756:      Says that the following character should be ignored when choosing
        !           757:      register preferences.  `*' has no effect on the meaning of the
        !           758:      constraint as a constraint.
        !           759: 
        !           760:      Here is an example: the 68000 has an instruction to sign-extend a
        !           761:      halfword in a data register, and can also sign-extend a value by
        !           762:      copying it into an address register.  While either kind of register is
        !           763:      acceptable, the constraints on an address-register destination are
        !           764:      less strict, so it is best if register allocation makes an address
        !           765:      register its goal.  Therefore, `*' is used so that the `d' constraint
        !           766:      letter (for data register) is ignored when computing register
        !           767:      preferences.
        !           768: 
        !           769:           (define_insn "extendhisi2"
        !           770:             [(set (match_operand:SI 0 "general_operand" "=*d,a")
        !           771:                   (sign_extend:SI
        !           772:                    (match_operand:HI 1 "general_operand" "0,g")))]
        !           773:             ...)
        !           774: 
        !           775: 
        !           776: 
        !           777: File: internals,  Node: No Constraints,  Prev: Modifiers,  Up: Constraints
        !           778: 
        !           779: Not Using Constraints
        !           780: ---------------------
        !           781: 
        !           782: Some machines are so clean that operand constraints are not required.  For
        !           783: example, on the Vax, an operand valid in one context is valid in any other
        !           784: context.  On such a machine, every operand constraint would be `g',
        !           785: excepting only operands of ``load address'' instructions which are written
        !           786: as if they referred to a memory location's contents but actual refer to its
        !           787: address.  They would have constraint `p'.
        !           788: 
        !           789: For such machines, instead of writing `g' and `p' for all the constraints,
        !           790: you can choose to write a description with empty constraints.  Then you
        !           791: write `""' for the constraint in every `match_operand'.  Address operands
        !           792: are identified by writing an `address' expression around the
        !           793: `match_operand', not by their constraints.
        !           794: 
        !           795: When the machine description has just empty constraints, certain parts of
        !           796: compilation are skipped, making the compiler faster.
        !           797: 
        !           798: 
        !           799: File: internals,  Node: Standard Names,  Next: Pattern Ordering,  Prev: Constraints,  Up: Machine Desc
        !           800: 
        !           801: Standard Names for Patterns Used in Generation
        !           802: ==============================================
        !           803: 
        !           804: Here is a table of the instruction names that are meaningful in the RTL
        !           805: generation pass of the compiler.  Giving one of these names to an
        !           806: instruction pattern tells the RTL generation pass that it can use the
        !           807: pattern in to accomplish a certain task.
        !           808: 
        !           809: `movM'
        !           810:      Here M is a two-letter machine mode name, in lower case.  This
        !           811:      instruction pattern moves data with that machine mode from operand 1
        !           812:      to operand 0.  For example, `movsi' moves full-word data.
        !           813: 
        !           814:      If operand 0 is a `subreg' with mode M of a register whose natural
        !           815:      mode is wider than M, the effect of this instruction is to store the
        !           816:      specified value in the part of the register that corresponds to mode
        !           817:      M.  The effect on the rest of the register is undefined.
        !           818: 
        !           819: `movstrictM'
        !           820:      Like `movM' except that if operand 0 is a `subreg' with mode M of a
        !           821:      register whose natural mode is wider, the `movstrictM' instruction is
        !           822:      guaranteed not to alter any of the register except the part which
        !           823:      belongs to mode M.
        !           824: 
        !           825: `addM3'
        !           826:      Add operand 2 and operand 1, storing the result in operand 0.  All
        !           827:      operands must have mode M.  This can be used even on two-address
        !           828:      machines, by means of constraints requiring operands 1 and 0 to be the
        !           829:      same location.
        !           830: 
        !           831: `subM3', `mulM3', `umulM3', `divM3', `udivM3', `modM3', `umodM3', `andM3', `iorM3', `xorM3'
        !           832:      Similar, for other arithmetic operations.
        !           833: 
        !           834: `andcbM3'
        !           835:      Bitwise logical-and operand 1 with the complement of operand 2 and
        !           836:      store the result in operand 0.
        !           837: 
        !           838: `mulhisi3'
        !           839:      Multiply operands 1 and 2, which have mode `HImode', and store a
        !           840:      `SImode' product in operand 0.
        !           841: 
        !           842: `mulqihi3', `mulsidi3'
        !           843:      Similar widening-multiplication instructions of other widths.
        !           844: 
        !           845: `umulqihi3', `umulhisi3', `umulsidi3'
        !           846:      Similar widening-multiplication instructions that do unsigned
        !           847:      multiplication.
        !           848: 
        !           849: `divmodM4'
        !           850:      Signed division that produces both a quotient and a remainder. 
        !           851:      Operand 1 is divided by operand 2 to produce a quotient stored in
        !           852:      operand 0 and a remainder stored in operand 3.
        !           853: 
        !           854: `udivmodM4'
        !           855:      Similar, but does unsigned division.
        !           856: 
        !           857: `divmodMN4'
        !           858:      Like `divmodM4' except that only the dividend has mode M; the divisor,
        !           859:      quotient and remainder have mode N.  For example, the Vax has a
        !           860:      `divmoddisi4' instruction (but it is omitted from the machine
        !           861:      description, because it is so slow that it is faster to compute
        !           862:      remainders by the circumlocution that the compiler will use if this
        !           863:      instruction is not available).
        !           864: 
        !           865: `ashlM3'
        !           866:      Arithmetic-shift operand 1 left by a number of bits specified by
        !           867:      operand 2, and store the result in operand 0.  Operand 2 has mode
        !           868:      `SImode', not mode M.
        !           869: 
        !           870: `ashrM3', `lshlM3', `lshrM3', `rotlM3', `rotrM3'
        !           871:      Other shift and rotate instructions.
        !           872: 
        !           873:      Logical and arithmetic left shift are the same.  Machines that do not
        !           874:      allow negative shift counts often have only one instruction for
        !           875:      shifting left.  On such machines, you should define a pattern named
        !           876:      `ashlM3' and leave `lshlM3' undefined.
        !           877: 
        !           878: `negM2'
        !           879:      Negate operand 1 and store the result in operand 0.
        !           880: 
        !           881: `absM2'
        !           882:      Store the absolute value of operand 1 into operand 0.
        !           883: 
        !           884: `sqrtM2'
        !           885:      Store the square root of operand 1 into operand 0.
        !           886: 
        !           887: `ffsM2'
        !           888:      Store into operand 0 one plus the index of the least significant 1-bit
        !           889:      of operand 1.  If operand 1 is zero, store zero.  M is the mode of
        !           890:      operand 0; operand 1's mode is specified by the instruction pattern,
        !           891:      and the compiler will convert the operand to that mode before
        !           892:      generating the instruction.
        !           893: 
        !           894: `one_cmplM2'
        !           895:      Store the bitwise-complement of operand 1 into operand 0.
        !           896: 
        !           897: `cmpM'
        !           898:      Compare operand 0 and operand 1, and set the condition codes.  The RTL
        !           899:      pattern should look like this:
        !           900: 
        !           901:           (set (cc0) (minus (match_operand:M 0 ...)
        !           902:                             (match_operand:M 1 ...)))
        !           903: 
        !           904: 
        !           905:      Each such definition in the machine description, for integer mode M,
        !           906:      must have a corresponding `tstM' pattern, because optimization can
        !           907:      simplify the compare into a test when operand 1 is zero.
        !           908: 
        !           909: `tstM'
        !           910:      Compare operand 0 against zero, and set the condition codes.  The RTL
        !           911:      pattern should look like this:
        !           912: 
        !           913:           (set (cc0) (match_operand:M 0 ...))
        !           914: 
        !           915: 
        !           916: `movstrM'
        !           917:      Block move instruction.  The addresses of the destination and source
        !           918:      strings are the first two operands, and both are in mode `Pmode'.  The
        !           919:      number of bytes to move is the third operand, in mode M.
        !           920: 
        !           921: `cmpstrM'
        !           922:      Block compare instruction, with operands like `movstrM' except that
        !           923:      the two memory blocks are compared byte by byte in lexicographic
        !           924:      order.  The effect of the instruction is to set the condition codes.
        !           925: 
        !           926: `floatMN2'
        !           927:      Convert operand 1 (valid for fixed point mode M) to floating point
        !           928:      MODE N and store in operand 0 (which has mode N).
        !           929: 
        !           930: `fixMN2'
        !           931:      Convert operand 1 (valid for floating point mode M) to fixed point
        !           932:      MODE N as a signed number and store in operand 0 (which has mode N). 
        !           933:      This instruction's result is defined only when the value of operand 1
        !           934:      is an integer.
        !           935: 
        !           936: `fixunsMN2'
        !           937:      Convert operand 1 (valid for floating point mode M) to fixed point
        !           938:      MODE N as an unsigned number and store in operand 0 (which has mode
        !           939:      N).  This instruction's result is defined only when the value of
        !           940:      operand 1 is an integer.
        !           941: 
        !           942: `ftruncM2'
        !           943:      Convert operand 1 (valid for floating point mode M) to an integer
        !           944:      value, still represented in floating point mode M, and store it in
        !           945:      operand 0 (valid for floating point mode M).
        !           946: 
        !           947: `fix_truncMN2'
        !           948:      Like `fixMN2' but works for any floating point value of mode M by
        !           949:      converting the value to an integer.
        !           950: 
        !           951: `fixuns_truncMN2'
        !           952:      Like `fixunsMN2' but works for any floating point value of mode M by
        !           953:      converting the value to an integer.
        !           954: 
        !           955: `truncMN'
        !           956:      Truncate operand 1 (valid for mode M) to mode N and store in operand 0
        !           957:      (which has mode N).  Both modes must be fixed point or both floating
        !           958:      point.
        !           959: 
        !           960: `extendMN'
        !           961:      Sign-extend operand 1 (valid for mode M) to mode N and store in
        !           962:      operand 0 (which has mode N).  Both modes must be fixed point or both
        !           963:      floating point.
        !           964: 
        !           965: `zero_extendMN'
        !           966:      Zero-extend operand 1 (valid for mode M) to mode N and store in
        !           967:      operand 0 (which has mode N).  Both modes must be fixed point.
        !           968: 
        !           969: `extv'
        !           970:      Extract a bit-field from operand 1 (a register or memory operand),
        !           971:      where operand 2 specifies the width in bits and operand 3 the starting
        !           972:      bit, and store it in operand 0.  Operand 0 must have `Simode'. 
        !           973:      Operand 1 may have mode `QImode' or `SImode'; often `SImode' is
        !           974:      allowed only for registers.  Operands 2 and 3 must be valid for
        !           975:      `SImode'.
        !           976: 
        !           977:      The RTL generation pass generates this instruction only with constants
        !           978:      for operands 2 and 3.
        !           979: 
        !           980:      The bit-field value is sign-extended to a full word integer before it
        !           981:      is stored in operand 0.
        !           982: 
        !           983: `extzv'
        !           984:      Like `extv' except that the bit-field value is zero-extended.
        !           985: 
        !           986: `insv'
        !           987:      Store operand 3 (which must be valid for `SImode') into a bit-field in
        !           988:      operand 0, where operand 1 specifies the width in bits and operand 2
        !           989:      the starting bit.  Operand 0 may have mode `QImode' or `SImode'; often
        !           990:      `SImode' is allowed only for registers.  Operands 1 and 2 must be
        !           991:      valid for `SImode'.
        !           992: 
        !           993:      The RTL generation pass generates this instruction only with constants
        !           994:      for operands 1 and 2.
        !           995: 
        !           996: `sCOND'
        !           997:      Store zero or nonzero in the operand according to the condition codes.
        !           998:       Value stored is nonzero iff the condition COND is true.  COND is the
        !           999:      name of a comparison operation expression code, such as `eq', `lt' or
        !          1000:      `leu'.
        !          1001: 
        !          1002:      You specify the mode that the operand must have when you write the
        !          1003:      `match_operand' expression.  The compiler automatically sees which
        !          1004:      mode you have used and supplies an operand of that mode.
        !          1005: 
        !          1006:      The value stored for a true condition must have 1 as its low bit. 
        !          1007:      Otherwise the instruction is not suitable and must be omitted from the
        !          1008:      machine description.  You must tell the compiler exactly which value
        !          1009:      is stored by defining the macro `STORE_FLAG_VALUE'.
        !          1010: 
        !          1011: `bCOND'
        !          1012:      Conditional branch instruction.  Operand 0 is a `label_ref' that
        !          1013:      refers to the label to jump to.  Jump if the condition codes meet
        !          1014:      condition COND.
        !          1015: 
        !          1016: `call'
        !          1017:      Subroutine call instruction.  Operand 1 is the number of bytes of
        !          1018:      arguments pushed (in mode `SImode'), and operand 0 is the function to
        !          1019:      call.  Operand 0 should be a `mem' RTX whose address is the address of
        !          1020:      the function.
        !          1021: 
        !          1022: `return'
        !          1023:      Subroutine return instruction.  This instruction pattern name should
        !          1024:      be defined only if a single instruction can do all the work of
        !          1025:      returning from a function.
        !          1026: 
        !          1027: `tablejump'
        !          1028: `caseM'
        !          1029: 
        !          1030: File: internals,  Node: Pattern Ordering,  Next: Dependent Patterns,  Prev: Standard Names,  Up: Machine Desc
        !          1031: 
        !          1032: When the Order of Patterns Matters
        !          1033: ==================================
        !          1034: 
        !          1035: Sometimes an insn can match more than one instruction pattern.  Then the
        !          1036: pattern that appears first in the machine description is the one used. 
        !          1037: Therefore, more specific patterns (patterns that will match fewer things)
        !          1038: and faster instructions (those that will produce better code when they do
        !          1039: match) should usually go first in the description.
        !          1040: 
        !          1041: In some cases the effect of ordering the patterns can be used to hide a
        !          1042: pattern when it is not valid.  For example, the 68000 has an instruction
        !          1043: for converting a fullword to floating point and another for converting a
        !          1044: byte to floating point.  An instruction converting an integer to floating
        !          1045: point could match either one.  We put the pattern to convert the fullword
        !          1046: first to make sure that one will be used rather than the other.  (Otherwise
        !          1047: a large integer might be generated as a single-byte immediate quantity,
        !          1048: which would not work.) Instead of using this pattern ordering it would be
        !          1049: possible to make the pattern for convert-a-byte smart enough to deal
        !          1050: properly with any constant value.
        !          1051: 
        !          1052: 
        !          1053: File: internals,  Node: Dependent Patterns,  Next: Jump Patterns,  Prev: Pattern Ordering,  Up: Machine Desc
        !          1054: 
        !          1055: Interdependence of Patterns
        !          1056: ===========================
        !          1057: 
        !          1058: Every machine description must have a named pattern for each of the
        !          1059: conditional branch names `bCOND'.  The recognition template must always
        !          1060: have the form
        !          1061: 
        !          1062:      (set (pc)
        !          1063:           (if_then_else (COND (cc0) (const_int 0))
        !          1064:                         (label_ref (match_operand 0 "" ""))
        !          1065:                         (pc)))
        !          1066: 
        !          1067: 
        !          1068: In addition, every machine description must have an anonymous pattern for
        !          1069: each of the possible reverse-conditional branches.  These patterns look like
        !          1070: 
        !          1071:      (set (pc)
        !          1072:           (if_then_else (COND (cc0) (const_int 0))
        !          1073:                         (pc)
        !          1074:                         (label_ref (match_operand 0 "" ""))))
        !          1075: 
        !          1076: 
        !          1077: They are necessary because jump optimization can turn direct-conditional
        !          1078: branches into reverse-conditional branches.
        !          1079: 
        !          1080: The compiler does more with RTL than just create it from patterns and
        !          1081: recognize the patterns: it can perform arithmetic expression codes when
        !          1082: constant values for their operands can be determined.  As a result,
        !          1083: sometimes having one pattern can require other patterns.  For example, the
        !          1084: Vax has no `and' instruction, but it has `and not' instructions.  Here is
        !          1085: the definition of one of them:
        !          1086: 
        !          1087:      (define_insn "andcbsi2"
        !          1088:        [(set (match_operand:SI 0 "general_operand" "")
        !          1089:              (and:SI (match_dup 0)
        !          1090:                      (not:SI (match_operand:SI
        !          1091:                                1 "general_operand" ""))))]
        !          1092:        ""
        !          1093:        "bicl2 %1,%0")
        !          1094: 
        !          1095: 
        !          1096: If operand 1 is an explicit integer constant, an instruction constructed
        !          1097: using that pattern can be simplified into an `and' like this:
        !          1098: 
        !          1099:      (set (reg:SI 41)
        !          1100:           (and:SI (reg:SI 41)
        !          1101:                   (const_int 0xffff7fff)))
        !          1102: 
        !          1103: 
        !          1104: (where the integer constant is the one's complement of what appeared in the
        !          1105: original instruction).
        !          1106: 
        !          1107: To avoid a fatal error, the compiler must have a pattern that recognizes
        !          1108: such an instruction.  Here is what is used:
        !          1109: 
        !          1110:      (define_insn ""
        !          1111:        [(set (match_operand:SI 0 "general_operand" "")
        !          1112:              (and:SI (match_dup 0)
        !          1113:                      (match_operand:SI 1 "general_operand" "")))]
        !          1114:        "GET_CODE (operands[1]) == CONST_INT"
        !          1115:        "*
        !          1116:      { operands[1]
        !          1117:          = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
        !          1118:        return \"bicl2 %1,%0\";
        !          1119:      }")
        !          1120: 
        !          1121: 
        !          1122: Whereas a pattern to match a general `and' instruction is impossible to
        !          1123: support on the Vax, this pattern is possible because it matches only a
        !          1124: constant second argument: a special case that can be output as an `and not'
        !          1125: instruction.
        !          1126: 
        !          1127: A ``compare'' instruction whose RTL looks like this:
        !          1128: 
        !          1129:      (set (cc0) (minus OPERAND (const_int 0)))
        !          1130: 
        !          1131: 
        !          1132: may be simplified by optimization into a ``test'' like this:
        !          1133: 
        !          1134:      (set (cc0) OPERAND)
        !          1135: 
        !          1136: 
        !          1137: So in the machine description, each ``compare'' pattern for an integer mode
        !          1138: must have a corresponding ``test'' pattern that will match the result of
        !          1139: such simplification.
        !          1140: 
        !          1141: In some cases machines support instructions identical except for the
        !          1142: machine mode of one or more operands.  For example, there may be
        !          1143: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
        !          1144: patterns are
        !          1145: 
        !          1146:      (set (match_operand:SI 0 ...)
        !          1147:           (extend:SI (match_operand:HI 1 ...)))
        !          1148:      
        !          1149:      (set (match_operand:SI 0 ...)
        !          1150:           (extend:SI (match_operand:QI 1 ...)))
        !          1151: 
        !          1152: 
        !          1153: Constant integers do not specify a machine mode, so an instruction to
        !          1154: extend a constant value could match either pattern.  The pattern it
        !          1155: actually will match is the one that appears first in the file.  For correct
        !          1156: results, this must be the one for the widest possible mode (`HImode',
        !          1157: here).  If the pattern matches the `QImode' instruction, the results will
        !          1158: be incorrect if the constant value does not actually fit that mode.
        !          1159: 
        !          1160: Such instructions to extend constants are rarely generated because they are
        !          1161: optimized away, but they do occasionally happen in nonoptimized compilations.
        !          1162: 
        !          1163: 
        !          1164: File: internals,  Node: Jump Patterns,  Next: Peephole Definitions,  Prev: Dependent Patterns,  Up: Machine Desc
        !          1165: 
        !          1166: Defining Jump Instruction Patterns
        !          1167: ==================================
        !          1168: 
        !          1169: GNU CC assumes that the machine has a condition code.  A comparison insn
        !          1170: sets the condition code, recording the results of both signed and unsigned
        !          1171: comparison of the given operands.  A separate branch insn tests the
        !          1172: condition code and branches or not according its value.  The branch insns
        !          1173: come in distinct signed and unsigned flavors.  Many common machines, such
        !          1174: as the Vax, the 68000 and the 32000, work this way.
        !          1175: 
        !          1176: Some machines have distinct signed and unsigned compare instructions, and
        !          1177: only one set of conditional branch instructions.  The easiest way to handle
        !          1178: these machines is to treat them just like the others until the final stage
        !          1179: where assembly code is written.  At this time, when outputting code for the
        !          1180: compare instruction, peek ahead at the following branch using `NEXT_INSN
        !          1181: (insn)'.  (The variable `insn' refers to the insn being output, in the
        !          1182: output-writing code in an instruction pattern.)  If the RTL says that is an
        !          1183: unsigned branch, output an unsigned compare; otherwise output a signed
        !          1184: compare.  When the branch itself is output, you can treat signed and
        !          1185: unsigned branches identically.
        !          1186: 
        !          1187: The reason you can do this is that GNU CC always generates a pair of
        !          1188: consecutive RTL insns, one to set the condition code and one to test it,
        !          1189: and keeps the pair inviolate until the end.
        !          1190: 
        !          1191: To go with this technique, you must define the machine-description macro
        !          1192: `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no compare
        !          1193: instruction is superfluous.
        !          1194: 
        !          1195: Some machines have compare-and-branch instructions and no condition code. 
        !          1196: A similar technique works for them.  When it is time to ``output'' a
        !          1197: compare instruction, record its operands in two static variables.  When
        !          1198: outputting the branch-on-condition-code instruction that follows, actually
        !          1199: output a compare-and-branch instruction that uses the remembered operands.
        !          1200: 
        !          1201: It also works to define patterns for compare-and-branch instructions.  In
        !          1202: optimizing compilation, the pair of compare and branch instructions will be
        !          1203: combined accoprding to these patterns.  But this does not happen if
        !          1204: optimization is not requested.  So you must use one of the solutions above
        !          1205: in addition to any special patterns you define.
        !          1206: 
        !          1207: 

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