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