Return to internals-2 CVS log

Up to [GCC 1.x] / gcc

Annotation of gcc/internals-2, 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.
1.1       root       25: 
                     26: 
                     27: 
1.1.1.2 ! root       28: 
1.1       root       29: 
                     30: 
1.1.1.2 ! root       31: File: internals,  Node: Lvalues,  Next: Conditionals,  Prev: Typeof,  Up: Extensions
        !            32: 
        !            33: Generalized Lvalues
        !            34: ===================
        !            35: 
        !            36: Compound expressions, conditional expressions and casts are allowed as
        !            37: lvalues provided their operands are lvalues.  This means that you can take
        !            38: their addresses or store values into them.
        !            39: 
        !            40: For example, a compound expression can be assigned, provided the last
        !            41: expression in the sequence is an lvalue.  These two expressions are
        !            42: equivalent:
        !            43: 
        !            44:      (a, b) += 5
        !            45:      a, (b += 5)
        !            46: 
        !            47: 
        !            48: Similarly, the address of the compound expression can be taken.  These two
        !            49: expressions are equivalent:
        !            50: 
        !            51:      &(a, b)
        !            52:      a, &b
        !            53: 
        !            54: 
        !            55: A conditional expression is a valid lvalue if its type is not void and the
        !            56: true and false branches are both valid lvalues.  For example, these two
        !            57: expressions are equivalent:
        !            58: 
        !            59:      (a ? b : c) = 5
        !            60:      (a ? b = 5 : (c = 5))
        !            61: 
        !            62: 
        !            63: A cast is a valid lvalue if its operand is valid.  Taking the address of
        !            64: the cast is the same as taking the address without a cast, except for the
        !            65: type of the result.  For example, these two expressions are equivalent (but
        !            66: the second may be valid when the type of `a' does not permit a cast to `int
        !            67: *').
        !            68: 
        !            69:      &(int *)a
        !            70:      (int **)&a
        !            71: 
        !            72: 
        !            73: A simple assignment whose left-hand side is a cast works by converting the
        !            74: right-hand side first to the specified type, then to the type of the inner
        !            75: left-hand side expression.  After this is stored, the value is converter
        !            76: back to the specified type to become the value of the assignment.  Thus, if
        !            77: `a' has type `char *', the following two expressions are equivalent:
        !            78: 
        !            79:      (int)a = 5
        !            80:      (int)(a = (char *)5)
        !            81: 
1.1       root       82: 
1.1.1.2 ! root       83: An assignment-with-arithmetic operation such as `+=' applied to a cast
        !            84: performs the arithmetic using the type resulting from the cast, and then
        !            85: continues as in the previous case.  Therefore, these two expressions are
        !            86: equivalent:
        !            87: 
        !            88:      (int)a += 5
        !            89:      (int)(a = (char *) ((int)a + 5))
        !            90: 
        !            91: 
        !            92: 
        !            93: File: internals,  Node: Conditionals,  Next: Zero-Length,  Prev: Lvalues,  Up: Extensions
        !            94: 
        !            95: Conditional Expressions with Omitted Middle-Operands
        !            96: ====================================================
        !            97: 
        !            98: The middle operand in a conditional expression may be omitted.  Then if the
        !            99: first operand is nonzero, its value is the value of the conditional
        !           100: expression.
        !           101: 
        !           102: Therefore, the expression
        !           103: 
        !           104:      x ? : y
        !           105: 
        !           106: 
        !           107: has the value of `x' if that is nonzero; otherwise, the value of `y'.
        !           108: 
        !           109: This example is perfectly equivalent to
        !           110: 
        !           111:      x ? x : y
        !           112: 
        !           113: 
        !           114: In this simple case, the ability to omit the middle operand is not
        !           115: especially useful.  When it becomes useful is when the first operand does,
        !           116: or may (if it is a macro argument), contain a side effect.  Then repeating
        !           117: the operand in the middle would perform the side effect twice.  Omitting
        !           118: the middle operand uses the value already computed without the undesirable
        !           119: effects of recomputing it.
        !           120: 
        !           121: 
        !           122: File: internals,  Node: Zero-Length,  Next: Variable-Length,  Prev: Conditionals,  Up: Extensions
        !           123: 
        !           124: Arrays of Length Zero
1.1       root      125: =====================
                    126: 
1.1.1.2 ! root      127: Zero-length arrays are allowed in GNU C.  They are very useful as the last
        !           128: element of a structure which is really a header for a variable-length object:
        !           129: 
        !           130:      struct line {
        !           131:        int length;
        !           132:        char contents[0];
        !           133:      };
        !           134:      
        !           135:      {
        !           136:        struct line *thisline 
        !           137:          = (struct line *) malloc (sizeof (struct line) + this_length);
        !           138:        thisline->length = thislength;
        !           139:      }
        !           140: 
        !           141: 
        !           142: In standard C, you would have to give `contents' a length of 1, which means
        !           143: either you waste space or complicate the argument to `malloc'.
1.1       root      144: 
                    145: 
1.1.1.2 ! root      146: File: internals,  Node: Variable-Length,  Next: Subscripting,  Prev: Zero-Length,  Up: Extensions
1.1       root      147: 
1.1.1.2 ! root      148: Arrays of Variable Length
        !           149: =========================
1.1       root      150: 
1.1.1.2 ! root      151: Variable-length automatic arrays are allowed in GNU C.  These arrays are
        !           152: declared like any other automatic arrays, but with a length that is not a
        !           153: constant expression.  The storage is allocated at that time and deallocated
        !           154: when the brace-level is exited.  For example:
        !           155: 
        !           156:      FILE *concat_fopen (char *s1, char *s2, char *mode)
        !           157:      {
        !           158:        char str[strlen (s1) + strlen (s2) + 1];
        !           159:        strcpy (str, s1);
        !           160:        strcat (str, s2);
        !           161:        return fopen (str, mode);
        !           162:      }
        !           163: 
        !           164: 
        !           165: You can also define structure types containing variable-length arrays, and
        !           166: use them even for arguments or function values, as shown here:
        !           167: 
        !           168:      int foo;
        !           169:      
        !           170:      struct entry
        !           171:      {
        !           172:        char data[foo];
        !           173:      };
        !           174:      
        !           175:      struct entry
        !           176:      tester (struct entry arg)
        !           177:      {
        !           178:        struct entry new;
        !           179:        int i;
        !           180:        for (i = 0; i < foo; i++)
        !           181:          new.data[i] = arg.data[i] + 1;
        !           182:        return new;
        !           183:      }
        !           184: 
        !           185: 
        !           186: (Eventually there will be a way to say that the size of the array is
        !           187: another member of the same structure.)
        !           188: 
        !           189: The length of an array is computed on entry to the brace-level where the
        !           190: array is declared and is remembered for the scope of the array in case you
        !           191: access it with `sizeof'.
        !           192: 
        !           193: Jumping or breaking out of the scope of the array name will also deallocate
        !           194: the storage.  Jumping into the scope is not allowed; you will get an error
        !           195: message for it.
        !           196: 
        !           197: You can use the function `alloca' to get an effect much like
        !           198: variable-length arrays.  The function `alloca' is available in many other C
        !           199: implementations (but not in all).  On the other hand, variable-length
        !           200: arrays are more elegant.
        !           201: 
        !           202: There are other differences between these two methods.  Space allocated
        !           203: with `alloca' exists until the containing *function* returns.  The space
        !           204: for a variable-length array is deallocated as soon as the array name's
        !           205: scope ends.  (If you use both variable-length arrays and `alloca' in the
        !           206: same function, deallocation of a variable-length array will also deallocate
        !           207: anything more recently allocated with `alloca'.)
1.1       root      208: 
                    209: 
1.1.1.2 ! root      210: File: internals,  Node: Subscripting,  Next: Pointer Arith,  Prev: Variable-Length,  Up: Extensions
1.1       root      211: 
1.1.1.2 ! root      212: Non-Lvalue Arrays May Have Subscripts
        !           213: =====================================
1.1       root      214: 
1.1.1.2 ! root      215: Subscripting is allowed on arrays that are not lvalues, even though the
        !           216: unary `&' operator is not.  For example, this is valid in GNU C though not
        !           217: valid in other C dialects:
1.1       root      218: 
1.1.1.2 ! root      219:      struct foo {int a[4];};
1.1       root      220:      
1.1.1.2 ! root      221:      struct foo f();
1.1       root      222:      
1.1.1.2 ! root      223:      bar (int index)
        !           224:      {
        !           225:        return f().a[index];
        !           226:      }
        !           227: 
        !           228: 
        !           229: 
        !           230: File: internals,  Node: Pointer Arith,  Next: Initializers,  Prev: Subscripting,  Up: Extensions
        !           231: 
        !           232: Arithmetic on `void'-Pointers and Function Pointers
        !           233: ===================================================
        !           234: 
        !           235: In GNU C, addition and subtraction operations are supported on pointers to
        !           236: `void' and on pointers to functions.  This is done by treating the size of
        !           237: a `void' or of a function as 1.
        !           238: 
        !           239: A consequence of this is that `sizeof' is also allowed on `void' and on
        !           240: function types, and returns 1.
1.1       root      241: 
                    242: 
1.1.1.2 ! root      243: File: internals,  Node: Initializers,  Next: Constructors,  Prev: Pointer Arith,  Up: Extensions
        !           244: 
        !           245: Non-Constant Initializers
        !           246: =========================
        !           247: 
        !           248: The elements of an aggregate initializer are not required to be constant
        !           249: expressions in GNU C.  Here is an example of an initializer with run-time
        !           250: varying elements:
        !           251: 
        !           252:      foo (float f, float g)
        !           253:      {
        !           254:        float beat_freqs[2] = { f-g, f+g };
        !           255:        ...
        !           256:      }
1.1       root      257: 
1.1.1.2 ! root      258: 
        !           259: 
        !           260: File: internals,  Node: Constructors,  Next: Dollar Signs,  Prev: Initializers,  Up: Extensions
        !           261: 
        !           262: Constructor Expressions
1.1       root      263: =======================
                    264: 
1.1.1.2 ! root      265: GNU C supports constructor expressions.  A constructor looks like a cast
        !           266: containing an initializer.  Its value is an object of the type specified in
        !           267: the cast, containing the elements specified in the initializer.  The type
        !           268: must be a structure, union or array type.
1.1       root      269: 
1.1.1.2 ! root      270: Assume that `struct foo' and `structure' are declared as shown:
1.1       root      271: 
1.1.1.2 ! root      272:      struct foo {int a; char b[2];} structure;
1.1       root      273: 
                    274: 
1.1.1.2 ! root      275: Here is an example of constructing a `struct foo' with a constructor:
1.1       root      276: 
1.1.1.2 ! root      277:      structure = ((struct foo) {x + y, 'a', 0});
1.1       root      278: 
                    279: 
1.1.1.2 ! root      280: This is equivalent to writing the following:
1.1       root      281: 
1.1.1.2 ! root      282:      {
        !           283:        struct foo temp = {x + y, 'a', 0};
        !           284:        structure = temp;
        !           285:      }
1.1       root      286: 
                    287: 
1.1.1.2 ! root      288: You can also construct an array.  If all the elements of the constructor
        !           289: are (made up of) simple constant expressions, suitable for use in
        !           290: initializers, then the constructor is an lvalue and can be coerced to a
        !           291: pointer to its first element, as shown here:
        !           292: 
        !           293:      char **foo = (char *[]) { "x", "y", "z" };
        !           294: 
        !           295: 
        !           296: Array constructors whose elements are not simple constants are not very
        !           297: useful, because the constructor is not an lvalue.  There are only two valid
        !           298: ways to use it: to subscript it, or initialize an array variable with it. 
        !           299: The former is probably slower than a `switch' statement, while the latter
        !           300: does the same thing an ordinary C initializer would do.
        !           301: 
        !           302:      output = ((int[]) { 2, x, 28 }) [input];
1.1       root      303: 
                    304: 
                    305: 
1.1.1.2 ! root      306: File: internals,  Node: Dollar Signs,  Next: Alignment,  Prev: Constructors,  Up: Extensions
1.1       root      307: 
1.1.1.2 ! root      308: Dollar Signs in Identifier Names
        !           309: ================================
1.1       root      310: 
1.1.1.2 ! root      311: In GNU C, you may use dollar signs in identifier names.  This is because
        !           312: many traditional C implementations allow such identifiers.
1.1       root      313: 
1.1.1.2 ! root      314: 
        !           315: File: internals,  Node: Alignment,  Next: Inline,  Prev: Dollar Signs,  Up: Extensions
1.1       root      316: 
1.1.1.2 ! root      317: Inquiring about the Alignment of a Type or Variable
        !           318: ===================================================
1.1       root      319: 
1.1.1.2 ! root      320: The keyword `__alignof' allows you to inquire about how an object is
        !           321: aligned, or the minimum alignment usually required by a type.  Its syntax
        !           322: is just like `sizeof'.
1.1       root      323: 
1.1.1.2 ! root      324: For example, if the target machine requires a `double' value to be aligned
        !           325: on an 8-byte boundary, then `__alignof (double)' is 8.  This is true on
        !           326: many RISC machines.  On more traditional machine designs, `__alignof
        !           327: (double)' is 4 or even 2.
        !           328: 
        !           329: Some machines never actually require alignment; they allow reference to any
        !           330: data type even at an odd addresses.  For these machines, `__alignof'
        !           331: reports the *recommended* alignment of a type.
        !           332: 
        !           333: When the operand of `__alignof' is an lvalue rather than a type, the value
        !           334: is the largest alignment that the lvalue is known to have.  It may have
        !           335: this alignment as a result of its data type, or because it is part of a
        !           336: structure and inherits alignment from that structure. For example, after
        !           337: this declaration:
        !           338: 
        !           339:      struct foo { int x; char y; } foo1;
        !           340: 
        !           341: 
        !           342: the value of `__alignof (foo1.y)' is probably 2 or 4, the same as
        !           343: `__alignof (int)', even though the data type of `foo1.y' does not itself
        !           344: demand any alignment.
        !           345: 
        !           346: 
        !           347: File: internals,  Node: Inline,  Next: Extended Asm,  Prev: Alignment,  Up: Extensions
        !           348: 
        !           349: An Inline Function is As Fast As a Macro
        !           350: ========================================
        !           351: 
        !           352: By declaring a function `inline', you can direct GNU CC to integrate that
        !           353: function's code into the code for its callers.  This makes execution faster
        !           354: by eliminating the function-call overhead; in addition, if any of the
        !           355: actual argument values are constant, their known values may permit
        !           356: simplifications at compile time so that not all of the inline function's
        !           357: code needs to be included.
        !           358: 
        !           359: To declare a function inline, use the `inline' keyword in its declaration,
        !           360: like this:
        !           361: 
        !           362:      inline int
        !           363:      inc (int *a)
        !           364:      {
        !           365:        (*a)++;
        !           366:      }
        !           367: 
        !           368: 
        !           369: You can also make all ``simple enough'' functions inline with the option
        !           370: `-finline-functions'.  Note that certain usages in a function definition
        !           371: can make it unsuitable for inline substitution.
        !           372: 
        !           373: When a function is both inline and `static', if all calls to the function
        !           374: are integrated into the caller, then the function's own assembler code is
        !           375: never referenced.  In this case, GNU CC does not actually output assembler
        !           376: code for the function, unless you specify the option
        !           377: `-fkeep-inline-functions'.  Some calls cannot be integrated for various
        !           378: reasons (in particular, calls that precede the function's definition cannot
        !           379: be integrated, and neither can recursive calls within the definition).  If
        !           380: there is a nonintegrated call, then the function is compiled to assembler
        !           381: code as usual.
        !           382: 
        !           383: When an inline function is not `static', then the compiler must assume that
        !           384: there may be calls from other source files; since a global symbol can be
        !           385: defined only once in any program, the function must not be defined in the
        !           386: other source files, so the calls therein cannot be integrated.  Therefore,
        !           387: a non-`static' inline function is always compiled on its own in the usual
        !           388: fashion.
        !           389: 
        !           390: 
        !           391: File: internals,  Node: Extended Asm,  Next: Asm Labels,  Prev: Inline,  Up: Extensions
        !           392: 
        !           393: Assembler Instructions with C Expression Operands
        !           394: =================================================
        !           395: 
        !           396: In an assembler instruction using `asm', you can now specify the operands
        !           397: of the instruction using C expressions.  This means no more guessing which
        !           398: registers or memory locations will contain the data you want to use.
        !           399: 
        !           400: You must specify an assembler instruction template much like what appears
        !           401: in a machine description, plus an operand constraint string for each operand.
        !           402: 
        !           403: For example, here is how to use the 68881's `fsinx' instruction:
        !           404: 
        !           405:      asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
        !           406: 
        !           407: 
        !           408: Here `angle' is the C expression for the input operand while `result' is
        !           409: that of the output operand.  Each has `"f"' as its operand constraint,
        !           410: saying that a floating-point register is required.  The constraints use the
        !           411: same language used in the machine description (*Note Constraints::.).
        !           412: 
        !           413: Each operand is described by an operand-constraint string followed by the C
        !           414: expression in parentheses.  A colon separates the assembler template from
        !           415: the first output operand, and another separates the last output operand
        !           416: from the first input, if any.  Commas separate output operands and separate
        !           417: inputs.  The number of operands is limited to the maximum number of
        !           418: operands in any instruction pattern in the machine description.
        !           419: 
        !           420: Output operand expressions must be lvalues, and there must be at least one
        !           421: of them.  The compiler can check this.  The input operands need not be
        !           422: lvalues, and there need not be any.  The compiler cannot check whether the
        !           423: operands have data types that are reasonable for the instruction being
        !           424: executed.
        !           425: 
        !           426: The output operands must be write-only; GNU CC will assume that the values
        !           427: in these operands before the instruction are dead and need not be
        !           428: generated.  For an operand that is read-write, you must logically split its
        !           429: function into two separate operands, one input operand and one write-only
        !           430: output operand.  The connection between them is expressed by constraints
        !           431: which say they need to be in the same location when the instruction
        !           432: executes.  You can use the same C expression for both operands, or
        !           433: different expressions.  For example, here we write the (fictitious)
        !           434: `combine' instruction with `bar' as its read-only source operand and `foo'
        !           435: as its read-write destination:
        !           436: 
        !           437:      asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
        !           438: 
        !           439: 
        !           440: The constraint `"0"' for operand 1 says that it must occupy the same
        !           441: location as operand 0.  Therefore it is not necessary to substitute operand
        !           442: 1 into the assembler code output.
        !           443: 
        !           444: Usually the most convenient way to use these `asm' instructions is to
        !           445: encapsulate them in macros that look like functions.  For example,
        !           446: 
        !           447:      #define sin(x)       \
        !           448:      ({ double __value, __arg = (x);   \
        !           449:         asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
        !           450:         __value; })
        !           451: 
        !           452: 
        !           453: Here the variable `__arg' is used to make sure that the instruction
        !           454: operates on a proper `double' value, and to accept only those arguments `x'
        !           455: which can convert automatically to a `double'.
        !           456: 
        !           457: Another way to make sure the instruction operates on the correct data type
        !           458: is to use a cast in the `asm'.  This is different from using a variable
        !           459: `__arg' in that it converts more different types.  For example, if the
        !           460: desired type were `int', casting the argument to `int' would accept a
        !           461: pointer with no complaint, while assigning the argument to an `int'
        !           462: variable named `__arg' would warn about using a pointer unless the caller
        !           463: explicitly casts it.
        !           464: 
        !           465: GNU CC assumes for optimization purposes that these instructions have no
        !           466: side effects except to change the output operands.  This does not mean that
        !           467: instructions with a side effect cannot be used, but you must be careful,
        !           468: because the compiler may eliminate them if the output operands aren't used,
        !           469: or move them out of loops, or replace two with one if they constitute a
        !           470: common subexpression.  Also, if your instruction does have a side effect on
        !           471: a variable that otherwise appears not to change, the old value of the
        !           472: variable may be reused later if it happens to be found in a register.
        !           473: 
        !           474: You can prevent an `asm' instruction from being deleted, moved or combined
        !           475: by writing the keyword `volatile' after the `asm'.  For example:
        !           476: 
        !           477:      #define set_priority(x)  \
        !           478:      asm volatile ("set_priority %1":    \
        !           479:                    "=m" (*(char *)0): "g" (x))
        !           480: 
        !           481: 
        !           482: Note that we have supplied an output operand which is not actually used in
        !           483: the instruction.  This is because `asm' requires at least one output
        !           484: operand.  This requirement exists for internal implementation reasons and
        !           485: we might be able to relax it in the future.
        !           486: 
        !           487: In this case output operand has the additional benefit effect of giving the
        !           488: appearance of writing in memory.  As a result, GNU CC will assume that data
        !           489: previously fetched from memory must be fetched again if needed again later.
        !           490:  This may be desirable if you have not employed the `volatile' keyword on
        !           491: all the variable declarations that ought to have it.
        !           492: 
        !           493: 
        !           494: File: internals,  Node: Asm Labels,  Prev: Extended Asm,  Up: Extensions
        !           495: 
        !           496: Controlling Names Used in Assembler Code
        !           497: ========================================
        !           498: 
        !           499: You can specify the name to be used in the assembler code for a C function
        !           500: or variable by writing the `asm' keyword after the declarator as follows:
        !           501: 
        !           502:      int foo asm ("myfoo") = 2;
        !           503: 
        !           504: 
        !           505: This specifies that the name to be used for the variable `foo' in the
        !           506: assembler code should be `myfoo' rather than the usual `_foo'.
        !           507: 
        !           508: On systems where an underscore is normally prepended to the name of a C
        !           509: function or variable, this feature allows you to define names for the
        !           510: linker that do not start with an underscore.
        !           511: 
        !           512: You cannot use `asm' in this way in a function *definition*; but you can
        !           513: get the same effect by writing a declaration for the function before its
        !           514: definition and putting `asm' there, like this:
        !           515: 
        !           516:      extern func () asm ("FUNC");
1.1       root      517:      
1.1.1.2 ! root      518:      func (x, y)
        !           519:           int x, y;
        !           520:      ...
        !           521: 
1.1       root      522: 
1.1.1.2 ! root      523:  It is up to you to make sure that the assembler names you choose do not
        !           524: conflict with any other assembler symbols.  Also, you must not use a
        !           525: register name; that would produce completely invalid assembler code.  GNU
        !           526: CC does not as yet have the ability to store static variables in registers.
        !           527:  Perhaps that will be added.
1.1       root      528: 
                    529: 
1.1.1.2 ! root      530: File: internals,  Node: Bugs,  Next: Portability,  Prev: Extensions,  Up: Top
1.1       root      531: 
1.1.1.2 ! root      532: Reporting Bugs
        !           533: **************
        !           534: 
        !           535: Your bug reports play an essential role in making GNU CC reliable.
        !           536: 
        !           537: Reporting a bug may help you by bringing a solution to your problem, or it
        !           538: may not.  But in any case the important function of a bug report is to help
        !           539: the entire community by making the next version of GNU CC work better.  Bug
        !           540: reports are your contribution to the maintenance of GNU CC.
        !           541: 
        !           542: In order for a bug report to serve its purpose, you must include the
        !           543: information that makes for fixing the bug.
1.1       root      544: 
                    545: 
                    546: * Menu:
                    547: 
1.1.1.2 ! root      548: * Criteria:  Bug Criteria.   Have you really found a bug?
        !           549: * Reporting: Bug Reporting.  How to report a bug effectively.
        !           550: 
1.1       root      551: 
                    552: 
1.1.1.2 ! root      553: File: internals,  Node: Bug Criteria,  Next: Bug Reporting,  Prev: Bugs,  Up: Bugs
1.1       root      554: 
1.1.1.2 ! root      555: Have You Found a Bug?
        !           556: =====================
1.1       root      557: 
1.1.1.2 ! root      558: If you are not sure whether you have found a bug, here are some guidelines:
1.1       root      559: 
1.1.1.2 ! root      560:    * If the compiler gets a fatal signal, for any input whatever, that is a
        !           561:      compiler bug.  Reliable compilers never crash.
1.1       root      562: 
1.1.1.2 ! root      563:    * If the compiler produces invalid assembly code, for any input whatever
        !           564:      (except an `asm' statement), that is a compiler bug, unless the
        !           565:      compiler reports errors (not just warnings) which would ordinarily
        !           566:      prevent the assembler from being run.
        !           567: 
        !           568:    * If the compiler produces valid assembly code that does not correctly
        !           569:      execute the input source code, that is a compiler bug.
        !           570: 
        !           571:      However, you must double-check to make sure, because you may have run
        !           572:      into an incompatibility between GNU C and traditional C (*Note
        !           573:      Incompatibilities::.).  These incompatibilities might be considered
        !           574:      bugs, but they are inescapable consequences of features valuable
        !           575:      features.
        !           576: 
        !           577:      Or you may have a program whose behavior is undefined, which happened
        !           578:      by chance to give the desired results with another C compiler.
        !           579: 
        !           580:      For example, in many nonoptimizing compilers, you can write `x;' at
        !           581:      the end of a function instead of `return x;', with the same results. 
        !           582:      But the value of the function is undefined if `return' is omitted; it
        !           583:      is not a bug when GNU CC produces different results.
        !           584: 
        !           585:      Problems often result from expressions with two increment operators,
        !           586:      as in `f (*p++, *p++)'.  Your previous compiler might have interpreted
        !           587:      that expression the way you intended; GNU CC might interpret it
        !           588:      another way; neither compiler is wrong.
        !           589: 
        !           590:      After you have localized the error to a single source line, it should
        !           591:      be easy to check for these things.  If your program is correct and
        !           592:      well defined, you have found a compiler bug.
        !           593: 
        !           594:    * If the compiler produces an error message for valid input, that is a
        !           595:      compiler bug.
        !           596: 
        !           597:      Note that the following is not valid input, and the error message for
        !           598:      it is not a bug:
        !           599: 
        !           600:           int foo (char);
        !           601:           
        !           602:           int
        !           603:           foo (x)
        !           604:                char x;
        !           605:           { ... }
        !           606: 
        !           607: 
        !           608:      The prototype says to pass a `char', while the definition says to pass
        !           609:      an `int' and treat the value as a `char'.  This is what the ANSI
        !           610:      standard says, and it makes sense.
        !           611: 
        !           612:    * If the compiler does not produce an error message for invalid input,
        !           613:      that is a compiler bug.  However, you should note that your idea of
        !           614:      ``invalid input'' might be my idea of ``an extension'' or ``support
        !           615:      for traditional practice''.
        !           616: 
        !           617:    * If you are an experienced user of C compilers, your suggestions for
        !           618:      improvement of GNU CC are welcome in any case.
1.1       root      619: 
                    620: 
1.1.1.2 ! root      621: File: internals,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: Bugs
        !           622: 
        !           623: How to Report Bugs
        !           624: ==================
        !           625: 
        !           626: Send bug reports for GNU C to one of these addresses:
        !           627: 
        !           628:      [email protected]
        !           629:      {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gcc
        !           630: 
        !           631: 
        !           632: As a last resort, snail them to:
        !           633: 
        !           634:      GNU Compiler Bugs
        !           635:      545 Tech Sq
        !           636:      Cambridge, MA 02139
        !           637: 
        !           638: 
        !           639: The fundamental principle of reporting bugs usefully is this: *report all
        !           640: the facts*.  If you are not sure whether to mention a fact or leave it out,
        !           641: mention it!
        !           642: 
        !           643: Often people omit facts because they think they know what causes the
        !           644: problem and they conclude that some details don't matter.  Thus, you might
        !           645: assume that the name of the variable you use in an example does not matter.
        !           646:  Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
        !           647: stray memory reference which happens to fetch from the location where that
        !           648: name is stored in memory; perhaps, if the name were different, the contents
        !           649: of that location would fool the compiler into doing the right thing despite
        !           650: the bug.  Play it safe and give an exact example.
        !           651: 
        !           652: If you want to enable me to fix the bug, you should include all these things:
        !           653: 
        !           654:    * The version of GNU CC.  You can get this by running it with the `-v'
        !           655:      option.
        !           656: 
        !           657:      Without this, I won't know whether there is any point in looking for
        !           658:      the bug in the current version of GNU CC.
        !           659: 
        !           660:    * A complete input file that will reproduce the bug.  If the bug is in
        !           661:      the C preprocessor, send me a source file and any header files that it
        !           662:      requires.  If the bug is in the compiler proper (`cc1'), run your
        !           663:      source file through the C preprocessor by doing `gcc -E SOURCEFILE >
        !           664:      OUTFILE', then include the contents of OUTFILE in the bug report. 
        !           665:      (Any `-I', `-D' or `-U' options that you used in actual compilation
        !           666:      should also be used when doing this.)
        !           667: 
        !           668:      A single statement is not enough of an example.  In order to compile
        !           669:      it, it must be embedded in a function definition; and the bug might
        !           670:      depend on the details of how this is done.
        !           671: 
        !           672:      Without a real example I can compile, all I can do about your bug
        !           673:      report is wish you luck.  It would be futile to try to guess how to
        !           674:      provoke the bug.  For example, bugs in register allocation and
        !           675:      reloading frequently depend on every little detail of the function
        !           676:      they happen in.
1.1       root      677: 
1.1.1.2 ! root      678:    * The command arguments you gave GNU CC to compile that example and
        !           679:      observe the bug.  For example, did you use `-O'?  To guarantee you
        !           680:      won't omit something important, list them all.
1.1       root      681: 
1.1.1.2 ! root      682:      If I were to try to guess the arguments, I would probably guess wrong
        !           683:      and then I would not encounter the bug.
1.1       root      684: 
1.1.1.2 ! root      685:    * The names of the files that you used for `tm.h' and `md' when you
        !           686:      installed the compiler.
        !           687: 
        !           688:    * The type of machine you are using, and the operating system name and
        !           689:      version number.
        !           690: 
        !           691:    * A description of what behavior you observe that you believe is
        !           692:      incorrect.  For example, ``It gets a fatal signal,'' or, ``There is an
        !           693:      incorrect assembler instruction in the output.''
        !           694: 
        !           695:      Of course, if the bug is that the compiler gets a fatal signal, then I
        !           696:      will certainly notice it.  But if the bug is incorrect output, I might
        !           697:      not notice unless it is glaringly wrong.  I won't study all the
        !           698:      assembler code from a 50-line C program just on the off chance that it
        !           699:      might be wrong.
        !           700: 
        !           701:      Even if the problem you experience is a fatal signal, you should still
        !           702:      say so explicitly.  Suppose something strange is going on, such as,
        !           703:      your copy of the compiler is out of synch, or you have encountered a
        !           704:      bug in the C library on your system.  (This has happened!)  Your copy
        !           705:      might crash and mine would not.  If you told me to expect a crash,
        !           706:      then when mine fails to crash, I would know that the bug was not
        !           707:      happening for me.  If you had not told me to expect a crash, then I
        !           708:      would not be able to draw any conclusion from my observations.
        !           709: 
        !           710:      In cases where GNU CC generates incorrect code, if you send me a small
        !           711:      complete sample program I will find the error myself by running the
        !           712:      program under a debugger.  If you send me a large example or a part of
        !           713:      a larger program, I cannot do this; you must debug the compiled
        !           714:      program and narrow the problem down to one source line.  Tell me which
        !           715:      source line it is, and what you believe is incorrect about the code
        !           716:      generated for that line.
        !           717: 
        !           718:    * If you send me examples of output from GNU CC, please use `-g' when
        !           719:      you make them.  The debugging information includes source line numbers
        !           720:      which are essential for correlating the output with the input.
        !           721: 
        !           722: Here are some things that are not necessary:
        !           723: 
        !           724:    * A description of the envelope of the bug.
        !           725: 
        !           726:      Often people who encounter a bug spend a lot of time investigating
        !           727:      which changes to the input file will make the bug go away and which
        !           728:      changes will not affect it.
        !           729: 
        !           730:      This is often time consuming and not very useful, because the way I
        !           731:      will find the bug is by running a single example under the debugger
        !           732:      with breakpoints, not by pure deduction from a series of examples.
        !           733: 
        !           734:      Of course, it can't hurt if you can find a simpler example that
        !           735:      triggers the same bug.  Errors in the output will be easier to spot,
        !           736:      running under the debugger will take less time, etc.  An easy way to
        !           737:      simplify an example is to delete all the function definitions except
        !           738:      the one where the bug occurs.  Those earlier in the file may be
        !           739:      replaced by external declarations.
        !           740: 
        !           741:      However, simplification is not necessary; if you don't want to do
        !           742:      this, report the bug anyway.
        !           743: 
        !           744:    * A patch for the bug.
        !           745: 
        !           746:      A patch for the bug does help me if it is a good one.  But don't omit
        !           747:      the necessary information, such as the test case, because I might see
        !           748:      problems with your patch and decide to fix the problem another way.
        !           749: 
        !           750:      Sometimes with a program as complicated as GNU CC it is very hard to
        !           751:      construct an example that will make the program go through a certain
        !           752:      point in the code.  If you don't send me the example, I won't be able
        !           753:      to verify that the bug is fixed.
        !           754: 
        !           755:    * A guess about what the bug is or what it depends on.
        !           756: 
        !           757:      Such guesses are usually wrong.  Even I can't guess right about such
        !           758:      things without using the debugger to find the facts.  They also don't
        !           759:      serve a useful purpose.
1.1       root      760: 
                    761: 
1.1.1.2 ! root      762: File: internals,  Node: Portability,  Next: Interface,  Prev: Bugs,  Up: Top
1.1       root      763: 
1.1.1.2 ! root      764: GNU CC and Portability
        !           765: **********************
1.1       root      766: 
1.1.1.2 ! root      767: The main goal of GNU CC was to make a good, fast compiler for machines in
        !           768: the class that the GNU system aims to run on: 32-bit machines that address
        !           769: 8-bit bytes and have several general registers.  Elegance, theoretical
        !           770: power and simplicity are only secondary.
        !           771: 
        !           772: GNU CC gets most of the information about the target machine from a machine
        !           773: description which gives an algebraic formula for each of the machine's
        !           774: instructions.  This is a very clean way to describe the target.  But when
        !           775: the compiler needs information that is difficult to express in this
        !           776: fashion, I have not hesitated to define an ad-hoc parameter to the machine
        !           777: description.  The purpose of portability is to reduce the total work needed
        !           778: on the compiler; it was not of interest for its own sake.
        !           779: 
        !           780: GNU CC does not contain machine dependent code, but it does contain code
        !           781: that depends on machine parameters such as endianness (whether the most
        !           782: significant byte has the highest or lowest address of the bytes in a word)
        !           783: and the availability of autoincrement addressing.  In the RTL-generation
        !           784: pass, it is often necessary to have multiple strategies for generating code
        !           785: for a particular kind of syntax tree, strategies that are usable for
        !           786: different combinations of parameters.  Often I have not tried to address
        !           787: all possible cases, but only the common ones or only the ones that I have
        !           788: encountered.  As a result, a new target may require additional strategies. 
        !           789: You will know if this happens because the compiler will call `abort'. 
        !           790: Fortunately, the new strategies can be added in a machine-independent
        !           791: fashion, and will affect only the target machines that need them.
1.1       root      792: 
                    793: 
1.1.1.2 ! root      794: File: internals,  Node: Interface,  Next: Passes,  Prev: Portability,  Up: Top
1.1       root      795: 
1.1.1.2 ! root      796: Interfacing to GNU CC Output
        !           797: ****************************
1.1       root      798: 
1.1.1.2 ! root      799: GNU CC is normally configured to use the same function calling convention
        !           800: normally in use on the target system.  This is done with the
        !           801: machine-description macros described (*Note Machine Macros::.).
        !           802: 
        !           803: However, returning of structure and union values is done differently.  As a
        !           804: result, functions compiled with PCC returning such types cannot be called
        !           805: from code compiled with GNU CC, and vice versa.  This usually does not
        !           806: cause trouble because the Unix library routines don't return structures and
        !           807: unions.
        !           808: 
        !           809: Structures and unions that are 1, 2, 4 or 8 bytes long are returned in the
        !           810: same registers used for `int' or `double' return values.  (GNU CC typically
        !           811: allocates variables of such types in registers also.)  Structures and
        !           812: unions of other sizes are returned by storing them into an address passed
        !           813: by the caller in a register.  This method is faster than the one normally
        !           814: used by PCC and is also reentrant.  The register used for passing the
        !           815: address is specified by the machine-description macro `STRUCT_VALUE_REGNUM'.
        !           816: 
        !           817: GNU CC always passes arguments on the stack.  At some point it will be
        !           818: extended to pass arguments in registers, for machines which use that as the
        !           819: standard calling convention.  This will make it possible to use such a
        !           820: convention on other machines as well.  However, that would render it
        !           821: completely incompatible with PCC.  We will probably do this once we have a
        !           822: complete GNU system so we can compile the libraries with GNU CC.
        !           823: 
        !           824: If you use `longjmp', beware of automatic variables.  ANSI C says that
        !           825: automatic variables that are not declared `volatile' have undefined values
        !           826: after a `longjmp'.  And this is all GNU CC promises to do, because it is
        !           827: very difficult to restore register variables correctly, and one of GNU CC's
        !           828: features is that it can put variables in registers without your asking it to.
        !           829: 
        !           830: If you want a variable to be unaltered by `longjmp', and you don't want to
        !           831: write `volatile' because old C compilers don't accept it, just take the
        !           832: address of the variable.  If a variable's address is ever taken, even if
        !           833: just to compute it and ignore it, then the variable cannot go in a register:
        !           834: 
        !           835:      {
        !           836:        int careful;
        !           837:        &careful;
        !           838:        ...
        !           839:      }
        !           840: 
        !           841: 
        !           842: Code compiled with GNU CC may call certain library routines.  The routines
        !           843: needed on the Vax and 68000 are in the file `gnulib.c'.  You must compile
        !           844: this file with the standard C compiler, not with GNU CC, and then link it
        !           845: with each program you compile with GNU CC.  (In actuality, many programs
        !           846: will not need it.)  The usual function call interface is used for calling
        !           847: the library routines.  Some standard parts of the C library, such as
        !           848: `bcopy', are also called automatically.
        !           849: 
        !           850: 
        !           851: File: internals,  Node: Passes,  Next: RTL,  Prev: Interface,  Up: Top
1.1       root      852: 
1.1.1.2 ! root      853: Passes and Files of the Compiler
        !           854: ********************************
1.1       root      855: 
1.1.1.2 ! root      856: The overall control structure of the compiler is in `toplev.c'.  This file
        !           857: is responsible for initialization, decoding arguments, opening and closing
        !           858: files, and sequencing the passes.
        !           859: 
        !           860: The parsing pass is invoked only once, to parse the entire input.  The RTL
        !           861: intermediate code for a function is generated as the function is parsed, a
        !           862: statement at a time.  Each statement is read in as a syntax tree and then
        !           863: converted to RTL; then the storage for the tree for the statement is
        !           864: reclaimed.  Storage for types (and the expressions for their sizes),
        !           865: declarations, and a representation of the binding contours and how they
        !           866: nest, remains until the function is finished being compiled; these are all
        !           867: needed to output the debugging information.
        !           868: 
        !           869: Each time the parsing pass reads a complete function definition or
        !           870: top-level declaration, it calls the function `rest_of_compilation' or
        !           871: `rest_of_decl_compilation' in `toplev.c', which are responsible for all
        !           872: further processing necessary, ending with output of the assembler language.
        !           873:  All other compiler passes run, in sequence, within `rest_of_compilation'. 
        !           874: When that function returns from compiling a function definition, the
        !           875: storage used for that function definition's compilation is entirely freed,
        !           876: unless it is an inline function (*Note Inline::.).
        !           877: 
        !           878: Here is a list of all the passes of the compiler and their source files. 
        !           879: Also included is a description of where debugging dumps can be requested
        !           880: with `-d' options.
        !           881: 
        !           882:    * Parsing.  This pass reads the entire text of a function definition,
        !           883:      constructing partial syntax trees.  This and RTL generation are no
        !           884:      longer truly separate passes (formerly they were), but it is easier to
        !           885:      think of them as separate.
        !           886: 
        !           887:      The tree representation does not entirely follow C syntax, because it
        !           888:      is intended to support other languages as well.
        !           889: 
        !           890:      C data type analysis is also done in this pass, and every tree node
        !           891:      that represents an expression has a data type attached.  Variables are
        !           892:      represented as declaration nodes.
        !           893: 
        !           894:      Constant folding and associative-law simplifications are also done
        !           895:      during this pass.
        !           896: 
        !           897:      The source files for parsing are `parse.y', `decl.c', `typecheck.c',
        !           898:      `stor-layout.c', `fold-const.c', and `tree.c'.  The last three are
        !           899:      intended to be language-independent.  There are also header files
        !           900:      `parse.h', `c-tree.h', `tree.h' and `tree.def'.  The last two define
        !           901:      the format of the tree representation.
        !           902: 
        !           903:    * RTL generation.  This is the conversion of syntax tree into RTL code. 
        !           904:      It is actually done statement-by-statement during parsing, but for
        !           905:      most purposes it can be thought of as a separate pass.
        !           906: 
        !           907:      This is where the bulk of target-parameter-dependent code is found,
        !           908:      since often it is necessary for strategies to apply only when certain
        !           909:      standard kinds of instructions are available.  The purpose of named
        !           910:      instruction patterns is to provide this information to the RTL
        !           911:      generation pass.
        !           912: 
        !           913:      Optimization is done in this pass for `if'-conditions that are
        !           914:      comparisons, boolean operations or conditional expressions.  Tail
        !           915:      recursion is detected at this time also.  Decisions are made about how
        !           916:      best to arrange loops and how to output `switch' statements.
        !           917: 
        !           918:      The source files for RTL generation are `stmt.c', `expr.c',
        !           919:      `explow.c', `expmed.c', `optabs.c' and `emit-rtl.c'.  Also, the file
        !           920:      `insn-emit.c', generated from the machine description by the program
        !           921:      `genemit', is used in this pass.  The header files `expr.h' is used
        !           922:      for communication within this pass.
        !           923: 
        !           924:      The header files `insn-flags.h' and `insn-codes.h', generated from the
        !           925:      machine description by the programs `genflags' and `gencodes', tell
        !           926:      this pass which standard names are available for use and which
        !           927:      patterns correspond to them.
        !           928: 
        !           929:      Aside from debugging information output, none of the following passes
        !           930:      refers to the tree structure representation of the function (only part
        !           931:      of which is saved).
        !           932: 
        !           933:      The decision of whether the function can and should be expanded inline
        !           934:      in its subsequent callers is made at the end of rtl generation.  The
        !           935:      function must meet certain criteria, currently related to the size of
        !           936:      the function and the types and number of parameters it has.  Note that
        !           937:      this function may contain loops, recursive calls to itself
        !           938:      (tail-recursive functions can be inlined!), gotos, in short, all
        !           939:      constructs supported by GNU CC.
        !           940: 
        !           941:      The option `-dr' causes a debugging dump of the RTL code after this
        !           942:      pass.  This dump file's name is made by appending `.rtl' to the input
        !           943:      file name.
        !           944: 
        !           945:    * Jump optimization.  This pass simplifies jumps to the following
        !           946:      instruction, jumps across jumps, and jumps to jumps.  It deletes
        !           947:      unreferenced labels and unreachable code, except that unreachable code
        !           948:      that contains a loop is not recognized as unreachable in this pass. 
        !           949:      (Such loops are deleted later in the basic block analysis.)
        !           950: 
        !           951:      Jump optimization is performed two or three times.  The first time is
        !           952:      immediately following RTL generation.  The second time is after CSE,
        !           953:      but only if CSE says repeated jump optimization is needed.  The last
        !           954:      time is right before the final pass.  That time, cross-jumping and
        !           955:      deletion of no-op move instructions are done together with the
        !           956:      optimizations described above.
        !           957: 
        !           958:      The source file of this pass is `jump.c'.
        !           959: 
        !           960:      The option `-dj' causes a debugging dump of the RTL code after this
        !           961:      pass is run for the first time.  This dump file's name is made by
        !           962:      appending `.jump' to the input file name.
        !           963: 
        !           964:    * Register scan.  This pass finds the first and last use of each
        !           965:      register, as a guide for common subexpression elimination.  Its source
        !           966:      is in `regclass.c'.
        !           967: 
        !           968:    * Common subexpression elimination.  This pass also does constant
        !           969:      propagation.  Its source file is `cse.c'.  If constant propagation
        !           970:      causes conditional jumps to become unconditional or to become no-ops,
        !           971:      jump optimization is run again when CSE is finished.
        !           972: 
        !           973:      The option `-ds' causes a debugging dump of the RTL code after this
        !           974:      pass.  This dump file's name is made by appending `.cse' to the input
        !           975:      file name.
        !           976: 
        !           977:    * Loop optimization.  This pass moves constant expressions out of loops.
        !           978:       Its source file is `loop.c'.
        !           979: 
        !           980:      The option `-dL' causes a debugging dump of the RTL code after this
        !           981:      pass.  This dump file's name is made by appending `.loop' to the input
        !           982:      file name.
        !           983: 
        !           984:    * Stupid register allocation is performed at this point in a
        !           985:      nonoptimizing compilation.  It does a little data flow analysis as
        !           986:      well.  When stupid register allocation is in use, the next pass
        !           987:      executed is the reloading pass; the others in between are skipped. 
        !           988:      The source file is `stupid.c'.
        !           989: 
        !           990:    * Data flow analysis (`flow.c').  This pass divides the program into
        !           991:      basic blocks (and in the process deletes unreachable loops); then it
        !           992:      computes which pseudo-registers are live at each point in the program,
        !           993:      and makes the first instruction that uses a value point at the
        !           994:      instruction that computed the value.
        !           995: 
        !           996:      This pass also deletes computations whose results are never used, and
        !           997:      combines memory references with add or subtract instructions to make
        !           998:      autoincrement or autodecrement addressing.
        !           999: 
        !          1000:      The option `-df' causes a debugging dump of the RTL code after this
        !          1001:      pass.  This dump file's name is made by appending `.flow' to the input
        !          1002:      file name.  If stupid register allocation is in use, this dump file
        !          1003:      reflects the full results of such allocation.
        !          1004: 
        !          1005:    * Instruction combination (`combine.c').  This pass attempts to combine
        !          1006:      groups of two or three instructions that are related by data flow into
        !          1007:      single instructions.  It combines the RTL expressions for the
        !          1008:      instructions by substitution, simplifies the result using algebra, and
        !          1009:      then attempts to match the result against the machine description.
        !          1010: 
        !          1011:      The option `-dc' causes a debugging dump of the RTL code after this
        !          1012:      pass.  This dump file's name is made by appending `.combine' to the
        !          1013:      input file name.
        !          1014: 
        !          1015:    * Register class preferencing.  The RTL code is scanned to find out
        !          1016:      which register class is best for each pseudo register.  The source
        !          1017:      file is `regclass.c'.
        !          1018: 
        !          1019:    * Local register allocation (`local-alloc.c').  This pass allocates hard
        !          1020:      registers to pseudo registers that are used only within one basic
        !          1021:      block.  Because the basic block is linear, it can use fast and
        !          1022:      powerful techniques to do a very good job.
        !          1023: 
        !          1024:      The option `-dl' causes a debugging dump of the RTL code after this
        !          1025:      pass.  This dump file's name is made by appending `.lreg' to the input
        !          1026:      file name.
        !          1027: 
        !          1028:    * Global register allocation (`global-alloc.c').  This pass allocates
        !          1029:      hard registers for the remaining pseudo registers (those whose life
        !          1030:      spans are not contained in one basic block).
        !          1031: 
        !          1032:    * Reloading.  This pass renumbers pseudo registers with the hardware
        !          1033:      registers numbers they were allocated.  Pseudo registers that did not
        !          1034:      get hard registers are replaced with stack slots.  Then it finds
        !          1035:      instructions that are invalid because a value has failed to end up in
        !          1036:      a register, or has ended up in a register of the wrong kind.  It fixes
        !          1037:      up these instructions by reloading the problematical values
        !          1038:      temporarily into registers.  Additional instructions are generated to
        !          1039:      do the copying.
        !          1040: 
        !          1041:      Source files are `reload.c' and `reload1.c', plus the header
        !          1042:      `reload.h' used for communication between them.
        !          1043: 
        !          1044:      The option `-dg' causes a debugging dump of the RTL code after this
        !          1045:      pass.  This dump file's name is made by appending `.greg' to the input
        !          1046:      file name.
        !          1047: 
        !          1048:    * Jump optimization is repeated, this time including cross-jumping and
        !          1049:      deletion of no-op move instructions.  Machine-specific peephole
        !          1050:      optimizations are performed at the same time.
        !          1051: 
        !          1052:      The option `-dJ' causes a debugging dump of the RTL code after this
        !          1053:      pass.  This dump file's name is made by appending `.jump2' to the
        !          1054:      input file name.
        !          1055: 
        !          1056:    * Final.  This pass outputs the assembler code for the function.  It is
        !          1057:      also responsible for identifying spurious test and compare
        !          1058:      instructions.  The function entry and exit sequences are generated
        !          1059:      directly as assembler code in this pass; they never exist as RTL.
        !          1060: 
        !          1061:      The source files are `final.c' plus `insn-output.c'; the latter is
        !          1062:      generated automatically from the machine description by the tool
        !          1063:      `genoutput'.  The header file `conditions.h' is used for communication
        !          1064:      between these files.
        !          1065: 
        !          1066:    * Debugging information output.  This is run after final because it must
        !          1067:      output the stack slot offsets for pseudo registers that did not get
        !          1068:      hard registers.  Source files are `dbxout.c' for DBX symbol table
        !          1069:      format and `symout.c' for GDB's own symbol table format.
        !          1070: 
        !          1071: Some additional files are used by all or many passes:
        !          1072: 
        !          1073:    * Every pass uses `machmode.def', which defines the machine modes.
        !          1074: 
        !          1075:    * All the passes that work with RTL use the header files `rtl.h' and
        !          1076:      `rtl.def', and subroutines in file `rtl.c'.  The tools `gen*' also use
        !          1077:      these files to read and work with the machine description RTL.
        !          1078: 
        !          1079:    * Several passes refer to the header file `insn-config.h' which contains
        !          1080:      a few parameters (C macro definitions) generated automatically from
        !          1081:      the machine description RTL by the tool `genconfig'.
        !          1082: 
        !          1083:    * Several passes use the instruction recognizer, which consists of
        !          1084:      `recog.c' and `recog.h', plus the files `insn-recog.c' and
        !          1085:      `insn-extract.c' that are generated automatically from the machine
        !          1086:      description by the tools `genrecog' and `genextract'.
        !          1087: 
        !          1088:    * Several passes use the header files `regs.h' which defines the
        !          1089:      information recorded about pseudo register usage, and `basic-block.h'
        !          1090:      which defines the information recorded about basic blocks.
        !          1091: 
        !          1092:    * `hard-reg-set.h' defines the type `HARD_REG_SET', a bit-vector with a
        !          1093:      bit for each hard register, and some macros to manipulate it.  This
        !          1094:      type is just `int' if the machine has few enough hard registers;
        !          1095:      otherwise it is an array of `int' and some of the macros expand into
        !          1096:      loops.
1.1       root     1097: 
                   1098: 
1.1.1.2 ! root     1099: File: internals,  Node: RTL,  Next: Machine Desc,  Prev: Passes,  Up: Top
1.1       root     1100: 
1.1.1.2 ! root     1101: RTL Representation
        !          1102: ******************
1.1       root     1103: 
1.1.1.2 ! root     1104: Most of the work of the compiler is done on an intermediate representation
        !          1105: called register transfer language.  In this language, the instructions to
        !          1106: be output are described, pretty much one by one, in an algebraic form that
        !          1107: describes what the instruction does.
        !          1108: 
        !          1109: RTL is inspired by Lisp lists.  It has both an internal form, made up of
        !          1110: structures that point at other structures, and a textual form that is used
        !          1111: in the machine description and in printed debugging dumps.  The textual
        !          1112: form uses nested parentheses to indicate the pointers in the internal form.
        !          1113: 
        !          1114: 
        !          1115: * Menu:
        !          1116: 
        !          1117: * RTL Objects::       Expressions vs vectors vs strings vs integers.
        !          1118: * Accessors::         Macros to access expression operands or vector elts.
        !          1119: * Flags::             Other flags in an RTL expression.
        !          1120: * Machine Modes::     Describing the size and format of a datum.
        !          1121: * Constants::         Expressions with constant values.
        !          1122: * Regs and Memory::   Expressions representing register contents or memory.
        !          1123: * Arithmetic::        Expressions representing arithmetic on other expressions.
        !          1124: * Comparisons::       Expressions representing comparison of expressions.
        !          1125: * Bit Fields::        Expressions representing bit-fields in memory or reg.
        !          1126: * Conversions::       Extending, truncating, floating or fixing.
        !          1127: * RTL Declarations::  Declaring volatility, constancy, etc.
        !          1128: * Side Effects::      Expressions for storing in registers, etc.
        !          1129: * Incdec::            Embedded side-effects for autoincrement addressing.
        !          1130: * Assembler::        Representing `asm' with operands.
        !          1131: * Insns::             Expression types for entire insns.
        !          1132: * Calls::            RTL representation of function call insns.
        !          1133: * Sharing::           Some expressions are unique; others *must* be copied.
        !          1134: 
        !          1135: 
        !          1136: 
        !          1137: File: internals,  Node: RTL Objects,  Next: Accessors,  Prev: RTL,  Up: RTL
1.1       root     1138: 
1.1.1.2 ! root     1139: RTL Object Types
        !          1140: ================
        !          1141: 
        !          1142: RTL uses four kinds of objects: expressions, integers, strings and vectors.
        !          1143:  Expressions are the most important ones.  An RTL expression (``RTX'', for
        !          1144: short) is a C structure, but it is usually referred to with a pointer; a
        !          1145: type that is given the typedef name `rtx'.
        !          1146: 
        !          1147: An integer is simply an `int', and a string is a `char *'.  Within RTL
        !          1148: code, strings appear only inside `symbol_ref' expressions, but they appear
        !          1149: in other contexts in the RTL expressions that make up machine descriptions.
        !          1150:  Their written form uses decimal digits.
        !          1151: 
        !          1152: A string is a sequence of characters.  In core it is represented as a `char
        !          1153: *' in usual C fashion, and it is written in C syntax as well.  However,
        !          1154: strings in RTL may never be null.  If you write an empty string in a
        !          1155: machine description, it is represented in core as a null pointer rather
        !          1156: than as a pointer to a null character.  In certain contexts, these null
        !          1157: pointers instead of strings are valid.
        !          1158: 
        !          1159: A vector contains an arbitrary, specified number of pointers to
        !          1160: expressions.  The number of elements in the vector is explicitly present in
        !          1161: the vector.  The written form of a vector consists of square brackets
        !          1162: (`[...]') surrounding the elements, in sequence and with whitespace
        !          1163: separating them.  Vectors of length zero are not created; null pointers are
        !          1164: used instead.
        !          1165: 
        !          1166: Expressions are classified by "expression codes" (also called RTX codes). 
        !          1167: The expression code is a name defined in `rtl.def', which is also (in upper
        !          1168: case) a C enumeration constant.  The possible expression codes and their
        !          1169: meanings are machine-independent.  The code of an RTX can be extracted with
        !          1170: the macro `GET_CODE (X)' and altered with `PUT_CODE (X, NEWCODE)'.
        !          1171: 
        !          1172: The expression code determines how many operands the expression contains,
        !          1173: and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
        !          1174: by looking at an operand what kind of object it is.  Instead, you must know
        !          1175: from its context---from the expression code of the containing expression. 
        !          1176: For example, in an expression of code `subreg', the first operand is to be
        !          1177: regarded as an expression and the second operand as an integer.  In an
        !          1178: expression of code `plus', there are two operands, both of which are to be
        !          1179: regarded as expressions.  In a `symbol_ref' expression, there is one
        !          1180: operand, which is to be regarded as a string.
        !          1181: 
        !          1182: Expressions are written as parentheses containing the name of the
        !          1183: expression type, its flags and machine mode if any, and then the operands
        !          1184: of the expression (separated by spaces).
        !          1185: 
        !          1186: Expression code names in the `md' file are written in lower case, but when
        !          1187: they appear in C code they are written in upper case.  In this manual, they
        !          1188: are shown as follows: `const_int'.
        !          1189: 
        !          1190: In a few contexts a null pointer is valid where an expression is normally
        !          1191: wanted.  The written form of this is `(nil)'.
        !          1192: 
        !          1193: 

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