![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to gcc.info-4 CVS log | Up to [GCC 1.x] / gcc |
1.1 root 1: Info file gcc.info, produced by Makeinfo, -*- Text -*- from input
2: file gcc.texinfo.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
1.1.1.2 root 6: Copyright (C) 1988, 1989 Free Software Foundation, Inc.
1.1 root 7:
8: Permission is granted to make and distribute verbatim copies of this
9: manual provided the copyright notice and this permission notice are
10: preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of
13: this manual under the conditions for verbatim copying, provided also
1.1.1.3 ! root 14: that the sections entitled ``GNU General Public License'' and
! 15: ``Protect Your Freedom--Fight `Look And Feel''' are included exactly
! 16: as in the original, and provided that the entire resulting derived
! 17: work is distributed under the terms of a permission notice identical
! 18: to this one.
1.1 root 19:
20: Permission is granted to copy and distribute translations of this
21: manual into another language, under the above conditions for modified
1.1.1.3 ! root 22: versions, except that the sections entitled ``GNU General Public
! 23: License'' and ``Protect Your Freedom--Fight `Look And Feel''' and
! 24: this permission notice may be included in translations approved by
! 25: the Free Software Foundation instead of in the original English.
! 26:
1.1 root 27:
1.1.1.2 root 28:
1.1.1.3 ! root 29: File: gcc.info, Node: Function Attributes, Next: Dollar Signs, Prev: Constructors, Up: Extensions
! 30:
! 31: Declaring Attributes of Functions
! 32: =================================
! 33:
! 34: In GNU C, you declare certain things about functions called in your
! 35: program which help the compiler optimize function calls.
! 36:
! 37: A few functions, such as `abort' and `exit', cannot return. These
! 38: functions should be declared `volatile'. For example,
! 39:
! 40: extern volatile void abort ();
! 41:
! 42: tells the compiler that it can assume that `abort' will not return.
! 43: This makes slightly better code, but more importantly it helps avoid
! 44: spurious warnings of uninitialized variables.
1.1.1.2 root 45:
1.1.1.3 ! root 46: Many functions do not examine any values except their arguments, and
! 47: have no effects except the return value. Such a function can be
! 48: subject to common subexpression elimination and loop optimization
! 49: just as an arithmetic operator would be. These functions should be
! 50: declared `const'. For example,
1.1.1.2 root 51:
1.1.1.3 ! root 52: extern const void square ();
1.1.1.2 root 53:
1.1.1.3 ! root 54: says that the hypothetical function `square' is safe to call fewer
! 55: times than the program says.
! 56:
! 57: Note that a function that has pointer arguments and examines the data
! 58: pointed to must *not* be declared `const'. Likewise, a function that
! 59: calls a non-`const' function must not be `const'.
! 60:
! 61: Some people object to this feature, claiming that ANSI C's `#pragma'
! 62: should be used instead. There are two reasons I did not do this.
! 63:
! 64: 1. It is impossible to generate `#pragma' commands from a macro.
! 65:
! 66: 2. The `#pragma' command is just as likely as these keywords to
! 67: mean something else in another compiler.
! 68:
! 69: These two reasons apply to *any* application whatever: as far as I
! 70: can see, `#pragma' is never useful.
1.1.1.2 root 71:
72:
73:
1.1.1.3 ! root 74: File: gcc.info, Node: Dollar Signs, Next: Alignment, Prev: Function Attributes, Up: Extensions
1.1.1.2 root 75:
1.1.1.3 ! root 76: Dollar Signs in Identifier Names
! 77: ================================
! 78:
! 79: In GNU C, you may use dollar signs in identifier names. This is
! 80: because many traditional C implementations allow such identifiers.
1.1.1.2 root 81:
1.1.1.3 ! root 82: Dollar signs are allowed if you specify `-traditional'; they are not
! 83: allowed if you specify `-ansi'. Whether they are allowed by default
! 84: depends on the target machine; usually, they are not.
1.1.1.2 root 85:
86:
87:
1.1.1.3 ! root 88: File: gcc.info, Node: Alignment, Next: Inline, Prev: Dollar Signs, Up: Extensions
1.1.1.2 root 89:
1.1.1.3 ! root 90: Inquiring about the Alignment of a Type or Variable
! 91: ===================================================
1.1.1.2 root 92:
1.1.1.3 ! root 93: The keyword `__alignof__' allows you to inquire about how an object
! 94: is aligned, or the minimum alignment usually required by a type. Its
! 95: syntax is just like `sizeof'.
! 96:
! 97: For example, if the target machine requires a `double' value to be
! 98: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8.
! 99: This is true on many RISC machines. On more traditional machine
! 100: designs, `__alignof__ (double)' is 4 or even 2.
! 101:
! 102: Some machines never actually require alignment; they allow reference
! 103: to any data type even at an odd addresses. For these machines,
! 104: `__alignof__' reports the *recommended* alignment of a type.
! 105:
! 106: When the operand of `__alignof__' is an lvalue rather than a type,
! 107: the value is the largest alignment that the lvalue is known to have.
! 108: It may have this alignment as a result of its data type, or because
! 109: it is part of a structure and inherits alignment from that structure.
! 110: For example, after this declaration:
! 111:
! 112: struct foo { int x; char y; } foo1;
! 113:
! 114: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
! 115: `__alignof__ (int)', even though the data type of `foo1.y' does not
! 116: itself demand any alignment.
1.1.1.2 root 117:
118:
119:
1.1.1.3 ! root 120: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: Extensions
! 121:
! 122: An Inline Function is As Fast As a Macro
! 123: ========================================
! 124:
! 125: By declaring a function `inline', you can direct GNU CC to integrate
! 126: that function's code into the code for its callers. This makes
! 127: execution faster by eliminating the function-call overhead; in
! 128: addition, if any of the actual argument values are constant, their
! 129: known values may permit simplifications at compile time so that not
! 130: all of the inline function's code needs to be included.
1.1.1.2 root 131:
1.1.1.3 ! root 132: To declare a function inline, use the `inline' keyword in its
! 133: declaration, like this:
1.1.1.2 root 134:
1.1.1.3 ! root 135: inline int
! 136: inc (int *a)
! 137: {
! 138: (*a)++;
! 139: }
! 140:
! 141: (If you are writing a header file to be included in ANSI C programs,
! 142: write `__inline__' instead of `inline'. *Note Alternate Keywords::.)
! 143:
! 144: You can also make all ``simple enough'' functions inline with the
! 145: option `-finline-functions'. Note that certain usages in a function
! 146: definition can make it unsuitable for inline substitution.
! 147:
! 148: When a function is both inline and `static', if all calls to the
! 149: function are integrated into the caller, and the function's address
! 150: is never used, then the function's own assembler code is never
! 151: referenced. In this case, GNU CC does not actually output assembler
! 152: code for the function, unless you specify the option
! 153: `-fkeep-inline-functions'. Some calls cannot be integrated for
! 154: various reasons (in particular, calls that precede the function's
! 155: definition cannot be integrated, and neither can recursive calls
! 156: within the definition). If there is a nonintegrated call, then the
! 157: function is compiled to assembler code as usual. The function must
! 158: also be compiled as usual if the program refers to its address,
! 159: because that can't be inlined.
! 160:
! 161: When an inline function is not `static', then the compiler must
! 162: assume that there may be calls from other source files; since a
! 163: global symbol can be defined only once in any program, the function
! 164: must not be defined in the other source files, so the calls therein
! 165: cannot be integrated. Therefore, a non-`static' inline function is
! 166: always compiled on its own in the usual fashion.
! 167:
! 168: If you specify both `inline' and `extern' in the function definition,
! 169: then the definition is used only for inlining. In no case is the
! 170: function compiled on its own, not even if you refer to its address
! 171: explicitly. Such an address becomes an external reference, as if you
! 172: had only declared the function, and had not defined it.
! 173:
! 174: This combination of `inline' and `extern' has almost the effect of a
! 175: macro. The way to use it is to put a function definition in a header
! 176: file with these keywords, and put another copy of the definition
! 177: (lacking `inline' and `extern') in a library file. The definition in
! 178: the header file will cause most calls to the function to be inlined.
! 179: If any uses of the function remain, they will refer to the single
! 180: copy in the library.
1.1.1.2 root 181:
182:
183:
1.1.1.3 ! root 184: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: Extensions
! 185:
! 186: Assembler Instructions with C Expression Operands
! 187: =================================================
! 188:
! 189: In an assembler instruction using `asm', you can now specify the
! 190: operands of the instruction using C expressions. This means no more
! 191: guessing which registers or memory locations will contain the data
! 192: you want to use.
! 193:
! 194: You must specify an assembler instruction template much like what
! 195: appears in a machine description, plus an operand constraint string
! 196: for each operand.
! 197:
! 198: For example, here is how to use the 68881's `fsinx' instruction:
! 199:
! 200: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
! 201:
! 202: Here `angle' is the C expression for the input operand while `result'
! 203: is that of the output operand. Each has `"f"' as its operand
! 204: constraint, saying that a floating-point register is required. The
! 205: `=' in `=f' indicates that the operand is an output; all output
! 206: operands' constraints must use `='. The constraints use the same
! 207: language used in the machine description (*note Constraints::.).
! 208:
! 209: Each operand is described by an operand-constraint string followed by
! 210: the C expression in parentheses. A colon separates the assembler
! 211: template from the first output operand, and another separates the
! 212: last output operand from the first input, if any. Commas separate
! 213: output operands and separate inputs. The total number of operands is
! 214: limited to the maximum number of operands in any instruction pattern
! 215: in the machine description.
! 216:
! 217: If there are no output operands, and there are input operands, then
! 218: there must be two consecutive colons surrounding the place where the
! 219: output operands would go.
! 220:
! 221: Output operand expressions must be lvalues; the compiler can check
! 222: this. The input operands need not be lvalues. The compiler cannot
! 223: check whether the operands have data types that are reasonable for
! 224: the instruction being executed. It does not parse the assembler
! 225: instruction template and does not know what it means, or whether it
! 226: is valid assembler input. The extended `asm' feature is most often
! 227: used for machine instructions that the compiler itself does not know
! 228: exist.
! 229:
! 230: The output operands must be write-only; GNU CC will assume that the
! 231: values in these operands before the instruction are dead and need not
! 232: be generated. Extended asm does not support input-output or
! 233: read-write operands. For this reason, the constraint character `+',
! 234: which indicates such an operand, may not be used.
! 235:
! 236: When the assembler instruction has a read-write operand, or an
! 237: operand in which only some of the bits are to be changed, you must
! 238: logically split its function into two separate operands, one input
! 239: operand and one write-only output operand. The connection between
! 240: them is expressed by constraints which say they need to be in the
! 241: same location when the instruction executes. You can use the same C
! 242: expression for both operands, or different expressions. For example,
! 243: here we write the (fictitious) `combine' instruction with `bar' as
! 244: its read-only source operand and `foo' as its read-write destination:
! 245:
! 246: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
! 247:
! 248: The constraint `"0"' for operand 1 says that it must occupy the same
! 249: location as operand 0. A digit in constraint is allowed only in an
! 250: input operand, and it must refer to an output operand.
! 251:
! 252: Only a digit in the constraint can guarantee that one operand will be
! 253: in the same place as another. The mere fact that `foo' is the value
! 254: of both operands is not enough to guarantee that they will be in the
! 255: same place in the generated assembler code. The following would not
! 256: work:
! 257:
! 258: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
! 259:
! 260: Various optimizations or reloading could cause operands 0 and 1 to be
! 261: in different registers; GNU CC knows no reason not to do so. For
! 262: example, the compiler might find a copy of the value of `foo' in one
! 263: register and use it for operand 1, but generate the output operand 0
! 264: in a different register (copying it afterward to `foo''s own
! 265: address). Of course, since the register for operand 1 is not even
! 266: mentioned in the assembler code, the result will not work, but GNU CC
! 267: can't tell that.
! 268:
! 269: Unless an output operand has the `&' constraint modifier, GNU CC may
! 270: allocate it in the same register as an unrelated input operand, on
! 271: the assumption that the inputs are consumed before the outputs are
! 272: produced. This assumption may be false if the assembler code
! 273: actually consists of more than one instruction. In such a case, use
! 274: `&' for each output operand that may not overlap an input. *Note
! 275: Modifiers::.
! 276:
! 277: Some instructions clobber specific hard registers. To describe this,
! 278: write a third colon after the input operands, followed by the names
! 279: of the clobbered hard registers (given as strings). Here is a
! 280: realistic example for the vax:
! 281:
! 282: asm volatile ("movc3 %0,%1,%2"
! 283: : /* no outputs */
! 284: : "g" (from), "g" (to), "g" (count)
! 285: : "r0", "r1", "r2", "r3", "r4", "r5");
! 286:
! 287: You can put multiple assembler instructions together in a single
! 288: `asm' template, separated either with newlines (written as `\n') or
! 289: with semicolons if the assembler allows such semicolons. The GNU
! 290: assembler allows semicolons and all Unix assemblers seem to do so.
! 291: The input operands are guaranteed not to use any of the clobbered
! 292: registers, and neither will the output operands' addresses, so you
! 293: can read and write the clobbered registers as many times as you like.
! 294: Here is an example of multiple instructions in a template; it assumes
! 295: that the subroutine `_foo' accepts arguments in registers 9 and 10:
! 296:
! 297: asm ("movl %0,r9;movl %1,r10;call _foo"
! 298: : /* no outputs */
! 299: : "g" (from), "g" (to)
! 300: : "r9", "r10");
! 301:
! 302: If you want to test the condition code produced by an assembler
! 303: instruction, you must include a branch and a label in the `asm'
! 304: construct, as follows:
! 305:
! 306: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
! 307: : "g" (result)
! 308: : "g" (input));
! 309:
! 310: This assumes your assembler supports local labels, as the GNU
! 311: assembler and most Unix assemblers do.
! 312:
! 313: Usually the most convenient way to use these `asm' instructions is to
! 314: encapsulate them in macros that look like functions. For example,
! 315:
! 316: #define sin(x) \
! 317: ({ double __value, __arg = (x); \
! 318: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
! 319: __value; })
! 320:
! 321: Here the variable `__arg' is used to make sure that the instruction
! 322: operates on a proper `double' value, and to accept only those
! 323: arguments `x' which can convert automatically to a `double'.
! 324:
! 325: Another way to make sure the instruction operates on the correct data
! 326: type is to use a cast in the `asm'. This is different from using a
! 327: variable `__arg' in that it converts more different types. For
! 328: example, if the desired type were `int', casting the argument to
! 329: `int' would accept a pointer with no complaint, while assigning the
! 330: argument to an `int' variable named `__arg' would warn about using a
! 331: pointer unless the caller explicitly casts it.
1.1.1.2 root 332:
1.1.1.3 ! root 333: If an `asm' has output operands, GNU CC assumes for optimization
! 334: purposes that the instruction has no side effects except to change
! 335: the output operands. This does not mean that instructions with a
! 336: side effect cannot be used, but you must be careful, because the
! 337: compiler may eliminate them if the output operands aren't used, or
! 338: move them out of loops, or replace two with one if they constitute a
! 339: common subexpression. Also, if your instruction does have a side
! 340: effect on a variable that otherwise appears not to change, the old
! 341: value of the variable may be reused later if it happens to be found
! 342: in a register.
1.1.1.2 root 343:
1.1.1.3 ! root 344: You can prevent an `asm' instruction from being deleted, moved or
! 345: combined by writing the keyword `volatile' after the `asm'. For
! 346: example:
1.1.1.2 root 347:
1.1.1.3 ! root 348: #define set_priority(x) \
! 349: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
! 350:
! 351: (However, an instruction without output operands will not be deleted
! 352: or moved, regardless, unless it is unreachable.)
! 353:
! 354: It is a natural idea to look for a way to give access to the
! 355: condition code left by the assembler instruction. However, when we
! 356: attempted to implement this, we found no way to make it work
! 357: reliably. The problem is that output operands might need reloading,
! 358: which would result in additional following ``store'' instructions.
! 359: On most machines, these instructions would alter the condition code
! 360: before there was time to test it. This problem doesn't arise for
! 361: ordinary ``test'' and ``compare'' instructions because they don't
! 362: have any output operands.
! 363:
! 364: If you are writing a header file that should be includable in ANSI C
! 365: programs, write `__asm__' instead of `asm'. *Note Alternate
! 366: Keywords::.
1.1.1.2 root 367:
368:
369:
1.1.1.3 ! root 370: File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: Extensions
! 371:
! 372: Controlling Names Used in Assembler Code
! 373: ========================================
! 374:
! 375: You can specify the name to be used in the assembler code for a C
! 376: function or variable by writing the `asm' (or `__asm__') keyword
! 377: after the declarator as follows:
! 378:
! 379: int foo asm ("myfoo") = 2;
! 380:
! 381: This specifies that the name to be used for the variable `foo' in the
! 382: assembler code should be `myfoo' rather than the usual `_foo'.
1.1.1.2 root 383:
1.1.1.3 ! root 384: On systems where an underscore is normally prepended to the name of a
! 385: C function or variable, this feature allows you to define names for
! 386: the linker that do not start with an underscore.
1.1.1.2 root 387:
1.1.1.3 ! root 388: You cannot use `asm' in this way in a function *definition*; but you
! 389: can get the same effect by writing a declaration for the function
! 390: before its definition and putting `asm' there, like this:
1.1.1.2 root 391:
1.1.1.3 ! root 392: extern func () asm ("FUNC");
! 393:
! 394: func (x, y)
! 395: int x, y;
! 396: ...
! 397:
! 398: It is up to you to make sure that the assembler names you choose do
! 399: not conflict with any other assembler symbols. Also, you must not
! 400: use a register name; that would produce completely invalid assembler
! 401: code. GNU CC does not as yet have the ability to store static
! 402: variables in registers. Perhaps that will be added.
1.1.1.2 root 403:
404:
405:
1.1.1.3 ! root 406: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: Extensions
! 407:
! 408: Variables in Specified Registers
! 409: ================================
! 410:
! 411: GNU C allows you to put a few global variables into specified
! 412: hardware registers. You can also specify the register in which an
! 413: ordinary register variable should be allocated.
! 414:
! 415: * Global register variables reserve registers throughout the
! 416: program. This may be useful in programs such as programming
! 417: language interpreters which have a couple of global variables
! 418: that are accessed very often.
1.1.1.2 root 419:
1.1.1.3 ! root 420: * Local register variables in specific registers do not reserve
! 421: the registers. The compiler's data flow analysis is capable of
! 422: determining where the specified registers contain live values,
! 423: and where they are available for other uses. These local
! 424: variables are sometimes convenient for use with the extended
! 425: `asm' feature (*note Extended Asm::.).
1.1.1.2 root 426:
1.1.1.3 ! root 427: * Menu:
! 428:
! 429: * Global Reg Vars::
! 430: * Local Reg Vars::
1.1.1.2 root 431:
1.1 root 432:
433:
1.1.1.3 ! root 434: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Prev: Explicit Reg Vars, Up: Explicit Reg Vars
1.1 root 435:
1.1.1.3 ! root 436: Defining Global Register Variables
! 437: ----------------------------------
! 438:
! 439: You can define a global register variable in GNU C like this:
1.1 root 440:
1.1.1.3 ! root 441: register int *foo asm ("a5");
1.1 root 442:
1.1.1.3 ! root 443: Here `a5' is the name of the register which should be used. Choose a
! 444: register which is normally saved and restored by function calls on
! 445: your machine, so that library routines will not clobber it.
! 446:
! 447: Naturally the register name is cpu-dependent, so you would need to
! 448: conditionalize your program according to cpu type. The register `a5'
! 449: would be a good choice on a 68000 for a variable of pointer type. On
! 450: machines with register windows, be sure to choose a ``global''
! 451: register that is not affected magically by the function call mechanism.
! 452:
! 453: In addition, operating systems on one type of cpu may differ in how
! 454: they name the registers; then you would need additional conditionals.
! 455: For example, some 68000 operating systems call this register `%a5'.
! 456:
! 457: Eventually there may be a way of asking the compiler to choose a
! 458: register automatically, but first we need to figure out how it should
! 459: choose and how to enable you to guide the choice. No solution is
! 460: evident.
! 461:
! 462: Defining a global register variable in a certain register reserves
! 463: that register entirely for this use, at least within the current
! 464: compilation. The register will not be allocated for any other
! 465: purpose in the functions in the current compilation. The register
! 466: will not be saved and restored by these functions. Stores into this
! 467: register are never deleted even if they would appear to be dead, but
! 468: references may be deleted or moved or simplified.
! 469:
! 470: It is not safe to access the global register variables from signal
! 471: handlers, or from more than one thread of control, because the system
! 472: library routines may temporarily use the register for other things
! 473: (unless you recompile them specially for the task at hand).
! 474:
! 475: It is not safe for one function that uses a global register variable
! 476: to call another such function `foo' by way of a third function `lose'
! 477: that was compiled without knowledge of this variable (i.e. in a
! 478: different source file in which the variable wasn't declared). This
! 479: is because `lose' might save the register and put some other value
! 480: there. For example, you can't expect a global register variable to
! 481: be available in the comparison-function that you pass to `qsort',
! 482: since `qsort' might have put something else in that register. (If
! 483: you are prepared to recompile `qsort' with the same global register
! 484: variable, you can solve this problem.)
! 485:
! 486: If you want to recompile `qsort' or other source files which do not
! 487: actually use your global register variable, so that they will not use
! 488: that register for any other purpose, then it suffices to specify the
! 489: compiler option `-ffixed-REG'. You need not actually add a global
! 490: register declaration to their source code.
! 491:
! 492: A function which can alter the value of a global register variable
! 493: cannot safely be called from a function compiled without this
! 494: variable, because it could clobber the value the caller expects to
! 495: find there on return. Therefore, the function which is the entry
! 496: point into the part of the program that uses the global register
! 497: variable must explicitly save and restore the value which belongs to
! 498: its caller.
! 499:
! 500: On most machines, `longjmp' will restore to each global register
! 501: variable the value it had at the time of the `setjmp'. On some
! 502: machines, however, `longjmp' will not change the value of global
! 503: register variables. To be portable, the function that called
! 504: `setjmp' should make other arrangements to save the values of the
! 505: global register variables, and to restore them in a `longjmp'. This
! 506: way, the the same thing will happen regardless of what `longjmp' does.
! 507:
! 508: All global register variable declarations must precede all function
! 509: definitions. If such a declaration could appear after function
! 510: definitions, the declaration would be too late to prevent the
! 511: register from being used for other purposes in the preceding functions.
! 512:
! 513: Global register variables may not have initial values, because an
! 514: executable file has no means to supply initial contents for a register.
1.1 root 515:
516:
517:
1.1.1.3 ! root 518: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
! 519:
! 520: Specifying Registers for Local Variables
! 521: ----------------------------------------
! 522:
! 523: You can define a local register variable with a specified register
! 524: like this:
! 525:
! 526: register int *foo asm ("a5");
1.1 root 527:
1.1.1.3 ! root 528: Here `a5' is the name of the register which should be used. Note
! 529: that this is the same syntax used for defining global register
! 530: variables, but for a local variable it would appear within a function.
1.1 root 531:
1.1.1.3 ! root 532: Naturally the register name is cpu-dependent, but this is not a
! 533: problem, since specific registers are most often useful with explicit
! 534: assembler instructions (*note Extended Asm::.). Both of these things
! 535: generally require that you conditionalize your program according to
! 536: cpu type.
! 537:
! 538: In addition, operating systems on one type of cpu may differ in how
! 539: they name the registers; then you would need additional conditionals.
! 540: For example, some 68000 operating systems call this register `%a5'.
! 541:
! 542: Eventually there may be a way of asking the compiler to choose a
! 543: register automatically, but first we need to figure out how it should
! 544: choose and how to enable you to guide the choice. No solution is
! 545: evident.
! 546:
! 547: Defining such a register variable does not reserve the register; it
! 548: remains available for other uses in places where flow control
! 549: determines the variable's value is not live. However, these
! 550: registers made unavailable for use in the reload pass. I would not
! 551: be surprised if excessive use of this feature leaves the compiler too
! 552: few available registers to compile certain functions.
1.1 root 553:
554:
555:
1.1.1.3 ! root 556: File: gcc.info, Node: Alternate Keywords, Prev: Explicit Reg Vars, Up: Extensions
! 557:
! 558: Alternate Keywords
! 559: ==================
! 560:
! 561: The option `-traditional' disables certain keywords; `-ansi' disables
! 562: certain others. This causes trouble when you want to use GNU C
! 563: extensions, or ANSI C features, in a general-purpose header file that
! 564: should be usable by all programs, including ANSI C programs and
! 565: traditional ones. The keywords `asm', `typeof' and `inline' cannot
! 566: be used since they won't work in a program compiled with `-ansi',
! 567: while the keywords `const', `volatile', `signed', `typeof' and
! 568: `inline' won't work in a program compiled with `-traditional'.
! 569:
! 570: The way to solve these problems is to put `__' at the beginning and
! 571: end of each problematical keyword. For example, use `__asm__'
! 572: instead of `asm', `__const__' instead of `const', and `__inline__'
! 573: instead of `inline'.
1.1 root 574:
1.1.1.3 ! root 575: Other C compilers won't accept these alternative keywords; if you
! 576: want to compile with another compiler, you can define the alternate
! 577: keywords as macros to replace them with the customary keywords. It
! 578: looks like this:
1.1 root 579:
1.1.1.3 ! root 580: #ifndef __GNUC__
! 581: #define __asm__ asm
! 582: #endif
1.1 root 583:
584:
585:
1.1.1.3 ! root 586: File: gcc.info, Node: Bugs, Next: Portability, Prev: Extensions, Up: Top
1.1 root 587:
1.1.1.3 ! root 588: Reporting Bugs
! 589: **************
1.1 root 590:
1.1.1.3 ! root 591: Your bug reports play an essential role in making GNU CC reliable.
1.1 root 592:
1.1.1.3 ! root 593: Reporting a bug may help you by bringing a solution to your problem,
! 594: or it may not. But in any case the important function of a bug
! 595: report is to help the entire community by making the next version of
! 596: GNU CC work better. Bug reports are your contribution to the
! 597: maintenance of GNU CC.
1.1 root 598:
1.1.1.3 ! root 599: In order for a bug report to serve its purpose, you must include the
! 600: information that makes for fixing the bug.
1.1 root 601:
1.1.1.3 ! root 602: * Menu:
! 603:
! 604: * Criteria: Bug Criteria. Have you really found a bug?
! 605: * Reporting: Bug Reporting. How to report a bug effectively.
! 606:
! 607:
1.1 root 608:
1.1.1.3 ! root 609: File: gcc.info, Node: Bug Criteria, Next: Bug Reporting, Prev: Bugs, Up: Bugs
! 610:
! 611: Have You Found a Bug?
! 612: =====================
! 613:
! 614: If you are not sure whether you have found a bug, here are some
! 615: guidelines:
! 616:
! 617: * If the compiler gets a fatal signal, for any input whatever,
! 618: that is a compiler bug. Reliable compilers never crash.
1.1 root 619:
1.1.1.3 ! root 620: * If the compiler produces invalid assembly code, for any input
! 621: whatever (except an `asm' statement), that is a compiler bug,
! 622: unless the compiler reports errors (not just warnings) which
! 623: would ordinarily prevent the assembler from being run.
1.1 root 624:
1.1.1.3 ! root 625: * If the compiler produces valid assembly code that does not
! 626: correctly execute the input source code, that is a compiler bug.
! 627:
! 628: However, you must double-check to make sure, because you may
! 629: have run into an incompatibility between GNU C and traditional C
! 630: (*note Incompatibilities::.). These incompatibilities might be
! 631: considered bugs, but they are inescapable consequences of
! 632: valuable features.
! 633:
! 634: Or you may have a program whose behavior is undefined, which
! 635: happened by chance to give the desired results with another C
! 636: compiler.
! 637:
! 638: For example, in many nonoptimizing compilers, you can write `x;'
! 639: at the end of a function instead of `return x;', with the same
! 640: results. But the value of the function is undefined if `return'
! 641: is omitted; it is not a bug when GNU CC produces different
! 642: results.
! 643:
! 644: Problems often result from expressions with two increment
! 645: operators, as in `f (*p++, *p++)'. Your previous compiler might
! 646: have interpreted that expression the way you intended; GNU CC
! 647: might interpret it another way. Neither compiler is wrong. The
! 648: bug is in your code.
! 649:
! 650: After you have localized the error to a single source line, it
! 651: should be easy to check for these things. If your program is
! 652: correct and well defined, you have found a compiler bug.
! 653:
! 654: * If the compiler produces an error message for valid input, that
! 655: is a compiler bug.
! 656:
! 657: Note that the following is not valid input, and the error
! 658: message for it is not a bug:
! 659:
! 660: int foo (char);
! 661:
! 662: int
! 663: foo (x)
! 664: char x;
! 665: { ... }
! 666:
! 667: The prototype says to pass a `char', while the definition says
! 668: to pass an `int' and treat the value as a `char'. This is what
! 669: the ANSI standard says, and it makes sense.
! 670:
! 671: * If the compiler does not produce an error message for invalid
! 672: input, that is a compiler bug. However, you should note that
! 673: your idea of ``invalid input'' might be my idea of ``an
! 674: extension'' or ``support for traditional practice''.
! 675:
! 676: * If you are an experienced user of C compilers, your suggestions
! 677: for improvement of GNU CC are welcome in any case.
1.1 root 678:
679:
680:
1.1.1.3 ! root 681: File: gcc.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Bugs
! 682:
! 683: How to Report Bugs
! 684: ==================
1.1 root 685:
1.1.1.3 ! root 686: Send bug reports for GNU C to one of these addresses:
1.1 root 687:
1.1.1.3 ! root 688: [email protected]
! 689: {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gcc
1.1 root 690:
1.1.1.3 ! root 691: *Do not send bug reports to `info-gcc', or to the newsgroup
! 692: `gnu.gcc'.* Most users of GNU CC do not want to receive bug reports.
! 693: Those that do, have asked to be on `bug-gcc'.
! 694:
! 695: The mailing list `bug-gcc' has a newsgroup which serves as a
! 696: repeater. The mailing list and the newsgroup carry exactly the same
! 697: messages. Often people think of posting bug reports to the newsgroup
! 698: instead of mailing them. This appears to work, but it has one
! 699: problem which can be crucial: a newsgroup posting does not contain a
! 700: mail path back to the sender. Thus, if I need to ask for more
! 701: information, I may be unable to reach you. For this reason, it is
! 702: better to send bug reports to the mailing list.
! 703:
! 704: As a last resort, send bug reports on paper to:
! 705:
! 706: GNU Compiler Bugs
! 707: 545 Tech Sq
! 708: Cambridge, MA 02139
! 709:
! 710: The fundamental principle of reporting bugs usefully is this: *report
! 711: all the facts*. If you are not sure whether to state a fact or leave
! 712: it out, state it!
! 713:
! 714: Often people omit facts because they think they know what causes the
! 715: problem and they conclude that some details don't matter. Thus, you
! 716: might assume that the name of the variable you use in an example does
! 717: not matter. Well, probably it doesn't, but one cannot be sure.
! 718: Perhaps the bug is a stray memory reference which happens to fetch
! 719: from the location where that name is stored in memory; perhaps, if
! 720: the name were different, the contents of that location would fool the
! 721: compiler into doing the right thing despite the bug. Play it safe
! 722: and give a specific, complete example. That is the easiest thing for
! 723: you to do, and the most helpful.
! 724:
! 725: Keep in mind that the purpose of a bug report is to enable me to fix
! 726: the bug if it is not known. It isn't very important what happens if
! 727: the bug is already known. Therefore, always write your bug reports
! 728: on the assumption that the bug is not known.
! 729:
! 730: Sometimes people give a few sketchy facts and ask, ``Does this ring a
! 731: bell?'' Those bug reports are useless, and I urge everyone to
! 732: *refuse to respond to them* except to chide the sender to report bugs
! 733: properly.
! 734:
! 735: To enable me to fix the bug, you should include all these things:
! 736:
! 737: * The version of GNU CC. You can get this by running it with the
! 738: `-v' option.
! 739:
! 740: Without this, I won't know whether there is any point in looking
! 741: for the bug in the current version of GNU CC.
! 742:
! 743: * A complete input file that will reproduce the bug. If the bug
! 744: is in the C preprocessor, send me a source file and any header
! 745: files that it requires. If the bug is in the compiler proper
! 746: (`cc1'), run your source file through the C preprocessor by
! 747: doing `gcc -E SOURCEFILE > OUTFILE', then include the contents
! 748: of OUTFILE in the bug report. (Any `-I', `-D' or `-U' options
! 749: that you used in actual compilation should also be used when
! 750: doing this.)
! 751:
! 752: A single statement is not enough of an example. In order to
! 753: compile it, it must be embedded in a function definition; and
! 754: the bug might depend on the details of how this is done.
! 755:
! 756: Without a real example I can compile, all I can do about your
! 757: bug report is wish you luck. It would be futile to try to guess
! 758: how to provoke the bug. For example, bugs in register
! 759: allocation and reloading frequently depend on every little
! 760: detail of the function they happen in.
! 761:
! 762: * The command arguments you gave GNU CC to compile that example
! 763: and observe the bug. For example, did you use `-O'? To
! 764: guarantee you won't omit something important, list them all.
! 765:
! 766: If I were to try to guess the arguments, I would probably guess
! 767: wrong and then I would not encounter the bug.
! 768:
! 769: * The names of the files that you used for `tm.h' and `md' when
! 770: you installed the compiler.
! 771:
! 772: * The type of machine you are using, and the operating system name
! 773: and version number.
! 774:
! 775: * A description of what behavior you observe that you believe is
! 776: incorrect. For example, ``It gets a fatal signal,'' or, ``There
! 777: is an incorrect assembler instruction in the output.''
! 778:
! 779: Of course, if the bug is that the compiler gets a fatal signal,
! 780: then I will certainly notice it. But if the bug is incorrect
! 781: output, I might not notice unless it is glaringly wrong. I
! 782: won't study all the assembler code from a 50-line C program just
! 783: on the off chance that it might be wrong.
! 784:
! 785: Even if the problem you experience is a fatal signal, you should
! 786: still say so explicitly. Suppose something strange is going on,
! 787: such as, your copy of the compiler is out of synch, or you have
! 788: encountered a bug in the C library on your system. (This has
! 789: happened!) Your copy might crash and mine would not. If you
! 790: told me to expect a crash, then when mine fails to crash, I
! 791: would know that the bug was not happening for me. If you had
! 792: not told me to expect a crash, then I would not be able to draw
! 793: any conclusion from my observations.
! 794:
! 795: Often the observed symptom is incorrect output when your program
! 796: is run. Sad to say, this is not enough information for me
! 797: unless the program is short and simple. If you send me a large
! 798: program, I don't have time to figure out how it would work if
! 799: compiled correctly, much less which line of it was compiled
! 800: wrong. So you will have to do that. Tell me which source line
! 801: it is, and what incorrect result happens when that line is
! 802: executed. A person who understands the test program can find
! 803: this as easily as a bug in the program itself.
! 804:
! 805: * If you send me examples of output from GNU CC, please use `-g'
! 806: when you make them. The debugging information includes source
! 807: line numbers which are essential for correlating the output with
! 808: the input.
! 809:
! 810: * If you wish to suggest changes to the GNU CC source, send me
! 811: context diffs. If you even discuss something in the GNU CC
! 812: source, refer to it by context, not by line number.
! 813:
! 814: The line numbers in my development sources don't match those in
! 815: your sources. Your line numbers would convey no useful
! 816: information to me.
! 817:
! 818: * Additional information from a debugger might enable me to find a
! 819: problem on a machine which I do not have available myself.
! 820: However, you need to think when you collect this information if
! 821: you want it to have any chance of being useful.
! 822:
! 823: For example, many people send just a backtrace, but that is
! 824: never useful by itself. A simple backtrace with arguments
! 825: conveys little about GNU CC because the compiler is largely
! 826: data-driven; the same functions are called over and over for
! 827: different RTL insns, doing different things depending on the
! 828: details of the insn.
! 829:
! 830: Most of the arguments listed in the backtrace are useless
! 831: because they are pointers to RTL list structure. The numeric
! 832: values of the pointers, which the debugger prints in the
! 833: backtrace, have no significance whatever; all that matters is
! 834: the contents of the objects they point to (and most of the
! 835: contents are other such pointers).
! 836:
! 837: In addition, most compiler passes consist of one or more loops
! 838: that scan the RTL insn sequence. The most vital piece of
! 839: information about such a loop--which insn it has reached--is
! 840: usually in a local variable, not in an argument.
! 841:
! 842: What you need to provide in addition to a backtrace are the
! 843: values of the local variables for several stack frames up. When
! 844: a local variable or an argument is an RTX, first print its value
! 845: and then use the GDB command `pr' to print the RTL expression
! 846: that it points to. (If GDB doesn't run on your machine, use
! 847: your debugger to call the function `debug_rtx' with the RTX as
! 848: an argument.) In general, whenever a variable is a pointer, its
! 849: value is no use without the data it points to.
! 850:
! 851: In addition, include a debugging dump from just before the pass
! 852: in which the crash happens. Most bugs involve a series of
! 853: insns, not just one.
! 854:
! 855: Here are some things that are not necessary:
! 856:
! 857: * A description of the envelope of the bug.
! 858:
! 859: Often people who encounter a bug spend a lot of time
! 860: investigating which changes to the input file will make the bug
! 861: go away and which changes will not affect it.
! 862:
! 863: This is often time consuming and not very useful, because the
! 864: way I will find the bug is by running a single example under the
! 865: debugger with breakpoints, not by pure deduction from a series
! 866: of examples. I recommend that you save your time for something
! 867: else.
! 868:
! 869: Of course, if you can find a simpler example to report *instead*
! 870: of the original one, that is a convenience for me. Errors in
! 871: the output will be easier to spot, running under the debugger
! 872: will take less time, etc. Most GNU CC bugs involve just one
! 873: function, so the most straightforward way to simplify an example
! 874: is to delete all the function definitions except the one where
! 875: the bug occurs. Those earlier in the file may be replaced by
! 876: external declarations if the crucial function depends on them.
! 877: (Exception: inline functions may affect compilation of functions
! 878: defined later in the file.)
! 879:
! 880: However, simplification is not vital; if you don't want to do
! 881: this, report the bug anyway and send me the entire test case you
! 882: used.
! 883:
! 884: * A patch for the bug.
! 885:
! 886: A patch for the bug does help me if it is a good one. But don't
! 887: omit the necessary information, such as the test case, on the
! 888: assumption that a patch is all I need. I might see problems
! 889: with your patch and decide to fix the problem another way, or I
! 890: might not understand it at all.
! 891:
! 892: Sometimes with a program as complicated as GNU CC it is very
! 893: hard to construct an example that will make the program follow a
! 894: certain path through the code. If you don't send me the
! 895: example, I won't be able to construct one, so I won't be able to
! 896: verify that the bug is fixed.
! 897:
! 898: And if I can't understand what bug you are trying to fix, or why
! 899: your patch should be an improvement, I won't install it. A test
! 900: case will help me to understand.
! 901:
! 902: * A guess about what the bug is or what it depends on.
! 903:
! 904: Such guesses are usually wrong. Even I can't guess right about
! 905: such things without first using the debugger to find the facts.
! 906:
! 907:
! 908:
! 909: File: gcc.info, Node: Portability, Next: Interface, Prev: Bugs, Up: Top
! 910:
! 911: GNU CC and Portability
! 912: **********************
! 913:
! 914: The main goal of GNU CC was to make a good, fast compiler for
! 915: machines in the class that the GNU system aims to run on: 32-bit
! 916: machines that address 8-bit bytes and have several general registers.
! 917: Elegance, theoretical power and simplicity are only secondary.
! 918:
! 919: GNU CC gets most of the information about the target machine from a
! 920: machine description which gives an algebraic formula for each of the
! 921: machine's instructions. This is a very clean way to describe the
! 922: target. But when the compiler needs information that is difficult to
! 923: express in this fashion, I have not hesitated to define an ad-hoc
! 924: parameter to the machine description. The purpose of portability is
! 925: to reduce the total work needed on the compiler; it was not of
! 926: interest for its own sake.
! 927:
! 928: GNU CC does not contain machine dependent code, but it does contain
! 929: code that depends on machine parameters such as endianness (whether
! 930: the most significant byte has the highest or lowest address of the
! 931: bytes in a word) and the availability of autoincrement addressing.
! 932: In the RTL-generation pass, it is often necessary to have multiple
! 933: strategies for generating code for a particular kind of syntax tree,
! 934: strategies that are usable for different combinations of parameters.
! 935: Often I have not tried to address all possible cases, but only the
! 936: common ones or only the ones that I have encountered. As a result, a
! 937: new target may require additional strategies. You will know if this
! 938: happens because the compiler will call `abort'. Fortunately, the new
! 939: strategies can be added in a machine-independent fashion, and will
! 940: affect only the target machines that need them.
! 941:
! 942:
! 943:
! 944: File: gcc.info, Node: Interface, Next: Passes, Prev: Portability, Up: Top
! 945:
! 946: Interfacing to GNU CC Output
! 947: ****************************
! 948:
! 949: GNU CC is normally configured to use the same function calling
! 950: convention normally in use on the target system. This is done with
! 951: the machine-description macros described (*note Machine Macros::.).
! 952:
! 953: However, returning of structure and union values is done differently
! 954: on some target machines. As a result, functions compiled with PCC
! 955: returning such types cannot be called from code compiled with GNU CC,
! 956: and vice versa. This does not cause trouble often because few Unix
! 957: library routines return structures or unions.
! 958:
! 959: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
! 960: long in the same registers used for `int' or `double' return values.
! 961: (GNU CC typically allocates variables of such types in registers
! 962: also.) Structures and unions of other sizes are returned by storing
! 963: them into an address passed by the caller (usually in a register).
! 964: The machine-description macros `STRUCT_VALUE' and
! 965: `STRUCT_INCOMING_VALUE' tell GNU CC where to pass this address.
! 966:
! 967: By contrast, PCC on most target machines returns structures and
! 968: unions of any size by copying the data into an area of static
! 969: storage, and then returning the address of that storage as if it were
! 970: a pointer value. The caller must copy the data from that memory area
! 971: to the place where the value is wanted. This is slower than the
! 972: method used by GNU CC, and fails to be reentrant.
! 973:
! 974: On some target machines, such as RISC machines and the 80386, the
! 975: standard system convention is to pass to the subroutine the address
! 976: of where to return the value. On these machines, GNU CC has been
! 977: configured to be compatible with the standard compiler, when this
! 978: method is used. It may not be compatible for structures of 1, 2, 4
! 979: or 8 bytes.
! 980:
! 981: GNU CC uses the system's standard convention for passing arguments.
! 982: On some machines, the first few arguments are passed in registers; in
! 983: others, all are passed on the stack. It would be possible to use
! 984: registers for argument passing on any machine, and this would
! 985: probably result in a significant speedup. But the result would be
! 986: complete incompatibility with code that follows the standard
! 987: convention. So this change is practical only if you are switching to
! 988: GNU CC as the sole C compiler for the system. We may implement
! 989: register argument passing on certain machines once we have a complete
! 990: GNU system so that we can compile the libraries with GNU CC.
! 991:
! 992: If you use `longjmp', beware of automatic variables. ANSI C says
! 993: that automatic variables that are not declared `volatile' have
! 994: undefined values after a `longjmp'. And this is all GNU CC promises
! 995: to do, because it is very difficult to restore register variables
! 996: correctly, and one of GNU CC's features is that it can put variables
! 997: in registers without your asking it to.
! 998:
! 999: If you want a variable to be unaltered by `longjmp', and you don't
! 1000: want to write `volatile' because old C compilers don't accept it,
! 1001: just take the address of the variable. If a variable's address is
! 1002: ever taken, even if just to compute it and ignore it, then the
! 1003: variable cannot go in a register:
! 1004:
! 1005: {
! 1006: int careful;
! 1007: &careful;
! 1008: ...
! 1009: }
! 1010:
! 1011: Code compiled with GNU CC may call certain library routines. Most of
! 1012: them handle arithmetic for which there are no instructions. This
! 1013: includes multiply and divide on some machines, and floating point
! 1014: operations on any machine for which floating point support is
! 1015: disabled with `-msoft-float'. Some standard parts of the C library,
! 1016: such as `bcopy' or `memcpy', are also called automatically. The
! 1017: usual function call interface is used for calling the library routines.
! 1018:
! 1019: These library routines should be defined in the library `gnulib',
! 1020: which GNU CC automatically searches whenever it links a program. On
! 1021: machines that have multiply and divide instructions, if hardware
! 1022: floating point is in use, normally `gnulib' is not needed, but it is
! 1023: searched just in case.
! 1024:
! 1025: Each arithmetic function is defined in `gnulib.c' to use the
! 1026: corresponding C arithmetic operator. As long as the file is compiled
! 1027: with another C compiler, which supports all the C arithmetic
! 1028: operators, this file will work portably. However, `gnulib.c' does
! 1029: not work if compiled with GNU CC, because each arithmetic function
! 1030: would compile into a call to itself!
1.1 root 1031:
1032:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.