Return to internals-3 CVS log

Up to [GCC 1.x] / gcc

Annotation of gcc/internals-3, revision 1.1.1.2

1.1.1.2 ! root        1: Info file internals, produced by Makeinfo, -*- Text -*-
        !             2: from input file internals.texinfo.
        !             3: 
1.1       root        4: 
                      5: 
                      6: This file documents the internals of the GNU compiler.
                      7: 
1.1.1.2 ! root        8: Copyright (C) 1988 Free Software Foundation, Inc.
1.1       root        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
1.1.1.2 ! root       16: section entitled ``GNU CC General Public License'' is included exactly as
1.1       root       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,
1.1.1.2 ! root       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: 
1.1       root       29: 
                     30: 
1.1.1.2 ! root       31: File: internals,  Node: Accessors,  Next: Flags,  Prev: RTL Objects,  Up: RTL
1.1       root       32: 
1.1.1.2 ! root       33: Access to Operands
        !            34: ==================
        !            35: 
        !            36: For each expression type `rtl.def' specifies the number of contained
        !            37: objects and their kinds, with four possibilities: `e' for expression
        !            38: (actually a pointer to an expression), `i' for integer, `s' for string, and
        !            39: `E' for vector of expressions.  The sequence of letters for an expression
        !            40: code is called its "format".  Thus, the format of `subreg' is `ei'.
        !            41: 
        !            42: Two other format characters are used occasionally: `u' and `0'.  `u' is
        !            43: equivalent to `e' except that it is printed differently in debugging dumps,
        !            44: and `0' means a slot whose contents do not fit any normal category.  `0'
        !            45: slots are not printed at all in dumps, and are often used in special ways
        !            46: by small parts of the compiler.
        !            47: 
        !            48: There are macros to get the number of operands and the format of an
        !            49: expression code:
        !            50: 
        !            51: `GET_RTX_LENGTH (CODE)'
        !            52:      Number of operands of an RTX of code CODE.
        !            53: 
        !            54: `GET_RTX_FORMAT (CODE)'
        !            55:      The format of an RTX of code CODE, as a C string.
        !            56: 
        !            57: Operands of expressions are accessed using the macros `XEXP', `XINT' and
        !            58: `XSTR'.  Each of these macros takes two arguments: an expression-pointer
        !            59: (RTX) and an operand number (counting from zero).  Thus,
        !            60: 
        !            61:      XEXP (X, 2)
        !            62: 
        !            63: 
        !            64: accesses operand 2 of expression X, as an expression.
        !            65: 
        !            66:      XINT (X, 2)
1.1       root       67: 
1.1.1.2 ! root       68: 
        !            69: accesses the same operand as an integer.  `XSTR', used in the same fashion,
        !            70: would access it as a string.
        !            71: 
        !            72: Any operand can be accessed as an integer, as an expression or as a string.
        !            73:  You must choose the correct method of access for the kind of value
        !            74: actually stored in the operand.  You would do this based on the expression
        !            75: code of the containing expression.  That is also how you would know how
        !            76: many operands there are.
        !            77: 
        !            78: For example, if X is a `subreg' expression, you know that it has two
        !            79: operands which can be correctly accessed as `XEXP (X, 0)' and `XINT (X,
        !            80: 1)'.  If you did `XINT (X, 0)', you would get the address of the expression
        !            81: operand but cast as an integer; that might occasionally be useful, but it
        !            82: would be cleaner to write `(int) XEXP (X, 0)'.  `XEXP (X, 1)' would also
        !            83: compile without error, and would return the second, integer operand cast as
        !            84: an expression pointer, which would probably result in a crash when
        !            85: accessed.  Nothing stops you from writing `XEXP (X, 28)' either, but this
        !            86: will access memory past the end of the expression with unpredictable results.
        !            87: 
        !            88: Access to operands which are vectors is more complicated.  You can use the
        !            89: macro `XVEC' to get the vector-pointer itself, or the macros `XVECEXP' and
        !            90: `XVECLEN' to access the elements and length of a vector.
        !            91: 
        !            92: `XVEC (EXP, IDX)'
        !            93:      Access the vector-pointer which is operand number IDX in EXP.
        !            94: 
        !            95: `XVECLEN (EXP, IDX)'
        !            96:      Access the length (number of elements) in the vector which is in
        !            97:      operand number IDX in EXP.  This value is an `int'.
        !            98: 
        !            99: `XVECEXP (EXP, IDX, ELTNUM)'
        !           100:      Access element number ELTNUM in the vector which is in operand number
        !           101:      IDX in EXP.  This value is an RTX.
        !           102: 
        !           103:      It is up to you to make sure that ELTNUM is not negative and is less
        !           104:      than `XVECLEN (EXP, IDX)'.
        !           105: 
        !           106: All the macros defined in this section expand into lvalues and therefore
        !           107: can be used to assign the operands, lengths and vector elements as well as
        !           108: to access them.
1.1       root      109: 
                    110: 
1.1.1.2 ! root      111: File: internals,  Node: Flags,  Next: Machine Modes,  Prev: Accessors,  Up: RTL
1.1       root      112: 
1.1.1.2 ! root      113: Flags in an RTL Expression
1.1       root      114: ==========================
                    115: 
1.1.1.2 ! root      116: RTL expressions contain several flags (one-bit bit-fields) that are used in
        !           117: certain types of expression.
        !           118: 
        !           119: `used'
        !           120:      This flag is used only momentarily, at the end of RTL generation for a
        !           121:      function, to count the number of times an expression appears in insns.
        !           122:       Expressions that appear more than once are copied, according to the
        !           123:      rules for shared structure (*Note Sharing::.).
        !           124: 
        !           125: `volatil'
        !           126:      This flag is used in `mem' and `reg' expressions and in insns.  In RTL
        !           127:      dump files, it is printed as `/v'.
        !           128: 
        !           129:      In a `mem' expression, it is 1 if the memory reference is volatile. 
        !           130:      Volatile memory references may not be deleted, reordered or combined.
        !           131: 
        !           132:      In a `reg' expression, it is 1 if the value is a user-level variable. 
        !           133:      0 indicates an internal compiler temporary.
        !           134: 
        !           135:      In an insn, 1 means the insn has been deleted.
        !           136: 
        !           137: `in_struct'
        !           138:      This flag is used in `mem' expressions.  It is 1 if the memory datum
        !           139:      referred to is all or part of a structure or array; 0 if it is (or
        !           140:      might be) a scalar variable.  A reference through a C pointer has 0
        !           141:      because the pointer might point to a scalar variable.
        !           142: 
        !           143:      This information allows the compiler to determine something about
        !           144:      possible cases of aliasing.
        !           145: 
        !           146:      In an RTL dump, this flag is represented as `/s'.
        !           147: 
        !           148: `unchanging'
        !           149:      This flag is used in `reg' and `mem' expressions.  1 means that the
        !           150:      value of the expression never changes (at least within the current
        !           151:      function).
        !           152: 
        !           153:      In an RTL dump, this flag is represented as `/u'.
        !           154: 
        !           155: 
        !           156: File: internals,  Node: Machine Modes,  Next: Constants,  Prev: Flags,  Up: RTL
        !           157: 
        !           158: Machine Modes
        !           159: =============
        !           160: 
        !           161: A machine mode describes a size of data object and the representation used
        !           162: for it.  In the C code, machine modes are represented by an enumeration
        !           163: type, `enum machine_mode', defined in `machmode.def'.  Each RTL expression
        !           164: has room for a machine mode and so do certain kinds of tree expressions
        !           165: (declarations and types, to be precise).
        !           166: 
        !           167: In debugging dumps and machine descriptions, the machine mode of an RTL
        !           168: expression is written after the expression code with a colon to separate
        !           169: them.  The letters `mode' which appear at the end of each machine mode name
        !           170: are omitted.  For example, `(reg:SI 38)' is a `reg' expression with machine
        !           171: mode `SImode'.  If the mode is `VOIDmode', it is not written at all.
        !           172: 
        !           173: Here is a table of machine modes.
        !           174: 
        !           175: `QImode'
        !           176:      ``Quarter-Integer'' mode represents a single byte treated as an integer.
        !           177: 
        !           178: `HImode'
        !           179:      ``Half-Integer'' mode represents a two-byte integer.
        !           180: 
        !           181: `SImode'
        !           182:      ``Single Integer'' mode represents a four-byte integer.
        !           183: 
        !           184: `DImode'
        !           185:      ``Double Integer'' mode represents an eight-byte integer.
        !           186: 
        !           187: `TImode'
        !           188:      ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
        !           189: 
        !           190: `SFmode'
        !           191:      ``Single Floating'' mode represents a single-precision (four byte)
        !           192:      floating point number.
        !           193: 
        !           194: `DFmode'
        !           195:      ``Double Floating'' mode represents a double-precision (eight byte)
        !           196:      floating point number.
        !           197: 
        !           198: `TFmode'
        !           199:      ``Tetra Floating'' mode represents a quadruple-precision (sixteen
        !           200:      byte) floating point number.
        !           201: 
        !           202: `BLKmode'
        !           203:      ``Block'' mode represents values that are aggregates to which none of
        !           204:      the other modes apply.  In RTL, only memory references can have this
        !           205:      mode, and only if they appear in string-move or vector instructions. 
        !           206:      On machines which have no such instructions, `BLKmode' will not appear
        !           207:      in RTL.
        !           208: 
        !           209: `VOIDmode'
        !           210:      Void mode means the absence of a mode or an unspecified mode.  For
        !           211:      example, RTL expressions of code `const_int' have mode `VOIDmode'
        !           212:      because they can be taken to have whatever mode the context requires. 
        !           213:      In debugging dumps of RTL, `VOIDmode' is expressed by the absence of
        !           214:      any mode.
        !           215: 
        !           216: `EPmode'
        !           217:      ``Entry Pointer'' mode is intended to be used for function variables
        !           218:      in Pascal and other block structured languages.  Such values contain
        !           219:      both a function address and a static chain pointer for access to
        !           220:      automatic variables of outer levels.  This mode is only partially
        !           221:      implemented since C does not use it.
        !           222: 
        !           223: `CSImode, ...'
        !           224:      ``Complex Single Integer'' mode stands for a complex number
        !           225:      represented as a pair of `SImode' integers.  Any of the integer and
        !           226:      floating modes may have `C' prefixed to its name to obtain a complex
        !           227:      number mode.  For example, there are `CQImode', `CSFmode', and
        !           228:      `CDFmode'.  Since C does not support complex numbers, these machine
        !           229:      modes are only partially implemented.
        !           230: 
        !           231: `BImode'
        !           232:      This is the machine mode of a bit-field in a structure.  It is used
        !           233:      only in the syntax tree, never in RTL, and in the syntax tree it
        !           234:      appears only in declaration nodes.  In C, it appears only in
        !           235:      `FIELD_DECL' nodes for structure fields defined with a bit size.
        !           236: 
        !           237: The machine description defines `Pmode' as a C macro which expands into the
        !           238: machine mode used for addresses.  Normally this is `SImode'.
        !           239: 
        !           240: The only modes which a machine description must support are `QImode',
        !           241: `SImode', `SFmode' and `DFmode'.  The compiler will attempt to use `DImode'
        !           242: for two-word structures and unions, but it would not be hard to program it
        !           243: to avoid this.  Likewise, you can arrange for the C type `short int' to
        !           244: avoid using `HImode'.  In the long term it would be desirable to make the
        !           245: set of available machine modes machine-dependent and eliminate all
        !           246: assumptions about specific machine modes or their uses from the
        !           247: machine-independent code of the compiler.
        !           248: 
        !           249: Here are some C macros that relate to machine modes:
        !           250: 
        !           251: `GET_MODE (X)'
        !           252:      Returns the machine mode of the RTX X.
        !           253: 
        !           254: `PUT_MODE (X, NEWMODE)'
        !           255:      Alters the machine mode of the RTX X to be NEWMODE.
        !           256: 
        !           257: `GET_MODE_SIZE (M)'
        !           258:      Returns the size in bytes of a datum of mode M.
        !           259: 
        !           260: `GET_MODE_BITSIZE (M)'
        !           261:      Returns the size in bits of a datum of mode M.
        !           262: 
        !           263: `GET_MODE_UNIT_SIZE (M)'
        !           264:      Returns the size in bits of the subunits of a datum of mode M.  This
        !           265:      is the same as `GET_MODE_SIZE' except in the case of complex modes and
        !           266:      `EPmode'.  For them, the unit size is the size of the real or
        !           267:      imaginary part, or the size of the function pointer or the context
        !           268:      pointer.
        !           269: 
        !           270: 
        !           271: File: internals,  Node: Constants,  Next: Regs and Memory,  Prev: Machine Modes,  Up: RTL
        !           272: 
        !           273: Constant Expression Types
        !           274: =========================
        !           275: 
        !           276: The simplest RTL expressions are those that represent constant values.
        !           277: 
        !           278: `(const_int I)'
        !           279:      This type of expression represents the integer value I.  I is
        !           280:      customarily accessed with the macro `INTVAL' as in `INTVAL (EXP)',
        !           281:      which is equivalent to `XINT (EXP, 0)'.
        !           282: 
        !           283:      There is only one expression object for the integer value zero; it is
        !           284:      the value of the variable `const0_rtx'.  Likewise, the only expression
        !           285:      for integer value one is found in `const1_rtx'.  Any attempt to create
        !           286:      an expression of code `const_int' and value zero or one will return
        !           287:      `const0_rtx' or `const1_rtx' as appropriate.
        !           288: 
        !           289: `(const_double:M I0 I1)'
        !           290:      Represents a floating point constant value of mode M.  The two
        !           291:      inteGERS I0 and I1 together contain the bits of a `double' value.  To
        !           292:      convert them to a `double', do
        !           293: 
        !           294:           union { double d; int i[2];} u;
        !           295:           u.i[0] = XINT (x, 0);
        !           296:           u.i[1] = XINT (x, 1);
        !           297: 
        !           298: 
        !           299:      and then refer to `u.d'.  The value of the constant is represented as
        !           300:      a double in this fashion even if the value represented is
        !           301:      single-precision.
        !           302: 
        !           303:      The global variables `dconst0_rtx' and `fconst0_rtx' hold
        !           304:      `const_double' expressions with value 0, in modes `DFmode' and
        !           305:      `SFmode', respectively.
        !           306: 
        !           307: `(symbol_ref SYMBOL)'
        !           308:      Represents the value of an assembler label for data.  SYMBOL is a
        !           309:      string that describes the name of the assembler label.  If it starts
        !           310:      with a `*', the label is the rest of SYMBOL not including the `*'. 
        !           311:      Otherwise, the label is SYMBOL, prefixed with `_'.
        !           312: 
        !           313: `(label_ref LABEL)'
        !           314:      Represents the value of an assembler label for code.  It contains one
        !           315:      operand, an expression, which must be a `code_label' that appears in
        !           316:      the instruction sequence to identify the place where the label should
        !           317:      go.
        !           318: 
        !           319:      The reason for using a distinct expression type for code label
        !           320:      references is so that jump optimization can distinguish them.
        !           321: 
        !           322: `(const EXP)'
        !           323:      Represents a constant that is the result of an assembly-time
        !           324:      arithmetic computation.  The operand, EXP, is an expression that
        !           325:      contains only constants (`const_int', `symbol_ref' and `label_ref'
        !           326:      expressions) combined with `plus' and `minus'.  However, not all
        !           327:      combinations are valid, since the assembler cannot do arbitrary
        !           328:      arithmetic on relocatable symbols.
        !           329: 
        !           330: 
        !           331: File: internals,  Node: Regs and Memory,  Next: Arithmetic,  Prev: Constants,  Up: RTL
        !           332: 
        !           333: Registers and Memory
        !           334: ====================
        !           335: 
        !           336: Here are the RTL expression types for describing access to machine
        !           337: registers and to main memory.
        !           338: 
        !           339: `(reg:M N)'
        !           340:      For small values of the integer N (less than `FIRST_PSEUDO_REGISTER'),
        !           341:      this stands for a reference to machine register number N: a "hard
        !           342:      register".  For larger values of N, it stands for a temporary value or
        !           343:      "pseudo register".  The compiler's strategy is to generate code
        !           344:      assuming an unlimited number of such pseudo registers, and later
        !           345:      convert them into hard registers or into memory references.
        !           346: 
        !           347:      The symbol `FIRST_PSEUDO_REGISTER' is defined by the machine
        !           348:      description, since the number of hard registers on the machine is an
        !           349:      invariant characteristic of the machine.  Note, however, that not all
        !           350:      of the machine registers must be general registers.  All the machine
        !           351:      registers that can be used for storage of data are given hard register
        !           352:      numbers, even those that can be used only in certain instructions or
        !           353:      can hold only certain types of data.
        !           354: 
        !           355:      Each pseudo register number used in a function's RTL code is
        !           356:      represented by a unique `reg' expression.
        !           357: 
        !           358:      M is the machine mode of the reference.  It is necessary because
        !           359:      machines can generally refer to each register in more than one mode. 
        !           360:      For example, a register may contain a full word but there may be
        !           361:      instructions to refer to it as a half word or as a single byte, as
        !           362:      well as instructions to refer to it as a floating point number of
        !           363:      various precisions.
        !           364: 
        !           365:      Even for a register that the machine can access in only one mode, the
        !           366:      mode must always be specified.
        !           367: 
        !           368:      A hard register may be accessed in various modes throughout one
        !           369:      function, but each pseudo register is given a natural mode and is
        !           370:      accessed only in that mode.  When it is necessary to describe an
        !           371:      access to a pseudo register using a nonnatural mode, a `subreg'
        !           372:      expression is used.
        !           373: 
        !           374:      A `reg' expression with a machine mode that specifies more than one
        !           375:      word of data may actually stand for several consecutive registers.  If
        !           376:      in addition the register number specifies a hardware register, then it
        !           377:      actually represents several consecutive hardware registers starting
        !           378:      with the specified one.
        !           379: 
        !           380:      Such multi-word hardware register `reg' expressions may not be live
        !           381:      across the boundary of a basic block.  The lifetime analysis pass does
        !           382:      not know how to record properly that several consecutive registers are
        !           383:      actually live there, and therefore register allocation would be
        !           384:      confused.  The CSE pass must go out of its way to make sure the
        !           385:      situation does not arise.
        !           386: 
        !           387: `(subreg:M REG WORDNUM)'
        !           388:      `subreg' expressions are used to refer to a register in a machine mode
        !           389:      other than its natural one, or to refer to one register of a
        !           390:      multi-word `reg' that actually refers to several registers.
        !           391: 
        !           392:      Each pseudo-register has a natural mode.  If it is necessary to
        !           393:      operate on it in a different mode---for example, to perform a fullword
        !           394:      move instruction on a pseudo-register that contains a single byte---
        !           395:      the pseudo-register must be enclosed in a `subreg'.  In such a case,
        !           396:      WORDNUM is zero.
        !           397: 
        !           398:      The other use of `subreg' is to extract the individual registers of a
        !           399:      multi-register value.  Machine modes such as `DImode' and `EPmode'
        !           400:      indicate values longer than a word, values which usually require two
        !           401:      consecutive registers.  To access one of the registers, use a `subreg'
        !           402:      with mode `SImode' and a WORDNUM that says which register.
        !           403: 
        !           404:      The compilation parameter `WORDS_BIG_ENDIAN', if defined, says that
        !           405:      word number zero is the most significant part; otherwise, it is the
        !           406:      least significant part.
        !           407: 
        !           408:      Note that it is not valid to access a `DFmode' value in `SFmode' using
        !           409:      a `subreg'.  On some machines the most significant part of a `DFmode'
        !           410:      value does not have the same format as a single-precision floating
        !           411:      value.
        !           412: 
        !           413: `(cc0)'
        !           414:      This refers to the machine's condition code register.  It has no
        !           415:      operands and may not have a machine mode.  It may be validly used in
        !           416:      only two contexts: as the destination of an assignment (in test and
        !           417:      compare instructions) and in comparison operators comparing against
        !           418:      zero (`const_int' with value zero; that is to say, `const0_rtx').
        !           419: 
        !           420:      There is only one expression object of code `cc0'; it is the value of
        !           421:      the variable `cc0_rtx'.  Any attempt to create an expression of code
        !           422:      `cc0' will return `cc0_rtx'.
        !           423: 
        !           424:      One special thing about the condition code register is that
        !           425:      instructions can set it implicitly.  On many machines, nearly all
        !           426:      instructions set the condition code based on the value that they
        !           427:      compute or store.  It is not necessary to record these actions
        !           428:      explicitly in the RTL because the machine description includes a
        !           429:      prescription for recognizing the instructions that do so (by means of
        !           430:      the macro `NOTICE_UPDATE_CC').  Only instructions whose sole purpose
        !           431:      is to set the condition code, and instructions that use the condition
        !           432:      code, need mention `(cc0)'.
        !           433: 
        !           434: `(pc)'
        !           435:      This represents the machine's program counter.  It has no operands and
        !           436:      may not have a machine mode.  `(pc)' may be validly used only in
        !           437:      certain specific contexts in jump instructions.
        !           438: 
        !           439:      There is only one expression object of code `pc'; it is the value of
        !           440:      the variable `pc_rtx'.  Any attempt to create an expression of code
        !           441:      `pc' will return `pc_rtx'.
        !           442: 
        !           443:      All instructions that do not jump alter the program counter implicitly
        !           444:      by incrementing it, but there is no need to mention this in the RTL.
        !           445: 
        !           446: `(mem:M ADDR)'
        !           447:      This RTX represents a reference to main memory at an address
        !           448:      represented by the expression ADDR.  M specifies how large a unit of
        !           449:      memory is accessed.
        !           450: 
        !           451: 
        !           452: File: internals,  Node: Arithmetic,  Next: Comparisons,  Prev: Regs and Memory,  Up: RTL
        !           453: 
        !           454: RTL Expressions for Arithmetic
        !           455: ==============================
        !           456: 
        !           457: `(plus:M X Y)'
        !           458:      Represents the sum of the values represented by X and Y carried out in
        !           459:      machine mode M.  This is valid only if X and Y both are valid for mode
        !           460:      M.
        !           461: 
        !           462: `(minus:M X Y)'
        !           463:      Like `plus' but represents subtraction.
        !           464: 
        !           465: `(minus X Y)'
        !           466:      Represents the result of subtracting Y from X for purposes of
        !           467:      comparison.  The absence of a machine mode in the `minus' expression
        !           468:      indicates that the result is computed without overflow, as if with
        !           469:      infinite precision.
        !           470: 
        !           471:      Of course, machines can't really subtract with infinite precision. 
        !           472:      However, they can pretend to do so when only the sign of the result
        !           473:      will be used, which is the case when the result is stored in `(cc0)'. 
        !           474:      And that is the only way this kind of expression may validly be used:
        !           475:      as a value to be stored in the condition codes.
        !           476: 
        !           477: `(neg:M X)'
        !           478:      Represents the negation (subtraction from zero) of the value
        !           479:      represented by X, carried out in mode M.  X must be valid for mode M.
        !           480: 
        !           481: `(mult:M X Y)'
        !           482:      Represents the signed product of the values represented by X and Y
        !           483:      carried out in machine mode M.  If X and Y are both valid for mode M,
        !           484:      this is ordinary size-preserving multiplication.  Alternatively, both
        !           485:      X and Y may be valid for a different, narrower mode.  This represents
        !           486:      the kind of multiplication that generates a product wider than the
        !           487:      operands.  Widening multiplication and same-size multiplication are
        !           488:      completely distinct and supported by different machine instructions;
        !           489:      machines may support one but not the other.
        !           490: 
        !           491:      `mult' may be used for floating point division as well.  Then M is a
        !           492:      floating point machine mode.
        !           493: 
        !           494: `(umult:M X Y)'
        !           495:      Like `mult' but represents unsigned multiplication.  It may be used in
        !           496:      both same-size and widening forms, like `mult'.  `umult' is used only
        !           497:      for fixed-point multiplication.
        !           498: 
        !           499: `(div:M X Y)'
        !           500:      Represents the quotient in signed division of X by Y, carried out in
        !           501:      machine mode M.  If M is a floating-point mode, it represents the
        !           502:      exact quotient; otherwise, the integerized quotient.  If X and Y are
        !           503:      both valid for mode M, this is ordinary size-preserving division. 
        !           504:      Some machines have division instructions in which the operands and
        !           505:      quotient widths are not all the same; such instructions are
        !           506:      represented by `div' expressions in which the machine modes are not
        !           507:      all the same.
        !           508: 
        !           509: `(udiv:M X Y)'
        !           510:      Like `div' but represents unsigned division.
        !           511: 
        !           512: `(mod:M X Y)'
        !           513: `(umod:M X Y)'
        !           514:      Like `div' and `udiv' but represent the remainder instead of the
        !           515:      quotient.
        !           516: 
        !           517: `(not:M X)'
        !           518:      Represents the bitwise complement of the value represented by X,
        !           519:      carried out in mode M, which must be a fixed-point machine mode.  X
        !           520:      must be valid for mode M, which must be a fixed-point mode.
        !           521: 
        !           522: `(and:M X Y)'
        !           523:      Represents the bitwise logical-and of the values represented by X and
        !           524:      Y, carried out in machine mode M.  This is valid only if X and Y both
        !           525:      are valid for mode M, which must be a fixed-point mode.
        !           526: 
        !           527: `(ior:M X Y)'
        !           528:      Represents the bitwise inclusive-or of the values represented by X and
        !           529:      Y, carried out in machine mode M.  This is valid only if X and Y both
        !           530:      are valid for mode M, which must be a fixed-point mode.
        !           531: 
        !           532: `(xor:M X Y)'
        !           533:      Represents the bitwise exclusive-or of the values represented by X and
        !           534:      Y, carried out in machine mode M.  This is valid only if X and Y both
        !           535:      are valid for mode M, which must be a fixed-point mode.
        !           536: 
        !           537: `(lshift:M X C)'
        !           538:      Represents the result of logically shifting X left by C places.  X
        !           539:      must be valid for the mode M, a fixed-point machine mode.  C must be
        !           540:      valid for a fixed-point mode; which mode is determined by the mode
        !           541:      called for in the machine description entry for the left-shift
        !           542:      instruction.  For example, on the Vax, the mode of C is `QImode'
        !           543:      regardless of M.
        !           544: 
        !           545:      On some machines, negative values of C may be meaningful; this is why
        !           546:      logical left shift and arithmetic left shift are distinguished.  For
        !           547:      example, Vaxes have no right-shift instructions, and right shifts are
        !           548:      represented as left-shift instructions whose counts happen to be
        !           549:      negative constants or else computed (in a previous instruction) by
        !           550:      negation.
        !           551: 
        !           552: `(ashift:M X C)'
        !           553:      Like `lshift' but for arithmetic left shift.
        !           554: 
        !           555: `(lshiftrt:M X C)'
        !           556: `(ashiftrt:M X C)'
        !           557:      Like `lshift' and `ashift' but for right shift.
        !           558: 
        !           559: `(rotate:M X C)'
        !           560: `(rotatert:M X C)'
        !           561:      Similar but represent left and right rotate.
        !           562: 
        !           563: `(abs:M X)'
        !           564:      Represents the absolute value of X, computed in mode M.  X must be
        !           565:      valid for M.
        !           566: 
        !           567: `(sqrt:M X)'
        !           568:      Represents the square root of X, computed in mode M.  X must be valid
        !           569:      for M.  Most often M will be a floating point mode.
        !           570: 
        !           571: `(ffs:M X)'
        !           572:      Represents the one plus the index of the least significant 1-bit in X,
        !           573:      represented as an integer of mode M.  (The value is zero if X is
        !           574:      zero.)  The mode of X need not be M; depending on the target machine,
        !           575:      various mode combinations may be valid.
        !           576: 
        !           577: 
        !           578: File: internals,  Node: Comparisons,  Next: Bit Fields,  Prev: Arithmetic,  Up: RTL
        !           579: 
        !           580: Comparison Operations
        !           581: =====================
        !           582: 
        !           583: Comparison operators test a relation on two operands and are considered to
        !           584: represent the value 1 if the relation holds, or zero if it does not.  The
        !           585: mode of the comparison is determined by the operands; they must both be
        !           586: valid for a common machine mode.  A comparison with both operands constant
        !           587: would be invalid as the machine mode could not be deduced from it, but such
        !           588: a comparison should never exist in RTL due to constant folding.
        !           589: 
        !           590: Inequality comparisons come in two flavors, signed and unsigned.  Thus,
        !           591: there are distinct expression codes `gt' and `gtu' for signed and unsigned
        !           592: greater-than.  These can produce different results for the same pair of
        !           593: integer values: for example, 1 is signed greater-than -1 but not unsigned
        !           594: greater-than, because -1 when regarded as unsigned is actually `0xffffffff'
        !           595: which is greater than 1.
        !           596: 
        !           597: The signed comparisons are also used for floating point values.  Floating
        !           598: point comparisons are distinguished by the machine modes of the operands.
        !           599: 
        !           600: The comparison operators may be used to compare the condition codes `(cc0)'
        !           601: against zero, as in `(eq (cc0) (const_int 0))'.  Such a construct actually
        !           602: refers to the result of the preceding instruction in which the condition
        !           603: codes were set.  The above example stands for 1 if the condition codes were
        !           604: set to say ``zero'' or ``equal'', 0 otherwise.  Although the same
        !           605: comparison operators are used for this as may be used in other contexts on
        !           606: actual data, no confusion can result since the machine description would
        !           607: never allow both kinds of uses in the same context.
        !           608: 
        !           609: `(eq X Y)'
        !           610:      1 if the values represented by X and Y are equal, otherwise 0.
        !           611: 
        !           612: `(ne X Y)'
        !           613:      1 if the values represented by X and Y are not equal, otherwise 0.
        !           614: 
        !           615: `(gt X Y)'
        !           616:      1 if the X is greater than Y.  If they are fixed-point, the comparison
        !           617:      is done in a signed sense.
        !           618: 
        !           619: `(gtu X Y)'
        !           620:      Like `gt' but does unsigned comparison, on fixed-point numbers only.
        !           621: 
        !           622: `(lt X Y)'
        !           623: `(ltu X Y)'
        !           624:      Like `gt' and `gtu' but test for ``less than''.
        !           625: 
        !           626: `(ge X Y)'
        !           627: `(geu X Y)'
        !           628:      Like `gt' and `gtu' but test for ``greater than or equal''.
        !           629: 
        !           630: `(le X Y)'
        !           631: `(leu X Y)'
        !           632:      Like `gt' and `gtu' but test for ``less than or equal''.
        !           633: 
        !           634: `(if_then_else COND THEN ELSE)'
        !           635:      This is not a comparison operation but is listed here because it is
        !           636:      always used in conjunction with a comparison operation.  To be
        !           637:      precISE, COND is a comparison expression.  This expression represents
        !           638:      a choice, according to COND, between the value represented by THEN and
        !           639:      the one represented by ELSE.
        !           640: 
        !           641:      On most machines, `if_then_else' expressions are valid only to express
        !           642:      conditional jumps.
        !           643: 
        !           644: 
        !           645: File: internals,  Node: Bit Fields,  Next: Conversions,  Prev: Comparisons,  Up: RTL
1.1       root      646: 
1.1.1.2 ! root      647: Bit-fields
        !           648: ==========
        !           649: 
        !           650: Special expression codes exist to represent bit-field instructions.  These
        !           651: types of expressions are lvalues in RTL; they may appear on the left side
        !           652: of a assignment, indicating insertion of a value into the specified bit
        !           653: field.
        !           654: 
        !           655: `(sign_extract:SI LOC SIZE POS)'
        !           656:      This represents a reference to a sign-extended bit-field contained or
        !           657:      starting in LOC (a memory or register reference).  The bit field is
        !           658:      SIZE bits wide and starts at bit POS.  The compilation option
        !           659:      `BITS_BIG_ENDIAN' says which end of the memory unit POS counts from.
        !           660: 
        !           661:      Which machine modes are valid for LOC depends on the machine, but
        !           662:      typically LOC should be a single byte when in memory or a full word in
        !           663:      a register.
        !           664: 
        !           665: `(zero_extract:SI LOC SIZE POS)'
        !           666:      Like `sign_extract' but refers to an unsigned or zero-extended bit
        !           667:      field.  The same sequence of bits are extracted, but they are filled
        !           668:      to an entire word with zeros instead of by sign-extension.
        !           669: 
        !           670: 
        !           671: File: internals,  Node: Conversions,  Next: RTL Declarations,  Prev: Bit Fields,  Up: RTL
        !           672: 
        !           673: Conversions
        !           674: ===========
        !           675: 
        !           676: All conversions between machine modes must be represented by explicit
        !           677: conversion operations.  For example, an expression which is the sum of a
        !           678: byte and a full word cannot be written as `(plus:SI (reg:QI 34) (reg:SI
        !           679: 80))' because the `plus' operation requires two operands of the same
        !           680: machine mode.  Therefore, the byte-sized operand is enclosed in a
        !           681: conversion operation, as in
        !           682: 
        !           683:      (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
        !           684: 
        !           685: 
        !           686: The conversion operation is not a mere placeholder, because there may be
        !           687: more than one way of converting from a given starting mode to the desired
        !           688: final mode.  The conversion operation code says how to do it.
        !           689: 
        !           690: `(sign_extend:M X)'
        !           691:      Represents the result of sign-extending the value X to machine mode M.
        !           692:       M must be a fixed-point mode and X a fixed-point value of a mode
        !           693:      narrower than M.
        !           694: 
        !           695: `(zero_extend:M X)'
        !           696:      Represents the result of zero-extending the value X to machine mode M.
        !           697:       M must be a fixed-point mode and X a fixed-point value of a mode
        !           698:      narrower than M.
        !           699: 
        !           700: `(float_extend:M X)'
        !           701:      Represents the result of extending the value X to machine mode M.  M
        !           702:      must be a floating point mode and X a floating point value of a mode
        !           703:      narrower than M.
        !           704: 
        !           705: `(truncate:M X)'
        !           706:      Represents the result of truncating the value X to machine mode M.  M
        !           707:      must be a fixed-point mode and X a fixed-point value of a mode wider
        !           708:      than M.
        !           709: 
        !           710: `(float_truncate:M X)'
        !           711:      Represents the result of truncating the value X to machine mode M.  M
        !           712:      must be a floating point mode and X a floating point value of a mode
        !           713:      wider than M.
        !           714: 
        !           715: `(float:M X)'
        !           716:      Represents the result of converting fixed point value X, regarded as
        !           717:      signed, to floating point mode M.
        !           718: 
        !           719: `(unsigned_float:M X)'
        !           720:      Represents the result of converting fixed point value X, regarded as
        !           721:      unsigned, to floating point mode M.
        !           722: 
        !           723: `(fix:M X)'
        !           724:      When M is a fixed point mode, represents the result of converting
        !           725:      floating point value X to mode M, regarded as signed.  How rounding is
        !           726:      done is not specified, so this operation may be used validly in
        !           727:      compiling C code only for integer-valued operands.
        !           728: 
        !           729: `(unsigned_fix:M X)'
        !           730:      Represents the result of converting floating point value X to fixed
        !           731:      point mode M, regarded as unsigned.  How rounding is done is not
        !           732:      specified.
        !           733: 
        !           734: `(fix:M X)'
        !           735:      When M is a floating point mode, represents the result of converting
        !           736:      floating point value X (valid for mode M) to an integer, still
        !           737:      represented in floating point mode M, by rounding towards zero.
        !           738: 
        !           739: 
        !           740: File: internals,  Node: RTL Declarations,  Next: Side Effects,  Prev: Conversions,  Up: RTL
        !           741: 
        !           742: Declarations
        !           743: ============
        !           744: 
        !           745: Declaration expression codes do not represent arithmetic operations but
        !           746: rather state assertions about their operands.
        !           747: 
        !           748: `(strict_low_part (subreg:M (reg:N R) 0))'
        !           749:      This expression code is used in only one context: operand 0 of a `set'
        !           750:      expression.  In addition, the operand of this expression must be a
        !           751:      `subreg' expression.
        !           752: 
        !           753:      The presence of `strict_low_part' says that the part of the register
        !           754:      which is meaningful in mode N, but is not part of mode M, is not to be
        !           755:      altered.  Normally, an assignment to such a subreg is allowed to have
        !           756:      undefined effects on the rest of the register when M is less than a
        !           757:      word.
        !           758: 
        !           759: 
        !           760: File: internals,  Node: Side Effects,  Next: Incdec,  Prev: RTL Declarations,  Up: RTL
        !           761: 
        !           762: Side Effect Expressions
        !           763: =======================
        !           764: 
        !           765: The expression codes described so far represent values, not actions.  But
        !           766: machine instructions never produce values; they are meaningful only for
        !           767: their side effects on the state of the machine.  Special expression codes
        !           768: are used to represent side effects.
        !           769: 
        !           770: The body of an instruction is always one of these side effect codes; the
        !           771: codes described above, which represent values, appear only as the operands
        !           772: of these.
        !           773: 
        !           774: `(set LVAL X)'
        !           775:      Represents the action of storing the value of X into the place
        !           776:      represented by LVAL.  LVAL must be an expression representing a place
        !           777:      that can be stored in: `reg' (or `subreg' or `strict_low_part'),
        !           778:      `mem', `pc' or `cc0'.
        !           779: 
        !           780:      If LVAL is a `reg', `subreg' or `mem', it has a machine mode; then X
        !           781:      must be valid for that mode.
        !           782: 
        !           783:      If LVAL is a `reg' whose machine mode is less than the full width of
        !           784:      the register, then it means that the part of the register specified by
        !           785:      the machine mode is given the specified value and the rest of the
        !           786:      register receives an undefined value.  Likewise, if LVAL is a `subreg'
        !           787:      whose machine mode is narrower than `SImode', the rest of the register
        !           788:      can be changed in an undefined way.
        !           789: 
        !           790:      If LVAL is a `strict_low_part' of a `subreg', then the part of the
        !           791:      register specified by the machine mode of the `subreg' is given the
        !           792:      value X and the rest of the register is not changed.
        !           793: 
        !           794:      If LVAL is `(cc0)', it has no machine mode, and X may have any mode. 
        !           795:      This represents a ``test'' or ``compare'' instruction.
        !           796: 
        !           797:      If LVAL is `(pc)', we have a jump instruction, and the possibilities
        !           798:      for X are very limited.  It may be a `label_ref' expression
        !           799:      (unconditional jump).  It may be an `if_then_else' (conditional jump),
        !           800:      in which case either the second or the third operand must be `(pc)'
        !           801:      (for the case which does not jump) and the other of the two must be a
        !           802:      `label_ref' (for the case which does jump).  X may also be a `mem' or
        !           803:      `(plus:SI (pc) Y)', where Y may be a `reg' or a `mem'; these unusual
        !           804:      patterns are used to represent jumps through branch tables.
        !           805: 
        !           806: `(return)'
        !           807:      Represents a return from the current function, on machines where this
        !           808:      can be done with one instruction, such as Vaxes.  On machines where a
        !           809:      multi-instruction ``epilogue'' must be executed in order to return
        !           810:      from the function, returning is done by jumping to a label which
        !           811:      precedes the epilogue, and the `return' expression code is never used.
        !           812: 
        !           813: `(call FUNCTION NARGS)'
        !           814:      Represents a function call.  FUNCTION is a `mem' expression whose
        !           815:      address is the address of the function to be called.  NARGS is an
        !           816:      expression representing the number of words of argument.
        !           817: 
        !           818:      Each machine has a standard machine mode which FUNCTION must have. 
        !           819:      The machine description defines macro `FUNCTION_MODE' to expand into
        !           820:      the requisite mode name.  The purpose of this mode is to specify what
        !           821:      kind of addressing is allowed, on machines where the allowed kinds of
        !           822:      addressing depend on the machine mode being addressed.
        !           823: 
        !           824: `(clobber X)'
        !           825:      Represents the storing or possible storing of an unpredictable,
        !           826:      undescribed value into X, which must be a `reg' or `mem' expression.
        !           827: 
        !           828:      One place this is used is in string instructions that store standard
        !           829:      values into particular hard registers.  It may not be worth the
        !           830:      trouble to describe the values that are stored, but it is essential to
        !           831:      inform the compiler that the registers will be altered, lest it
        !           832:      attempt to keep data in them across the string instruction.
        !           833: 
        !           834:      X may also be null---a null C pointer, no expression at all.  Such a
        !           835:      `(clobber (null))' expression means that all memory locations must be
        !           836:      presumed clobbered.
        !           837: 
        !           838:      Note that the machine description classifies certain hard registers as
        !           839:      ``call-clobbered''.  All function call instructions are assumed by
        !           840:      default to clobber these registers, so there is no need to use
        !           841:      `clobber' expressions to indicate this fact.  Also, each function call
        !           842:      is assumed to have the potential to alter any memory location.
        !           843: 
        !           844: `(use X)'
        !           845:      Represents the use of the value of X.  It indicates that the value in
        !           846:      X at this point in the program is needed, even though it may not be
        !           847:      apparent why this is so.  Therefore, the compiler will not attempt to
        !           848:      delete instructions whose only effect is to store a value in X.  X
        !           849:      must be a `reg' expression.
        !           850: 
        !           851: `(parallel [X0 X1 ...])'
        !           852:      Represents several side effects performed in parallel.  The square
        !           853:      brackets stand for a vector; the operand of `parallel' is a vector of
        !           854:      expressions.  X0, X1 and so on are individual side
        !           855:      effects---expressions of code `set', `call', `return', `clobber' or
        !           856:      `use'.
        !           857: 
        !           858:      ``In parallel'' means that first all the values used in the individual
        !           859:      side-effects are computed, and second all the actual side-effects are
        !           860:      performed.  For example,
        !           861: 
        !           862:           (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
        !           863:                      (set (mem:SI (reg:SI 1)) (reg:SI 1))])
        !           864: 
        !           865: 
        !           866:      says unambiguously that the values of hard register 1 and the memory
        !           867:      location addressed by it are interchanged.  In both places where
        !           868:      `(reg:SI 1)' appears as a memory address it refers to the value in
        !           869:      register 1 *before* the execution of the instruction.
        !           870: 
        !           871: `(sequence [INSNS ...])'
        !           872:      Represents a sequence of insns.  Each of the INSNS that appears in the
        !           873:      vector is suitable for appearing in the chain of insns, so it must be
        !           874:      an `insn', `jump_insn', `call_insn', `code_label', `barrier' or `note'.
        !           875: 
        !           876:      A `sequence' RTX never appears in an actual insn.  It represents the
        !           877:      sequence of insns that result from a `define_expand' *before* those
        !           878:      insns are passed to `emit_insn' to insert them in the chain of insns. 
        !           879:      When actually inserted, the individual sub-insns are separated out and
        !           880:      the `sequence' is forgotten.
        !           881: 
        !           882: Three expression codes appear in place of a side effect, as the body of an
        !           883: insn, though strictly speaking they do not describe side effects as such:
        !           884: 
        !           885: `(asm_input S)'
        !           886:      Represents literal assembler code as described by the string S.
        !           887: 
        !           888: `(addr_vec:M [LR0 LR1 ...])'
        !           889:      Represents a table of jump addresses.  The vector elements LR0, etc.,
        !           890:      are `label_ref' expressions.  The mode M specifies how much space is
        !           891:      given to each address; normally M would be `Pmode'.
        !           892: 
        !           893: `(addr_diff_vec:M BASE [LR0 LR1 ...])'
        !           894:      Represents a table of jump addresses expressed as offsets from BASE. 
        !           895:      The vector elements LR0, etc., are `label_ref' expressions and so is
        !           896:      BASE.  The mode M specifies how much space is given to each
        !           897:      address-difference.
        !           898: 
        !           899: 
        !           900: File: internals,  Node: Incdec,  Next: Assembler,  Prev: Side Effects,  Up: RTL
        !           901: 
        !           902: Embedded Side-Effects on Addresses
        !           903: ==================================
        !           904: 
        !           905: Four special side-effect expression codes appear as memory addresses.
        !           906: 
        !           907: `(pre_dec:M X)'
        !           908:      Represents the side effect of decrementing X by a standard amount and
        !           909:      represents also the value that X has after being decremented.  X must
        !           910:      be a `reg' or `mem', but most machines allow only a `reg'.  M must be
        !           911:      the machine mode for pointers on the machine in use.  The amount X is
        !           912:      decremented by is the length in bytes of the machine mode of the
        !           913:      containing memory reference of which this expression serves as the
        !           914:      address.  Here is an example of its use:
        !           915: 
        !           916:           (mem:DF (pre_dec:SI (reg:SI 39)))
        !           917: 
        !           918: 
        !           919:      This says to decrement pseudo register 39 by the length of a `DFmode'
        !           920:      value and use the result to address a `DFmode' value.
        !           921: 
        !           922: `(pre_inc:M X)'
        !           923:      Similar, but specifies incrementing X instead of decrementing it.
        !           924: 
        !           925: `(post_dec:M X)'
        !           926:      Represents the same side effect as `pre_decrement' but a different
        !           927:      value.  The value represented here is the value X has before being
        !           928:      decremented.
        !           929: 
        !           930: `(post_inc:M X)'
        !           931:      Similar, but specifies incrementing X instead of decrementing it.
        !           932: 
        !           933: These embedded side effect expressions must be used with care.  Instruction
        !           934: patterns may not use them.  Until the `flow' pass of the compiler, they may
        !           935: occur only to represent pushes onto the stack.  The `flow' pass finds cases
        !           936: where registers are incremented or decremented in one instruction and used
        !           937: as an address shortly before or after; these cases are then transformed to
        !           938: use pre- or post-increment or -decrement.
        !           939: 
        !           940: Explicit popping of the stack could be represented with these embedded side
        !           941: effect operators, but that would not be safe; the instruction combination
        !           942: pass could move the popping past pushes, thus changing the meaning of the
        !           943: code.
        !           944: 
        !           945: An instruction that can be represented with an embedded side effect could
        !           946: also be represented using `parallel' containing an additional `set' to
        !           947: describe how the address register is altered.  This is not done because
        !           948: machines that allow these operations at all typically allow them wherever a
        !           949: memory address is called for.  Describing them as additional parallel
        !           950: stores would require doubling the number of entries in the machine
        !           951: description.
        !           952: 
        !           953: 
        !           954: File: internals,  Node: Assembler,  Next: Insns,  Prev: IncDec,  Up: RTL
        !           955: 
        !           956: Assembler Instructions as Expressions
        !           957: =====================================
        !           958: 
        !           959: The RTX code `asm_operands' represents a value produced by a user-specified
        !           960: assembler instruction.  It is used to represent an `asm' statement with
        !           961: arguments.  An `asm' statement with a single output operand, like this:
        !           962: 
        !           963:      asm ("foo %1,%2,%0" : "a" (outputvar) : "g" (x + y), "di" (*z));
        !           964: 
        !           965: 
        !           966: is represented using a single `asm_operands' RTX which represents the value
        !           967: that is stored in `outputvar':
        !           968: 
        !           969:      (set RTX-FOR-OUTPUTVAR
        !           970:           (asm_operands "foo %1,%2,%0" "a" 0
        !           971:                         [RTX-FOR-ADDITION-RESULT RTX-FOR-*Z]
        !           972:                         [(asm_input:M1 "g")
        !           973:                          (asm_input:M2 "di")]))
        !           974: 
        !           975: 
        !           976: Here the operands of the `asm_operands' RTX are the assembler template
        !           977: string, the output-operand's constraint, the index-number of the output
        !           978: operand among the output operands specified, a vector of input operand
        !           979: RTX's, and a vector of input-operand modes and constraints.  The mode M1 is
        !           980: the mode of the sum `x+y'; M2 is that of `*z'.
        !           981: 
        !           982: When an `asm' statement has multiple output values, its insn has several
        !           983: such `set' RTX's inside of a `parallel'.  Each `set' contains a
        !           984: `asm_operands'; all of these share the same assembler template and vectors,
        !           985: but each contains the constraint for the respective output operand.  They
        !           986: are also distinguished by the output-operand index number, which is 0, 1,
        !           987: ... for successive output operands.
        !           988: 
        !           989: 
        !           990: File: internals,  Node: Insns,  Next: Calls,  Prev: Assembler,  Up: RTL
        !           991: 
        !           992: Insns
        !           993: =====
        !           994: 
        !           995: The RTL representation of the code for a function is a doubly-linked chain
        !           996: of objects called "insns".  Insns are expressions with special codes that
        !           997: are used for no other purpose.  Some insns are actual instructions; others
        !           998: represent dispatch tables for `switch' statements; others represent labels
        !           999: to jump to or various sorts of declarative information.
        !          1000: 
        !          1001: In addition to its own specific data, each insn must have a unique
        !          1002: id-number that distinguishes it from all other insns in the current
        !          1003: function, and chain pointers to the preceding and following insns.  These
        !          1004: three fields occupy the same position in every insn, independent of the
        !          1005: expression code of the insn.  They could be accessed with `XEXP' and
        !          1006: `XINT', but instead three special macros are always used:
        !          1007: 
        !          1008: `INSN_UID (I)'
        !          1009:      Accesses the unique id of insn I.
        !          1010: 
        !          1011: `PREV_INSN (I)'
        !          1012:      Accesses the chain pointer to the insn preceding I.  If I is the first
        !          1013:      insn, this is a null pointer.
        !          1014: 
        !          1015: `NEXT_INSN (I)'
        !          1016:      Accesses the chain pointer to the insn following I.  If I is the last
        !          1017:      insn, this is a null pointer.
        !          1018: 
        !          1019: The `NEXT_INSN' and `PREV_INSN' pointers must always correspond: if I is
        !          1020: not the first insn,
        !          1021: 
        !          1022:      NEXT_INSN (PREV_INSN (INSN)) == INSN
        !          1023: 
        !          1024: 
        !          1025: is always true.
        !          1026: 
        !          1027: Every insn has one of the following six expression codes:
        !          1028: 
        !          1029: `insn'
        !          1030:      The expression code `insn' is used for instructions that do not jump
        !          1031:      and do not do function calls.  Insns with code `insn' have four
        !          1032:      additional fields beyond the three mandatory ones listed above.  These
        !          1033:      four are described in a table below.
        !          1034: 
        !          1035: `jump_insn'
        !          1036:      The expression code `jump_insn' is used for instructions that may jump
        !          1037:      (or, more generally, may contain `label_ref' expressions). 
        !          1038:      `jump_insn' insns have the same extra fields as `insn' insns, accessed
        !          1039:      in the same way.
        !          1040: 
        !          1041: `call_insn'
        !          1042:      The expression code `call_insn' is used for instructions that may do
        !          1043:      function calls.  It is important to distinguish these instructions
        !          1044:      because they imply that certain registers and memory locations may be
        !          1045:      altered unpredictably.
        !          1046: 
        !          1047:      `call_insn' insns have the same extra fields as `insn' insns, accessed
        !          1048:      in the same way.
        !          1049: 
        !          1050: `code_label'
        !          1051:      A `code_label' insn represents a label that a jump insn can jump to. 
        !          1052:      It contains one special field of data in addition to the three
        !          1053:      standard ones.  It is used to hold the "label number", a number that
        !          1054:      identifies this label uniquely among all the labels in the compilation
        !          1055:      (not just in the current function).  Ultimately, the label is
        !          1056:      represented in the assembler output as an assembler label `LN' where N
        !          1057:      is the label number.
        !          1058: 
        !          1059: `barrier'
        !          1060:      Barriers are placed in the instruction stream after unconditional jump
        !          1061:      instructions to indicate that the jumps are unconditional.  They
        !          1062:      contain no information beyond the three standard fields.
        !          1063: 
        !          1064: `note'
        !          1065:      `note' insns are used to represent additional debugging and
        !          1066:      declarative information.  They contain two nonstandard fields, an
        !          1067:      integer which is accessed with the macro `NOTE_LINE_NUMBER' and a
        !          1068:      string accessed with `NOTE_SOURCE_FILE'.
        !          1069: 
        !          1070:      If `NOTE_LINE_NUMBER' is positive, the note represents the position of
        !          1071:      a source line and `NOTE_SOURCE_FILE' is the source file name that the
        !          1072:      line came from.  These notes control generation of line number data in
        !          1073:      the assembler output.
        !          1074: 
        !          1075:      Otherwise, `NOTE_LINE_NUMBER' is not really a line number but a code
        !          1076:      with one of the following values (and `NOTE_SOURCE_FILE' must contain
        !          1077:      a null pointer):
        !          1078: 
        !          1079:      `NOTE_INSN_DELETED'
        !          1080:           Such a note is completely ignorable.  Some passes of the compiler
        !          1081:           delete insns by altering them into notes of this kind.
        !          1082: 
        !          1083:      `NOTE_INSN_BLOCK_BEG'
        !          1084:      `NOTE_INSN_BLOCK_END'
        !          1085:           These types of notes indicate the position of the beginning and
        !          1086:           end of a level of scoping of variable names.  They control the
        !          1087:           output of debugging information.
        !          1088: 
        !          1089:      `NOTE_INSN_LOOP_BEG'
        !          1090:      `NOTE_INSN_LOOP_END'
        !          1091:           These types of notes indicate the position of the beginning and
        !          1092:           end of a `while' or `for' loop.  They enable the loop optimizer
        !          1093:           to find loops quickly.
        !          1094: 
        !          1095: Here is a table of the extra fields of `insn', `jump_insn' and `call_insn'
        !          1096: insns:
        !          1097: 
        !          1098: `PATTERN (I)'
        !          1099:      An expression for the side effect performed by this insn.
        !          1100: 
        !          1101: `REG_NOTES (I)'
        !          1102:      A list (chain of `expr_list' expressions) giving information about the
        !          1103:      usage of registers in this insn.  This list is set up by the flow
        !          1104:      analysis pass; it is a null pointer until then.
        !          1105: 
        !          1106: `LOG_LINKS (I)'
        !          1107:      A list (chain of `insn_list' expressions) of previous ``related''
        !          1108:      insns: insns which store into registers values that are used for the
        !          1109:      first time in this insn.  (An additional constraint is that neither a
        !          1110:      jump nor a label may come between the related insns).  This list is
        !          1111:      set up by the flow analysis pass; it is a null pointer until then.
        !          1112: 
        !          1113: `INSN_CODE (I)'
        !          1114:      An integer that says which pattern in the machine description matches
        !          1115:      this insn, or -1 if the matching has not yet been attempted.
        !          1116: 
        !          1117:      Such matching is never attempted and this field is not used on an insn
        !          1118:      whose pattern consists of a single `use', `clobber', `asm', `addr_vec'
        !          1119:      or `addr_diff_vec' expression.
        !          1120: 
        !          1121: The `LOG_LINKS' field of an insn is a chain of `insn_list' expressions. 
        !          1122: Each of these has two operands: the first is an insn, and the second is
        !          1123: another `insn_list' expression (the next one in the chain).  The last
        !          1124: `insn_list' in the chain has a null pointer as second operand.  The
        !          1125: significant thing about the chain is which insns appear in it (as first
        !          1126: operands of `insn_list' expressions).  Their order is not significant.
        !          1127: 
        !          1128: The `REG_NOTES' field of an insn is a similar chain but of `expr_list'
        !          1129: expressions instead of `insn_list'.  There are four kinds of register
        !          1130: notes, which are distinguished by the machine mode of the `expr_list',
        !          1131: which a register note is really understood as being an `enum reg_note'. 
        !          1132: The first operand OP of the `expr_list' is data whose meaning depends on
        !          1133: the kind of note.  Here are the four kinds:
        !          1134: 
        !          1135: `REG_DEAD'
        !          1136:      The register OP dies in this insn; that is to say, altering the value
        !          1137:      immediately after this insn would not affect the future behavior of
        !          1138:      the program.
        !          1139: 
        !          1140: `REG_INC'
        !          1141:      The register OP is incremented (or decremented; at this level there is
        !          1142:      no distinction) by an embedded side effect inside this insn.  This
        !          1143:      means it appears in a `POST_INC', `PRE_INC', `POST_DEC' or `PRE_DEC'
        !          1144:      RTX.
        !          1145: 
        !          1146: `REG_EQUIV'
        !          1147:      The register that is set by this insn will be equal to OP at run time,
        !          1148:      and could validly be replaced in all its occurrences by OP. 
        !          1149:      (``Validly'' here refers to the data flow of the program; simple
        !          1150:      replacement may make some insns invalid.)
        !          1151: 
        !          1152:      The value which the insn explicitly copies into the register may look
        !          1153:      different from OP, but they will be equal at run time.
        !          1154: 
        !          1155:      For example, when a constant is loaded into a register that is never
        !          1156:      assigned any other value, this kind of note is used.
        !          1157: 
        !          1158:      When a parameter is copied into a pseudo-register at entry to a
        !          1159:      function, a note of this kind records that the register is equivalent
        !          1160:      to the stack slot where the parameter was passed.  Although in this
        !          1161:      case the register may be set by other insns, it is still valid to
        !          1162:      replace the register by the stack slot throughout the function.
        !          1163: 
        !          1164: `REG_EQUAL'
        !          1165:      The register that is set by this insn will be equal to OP at run time
        !          1166:      at the end of this insn (but not necessarily elsewhere in the function).
        !          1167: 
        !          1168:      The RTX OP is typically an arithmetic expression.  For example, when a
        !          1169:      sequence of insns such as a library call is used to perform an
        !          1170:      arithmetic operation, this kind of note is attached to the insn that
        !          1171:      produces or copies the final value.  It tells the CSE pass how to
        !          1172:      think of that value.
        !          1173: 
        !          1174: `REG_RETVAL'
        !          1175:      This insn copies the value of a library call, and OP is the first insn
        !          1176:      that was generated to set up the arguments for the library call.
        !          1177: 
        !          1178:      Flow analysis uses this note to delete all of a library call whose
        !          1179:      result is dead.
        !          1180: 
        !          1181: `REG_WAS_0'
        !          1182:      The register OP contained zero before this insn.  You can rely on this
        !          1183:      note if it is present; its absence implies nothing.
        !          1184: 
        !          1185: (The only difference between the expression codes `insn_list' and
        !          1186: `expr_list' is that the first operand of an `insn_list' is assumed to be an
        !          1187: insn and is printed in debugging dumps as the insn's unique id; the first
        !          1188: operand of an `expr_list' is printed in the ordinary way as an expression.)
        !          1189: 
        !          1190: 
        !          1191: File: internals,  Node: Calls,  Next: Sharing,  Prev: Insns,  Up: RTL
        !          1192: 
        !          1193: RTL Representation of Function-Call Insns
        !          1194: =========================================
        !          1195: 
        !          1196: Insns that call subroutines have the RTL expression code `call_insn'. 
        !          1197: These insns must satisfy special rules, and their bodies must use a special
        !          1198: RTL expression code, `call'.
        !          1199: 
        !          1200: A `call' expression has two operands, as follows:
        !          1201: 
        !          1202:      (call NBYTES (mem:FM ADDR))
        !          1203: 
        !          1204: 
        !          1205: Here NBYTES is an operand that represents the number of bytes of argument
        !          1206: data being passed to the subroutine, FM is a machine mode (which must equal
        !          1207: as the definition of the `FUNCTION_MODE' macro in the machine description)
        !          1208: and ADDR represents the address of the subroutine.
        !          1209: 
        !          1210: For a subroutine that returns no value, the `call' RTX as shown above is
        !          1211: the entire body of the insn.
        !          1212: 
        !          1213: For a subroutine that returns a value whose mode is not `BLKmode', the
        !          1214: value is returned in a hard register.  If this register's number is R, then
        !          1215: the body of the call insn looks like this:
        !          1216: 
        !          1217:      (set (reg:M R)
        !          1218:           (call NBYTES (mem:FM ADDR)))
        !          1219: 
        !          1220: 
        !          1221: This RTL expression makes it clear (to the optimizer passes) that the
        !          1222: appropriate register receives a useful value in this insn.
        !          1223: 
        !          1224: Immediately after RTL generation, if the value of the subroutine is
        !          1225: actually used, this call insn is always followed closely by an insn which
        !          1226: refers to the register R.  The following insn has one of two forms.  Either
        !          1227: it copies the value into a pseudo-register, like this:
        !          1228: 
        !          1229:      (set (reg:M P) (reg:M R))
        !          1230: 
        !          1231: 
        !          1232: or (in the case where the calling function will simply return whatever
        !          1233: value the call produced, and no operation is needed to do this):
        !          1234: 
        !          1235:      (use (reg:M R))
        !          1236: 
        !          1237: 
        !          1238: Between the call insn and this insn there may intervene only a
        !          1239: stack-adjustment insn (and perhaps some `note' insns).
        !          1240: 
        !          1241: When a subroutine returns a `BLKmode' value, it is handled by passing to
        !          1242: the subroutine the address of a place to store the value.  So the call insn
        !          1243: itself does not ``return'' any value, and it has the same RTL form as a
        !          1244: call that returns nothing.
        !          1245: 
        !          1246: 

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