--- gcc/gcc.info-12 2018/04/24 18:18:33 1.1.1.7 +++ gcc/gcc.info-12 2018/04/24 18:42:07 1.1.1.9 @@ -1,13 +1,13 @@ -This is Info file gcc.info, produced by Makeinfo-1.55 from the input -file gcc.texi. +This is Info file gcc.info, produced by Makeinfo version 1.67 from the +input file gcc.texi. This file documents the use and the internals of the GNU compiler. - Published by the Free Software Foundation 675 Massachusetts Avenue -Cambridge, MA 02139 USA + Published by the Free Software Foundation 59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA - Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, -Inc. + Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -30,1131 +30,1081 @@ translations approved by the Free Softwa original English.  -File: gcc.info, Node: Passes, Next: RTL, Prev: Interface, Up: Top +File: gcc.info, Node: Temporaries, Prev: Static Definitions, Up: C++ Misunderstandings -Passes and Files of the Compiler -******************************** +Temporaries May Vanish Before You Expect +---------------------------------------- - The overall control structure of the compiler is in `toplev.c'. This -file is responsible for initialization, decoding arguments, opening and -closing files, and sequencing the passes. - - The parsing pass is invoked only once, to parse the entire input. -The RTL intermediate code for a function is generated as the function -is parsed, a statement at a time. Each statement is read in as a -syntax tree and then converted to RTL; then the storage for the tree -for the statement is reclaimed. Storage for types (and the expressions -for their sizes), declarations, and a representation of the binding -contours and how they nest, remain until the function is finished being -compiled; these are all needed to output the debugging information. - - Each time the parsing pass reads a complete function definition or -top-level declaration, it calls either the function -`rest_of_compilation', or the function `rest_of_decl_compilation' in -`toplev.c', which are responsible for all further processing necessary, -ending with output of the assembler language. All other compiler -passes run, in sequence, within `rest_of_compilation'. When that -function returns from compiling a function definition, the storage used -for that function definition's compilation is entirely freed, unless it -is an inline function (*note An Inline Function is As Fast As a Macro: -Inline.). - - Here is a list of all the passes of the compiler and their source -files. Also included is a description of where debugging dumps can be -requested with `-d' options. - - * Parsing. This pass reads the entire text of a function definition, - constructing partial syntax trees. This and RTL generation are no - longer truly separate passes (formerly they were), but it is - easier to think of them as separate. - - The tree representation does not entirely follow C syntax, because - it is intended to support other languages as well. - - Language-specific data type analysis is also done in this pass, - and every tree node that represents an expression has a data type - attached. Variables are represented as declaration nodes. - - Constant folding and some arithmetic simplifications are also done - during this pass. - - The language-independent source files for parsing are - `stor-layout.c', `fold-const.c', and `tree.c'. There are also - header files `tree.h' and `tree.def' which define the format of - the tree representation. - - The source files to parse C are `c-parse.in', `c-decl.c', - `c-typeck.c', `c-aux-info.c', `c-convert.c', and `c-lang.c' along - with header files `c-lex.h', and `c-tree.h'. - - The source files for parsing C++ are `cp-parse.y', `cp-class.c', - `cp-cvt.c', `cp-decl.c', `cp-decl2.c', `cp-dem.c', `cp-except.c', - `cp-expr.c', `cp-init.c', `cp-lex.c', `cp-method.c', `cp-ptree.c', - `cp-search.c', `cp-tree.c', `cp-type2.c', and `cp-typeck.c', along - with header files `cp-tree.def', `cp-tree.h', and `cp-decl.h'. - - The special source files for parsing Objective C are - `objc-parse.y', `objc-actions.c', `objc-tree.def', and - `objc-actions.h'. Certain C-specific files are used for this as - well. - - The file `c-common.c' is also used for all of the above languages. - - * RTL generation. This is the conversion of syntax tree into RTL - code. It is actually done statement-by-statement during parsing, - but for most purposes it can be thought of as a separate pass. - - This is where the bulk of target-parameter-dependent code is found, - since often it is necessary for strategies to apply only when - certain standard kinds of instructions are available. The purpose - of named instruction patterns is to provide this information to - the RTL generation pass. - - Optimization is done in this pass for `if'-conditions that are - comparisons, boolean operations or conditional expressions. Tail - recursion is detected at this time also. Decisions are made about - how best to arrange loops and how to output `switch' statements. - - The source files for RTL generation include `stmt.c', `calls.c', - `expr.c', `explow.c', `expmed.c', `function.c', `optabs.c' and - `emit-rtl.c'. Also, the file `insn-emit.c', generated from the - machine description by the program `genemit', is used in this - pass. The header file `expr.h' is used for communication within - this pass. - - The header files `insn-flags.h' and `insn-codes.h', generated from - the machine description by the programs `genflags' and `gencodes', - tell this pass which standard names are available for use and - which patterns correspond to them. - - Aside from debugging information output, none of the following - passes refers to the tree structure representation of the function - (only part of which is saved). - - The decision of whether the function can and should be expanded - inline in its subsequent callers is made at the end of rtl - generation. The function must meet certain criteria, currently - related to the size of the function and the types and number of - parameters it has. Note that this function may contain loops, - recursive calls to itself (tail-recursive functions can be - inlined!), gotos, in short, all constructs supported by GNU CC. - The file `integrate.c' contains the code to save a function's rtl - for later inlining and to inline that rtl when the function is - called. The header file `integrate.h' is also used for this - purpose. - - The option `-dr' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.rtl' to - the input file name. - - * Jump optimization. This pass simplifies jumps to the following - instruction, jumps across jumps, and jumps to jumps. It deletes - unreferenced labels and unreachable code, except that unreachable - code that contains a loop is not recognized as unreachable in this - pass. (Such loops are deleted later in the basic block analysis.) - It also converts some code originally written with jumps into - sequences of instructions that directly set values from the - results of comparisons, if the machine has such instructions. - - Jump optimization is performed two or three times. The first time - is immediately following RTL generation. The second time is after - CSE, but only if CSE says repeated jump optimization is needed. - The last time is right before the final pass. That time, - cross-jumping and deletion of no-op move instructions are done - together with the optimizations described above. - - The source file of this pass is `jump.c'. - - The option `-dj' causes a debugging dump of the RTL code after - this pass is run for the first time. This dump file's name is - made by appending `.jump' to the input file name. - - * Register scan. This pass finds the first and last use of each - register, as a guide for common subexpression elimination. Its - source is in `regclass.c'. - - * Jump threading. This pass detects a condition jump that branches - to an identical or inverse test. Such jumps can be `threaded' - through the second conditional test. The source code for this - pass is in `jump.c'. This optimization is only performed if - `-fthread-jumps' is enabled. - - * Common subexpression elimination. This pass also does constant - propagation. Its source file is `cse.c'. If constant propagation - causes conditional jumps to become unconditional or to become - no-ops, jump optimization is run again when CSE is finished. - - The option `-ds' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.cse' to - the input file name. - - * Loop optimization. This pass moves constant expressions out of - loops, and optionally does strength-reduction and loop unrolling - as well. Its source files are `loop.c' and `unroll.c', plus the - header `loop.h' used for communication between them. Loop - unrolling uses some functions in `integrate.c' and the header - `integrate.h'. - - The option `-dL' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.loop' to - the input file name. - - * If `-frerun-cse-after-loop' was enabled, a second common - subexpression elimination pass is performed after the loop - optimization pass. Jump threading is also done again at this time - if it was specified. - - The option `-dt' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.cse2' to - the input file name. - - * Stupid register allocation is performed at this point in a - nonoptimizing compilation. It does a little data flow analysis as - well. When stupid register allocation is in use, the next pass - executed is the reloading pass; the others in between are skipped. - The source file is `stupid.c'. - - * Data flow analysis (`flow.c'). This pass divides the program into - basic blocks (and in the process deletes unreachable loops); then - it computes which pseudo-registers are live at each point in the - program, and makes the first instruction that uses a value point at - the instruction that computed the value. - - This pass also deletes computations whose results are never used, - and combines memory references with add or subtract instructions - to make autoincrement or autodecrement addressing. - - The option `-df' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.flow' to - the input file name. If stupid register allocation is in use, this - dump file reflects the full results of such allocation. - - * Instruction combination (`combine.c'). This pass attempts to - combine groups of two or three instructions that are related by - data flow into single instructions. It combines the RTL - expressions for the instructions by substitution, simplifies the - result using algebra, and then attempts to match the result - against the machine description. - - The option `-dc' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.combine' - to the input file name. - - * Instruction scheduling (`sched.c'). This pass looks for - instructions whose output will not be available by the time that - it is used in subsequent instructions. (Memory loads and floating - point instructions often have this behavior on RISC machines). It - re-orders instructions within a basic block to try to separate the - definition and use of items that otherwise would cause pipeline - stalls. - - Instruction scheduling is performed twice. The first time is - immediately after instruction combination and the second is - immediately after reload. - - The option `-dS' causes a debugging dump of the RTL code after this - pass is run for the first time. The dump file's name is made by - appending `.sched' to the input file name. - - * Register class preferencing. The RTL code is scanned to find out - which register class is best for each pseudo register. The source - file is `regclass.c'. - - * Local register allocation (`local-alloc.c'). This pass allocates - hard registers to pseudo registers that are used only within one - basic block. Because the basic block is linear, it can use fast - and powerful techniques to do a very good job. - - The option `-dl' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.lreg' to - the input file name. - - * Global register allocation (`global.c'). This pass allocates hard - registers for the remaining pseudo registers (those whose life - spans are not contained in one basic block). - - * Reloading. This pass renumbers pseudo registers with the hardware - registers numbers they were allocated. Pseudo registers that did - not get hard registers are replaced with stack slots. Then it - finds instructions that are invalid because a value has failed to - end up in a register, or has ended up in a register of the wrong - kind. It fixes up these instructions by reloading the - problematical values temporarily into registers. Additional - instructions are generated to do the copying. - - The reload pass also optionally eliminates the frame pointer and - inserts instructions to save and restore call-clobbered registers - around calls. - - Source files are `reload.c' and `reload1.c', plus the header - `reload.h' used for communication between them. - - The option `-dg' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.greg' to - the input file name. - - * Instruction scheduling is repeated here to try to avoid pipeline - stalls due to memory loads generated for spilled pseudo registers. - - The option `-dR' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.sched2' - to the input file name. - - * Jump optimization is repeated, this time including cross-jumping - and deletion of no-op move instructions. - - The option `-dJ' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.jump2' to - the input file name. - - * Delayed branch scheduling. This optional pass attempts to find - instructions that can go into the delay slots of other - instructions, usually jumps and calls. The source file name is - `reorg.c'. - - The option `-dd' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.dbr' to - the input file name. - - * Conversion from usage of some hard registers to usage of a register - stack may be done at this point. Currently, this is supported only - for the floating-point registers of the Intel 80387 coprocessor. - The source file name is `reg-stack.c'. - - The options `-dk' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.stack' to - the input file name. - - * Final. This pass outputs the assembler code for the function. It - is also responsible for identifying spurious test and compare - instructions. Machine-specific peephole optimizations are - performed at the same time. The function entry and exit sequences - are generated directly as assembler code in this pass; they never - exist as RTL. - - The source files are `final.c' plus `insn-output.c'; the latter is - generated automatically from the machine description by the tool - `genoutput'. The header file `conditions.h' is used for - communication between these files. - - * Debugging information output. This is run after final because it - must output the stack slot offsets for pseudo registers that did - not get hard registers. Source files are `dbxout.c' for DBX - symbol table format, `sdbout.c' for SDB symbol table format, and - `dwarfout.c' for DWARF symbol table format. - - Some additional files are used by all or many passes: - - * Every pass uses `machmode.def' and `machmode.h' which define the - machine modes. - - * Several passes use `real.h', which defines the default - representation of floating point constants and how to operate on - them. - - * All the passes that work with RTL use the header files `rtl.h' and - `rtl.def', and subroutines in file `rtl.c'. The tools `gen*' also - use these files to read and work with the machine description RTL. - - * Several passes refer to the header file `insn-config.h' which - contains a few parameters (C macro definitions) generated - automatically from the machine description RTL by the tool - `genconfig'. - - * Several passes use the instruction recognizer, which consists of - `recog.c' and `recog.h', plus the files `insn-recog.c' and - `insn-extract.c' that are generated automatically from the machine - description by the tools `genrecog' and `genextract'. - - * Several passes use the header files `regs.h' which defines the - information recorded about pseudo register usage, and - `basic-block.h' which defines the information recorded about basic - blocks. - - * `hard-reg-set.h' defines the type `HARD_REG_SET', a bit-vector - with a bit for each hard register, and some macros to manipulate - it. This type is just `int' if the machine has few enough hard - registers; otherwise it is an array of `int' and some of the - macros expand into loops. - - * Several passes use instruction attributes. A definition of the - attributes defined for a particular machine is in file - `insn-attr.h', which is generated from the machine description by - the program `genattr'. The file `insn-attrtab.c' contains - subroutines to obtain the attribute values for insns. It is - generated from the machine description by the program `genattrtab'. + It is dangerous to use pointers or references to *portions* of a +temporary object. The compiler may very well delete the object before +you expect it to, leaving a pointer to garbage. The most common place +where this problem crops up is in classes like the libg++ `String' +class, that define a conversion function to type `char *' or `const +char *'. However, any class that returns a pointer to some internal +structure is potentially subject to this problem. + + For example, a program may use a function `strfunc' that returns +`String' objects, and another function `charfunc' that operates on +pointers to `char': + + String strfunc (); + void charfunc (const char *); + +In this situation, it may seem natural to write +`charfunc (strfunc ());' based on the knowledge that class `String' has +an explicit conversion to `char' pointers. However, what really +happens is akin to `charfunc (strfunc ().convert ());', where the +`convert' method is a function to do the same data conversion normally +performed by a cast. Since the last use of the temporary `String' +object is the call to the conversion function, the compiler may delete +that object before actually calling `charfunc'. The compiler has no +way of knowing that deleting the `String' object will invalidate the +pointer. The pointer then points to garbage, so that by the time +`charfunc' is called, it gets an invalid argument. + + Code like this may run successfully under some other compilers, +especially those that delete temporaries relatively late. However, the +GNU C++ behavior is also standard-conforming, so if your program depends +on late destruction of temporaries it is not portable. + + If you think this is surprising, you should be aware that the ANSI +C++ committee continues to debate the lifetime-of-temporaries problem. + + For now, at least, the safe way to write such code is to give the +temporary a name, which forces it to remain until the end of the scope +of the name. For example: + + String& tmp = strfunc (); + charfunc (tmp); + + +File: gcc.info, Node: Protoize Caveats, Next: Non-bugs, Prev: C++ Misunderstandings, Up: Trouble + +Caveats of using `protoize' +=========================== + + The conversion programs `protoize' and `unprotoize' can sometimes +change a source file in a way that won't work unless you rearrange it. + + * `protoize' can insert references to a type name or type tag before + the definition, or in a file where they are not defined. + + If this happens, compiler error messages should show you where the + new references are, so fixing the file by hand is straightforward. + + * There are some C constructs which `protoize' cannot figure out. + For example, it can't determine argument types for declaring a + pointer-to-function variable; this you must do by hand. `protoize' + inserts a comment containing `???' each time it finds such a + variable; so you can find all such variables by searching for this + string. ANSI C does not require declaring the argument types of + pointer-to-function types. + + * Using `unprotoize' can easily introduce bugs. If the program + relied on prototypes to bring about conversion of arguments, these + conversions will not take place in the program without prototypes. + One case in which you can be sure `unprotoize' is safe is when you + are removing prototypes that were made with `protoize'; if the + program worked before without any prototypes, it will work again + without them. + + You can find all the places where this problem might occur by + compiling the program with the `-Wconversion' option. It prints a + warning whenever an argument is converted. + + * Both conversion programs can be confused if there are macro calls + in and around the text to be converted. In other words, the + standard syntax for a declaration or definition must not result + from expanding a macro. This problem is inherent in the design of + C and cannot be fixed. If only a few functions have confusing + macro calls, you can easily convert them manually. + + * `protoize' cannot get the argument types for a function whose + definition was not actually compiled due to preprocessing + conditionals. When this happens, `protoize' changes nothing in + regard to such a function. `protoize' tries to detect such + instances and warn about them. + + You can generally work around this problem by using `protoize' step + by step, each time specifying a different set of `-D' options for + compilation, until all of the functions have been converted. + There is no automatic way to verify that you have got them all, + however. + + * Confusion may result if there is an occasion to convert a function + declaration or definition in a region of source code where there + is more than one formal parameter list present. Thus, attempts to + convert code containing multiple (conditionally compiled) versions + of a single function header (in the same vicinity) may not produce + the desired (or expected) results. + + If you plan on converting source files which contain such code, it + is recommended that you first make sure that each conditionally + compiled region of source code which contains an alternative + function header also contains at least one additional follower + token (past the final right parenthesis of the function header). + This should circumvent the problem. + + * `unprotoize' can become confused when trying to convert a function + definition or declaration which contains a declaration for a + pointer-to-function formal argument which has the same name as the + function being defined or declared. We recommand you avoid such + choices of formal parameter names. + + * You might also want to correct some of the indentation by hand and + break long lines. (The conversion programs don't write lines + longer than eighty characters in any case.) + + +File: gcc.info, Node: Non-bugs, Next: Warnings and Errors, Prev: Protoize Caveats, Up: Trouble + +Certain Changes We Don't Want to Make +===================================== + + This section lists changes that people frequently request, but which +we do not make because we think GNU CC is better without them. + + * Checking the number and type of arguments to a function which has + an old-fashioned definition and no prototype. + + Such a feature would work only occasionally--only for calls that + appear in the same file as the called function, following the + definition. The only way to check all calls reliably is to add a + prototype for the function. But adding a prototype eliminates the + motivation for this feature. So the feature is not worthwhile. + + * Warning about using an expression whose type is signed as a shift + count. + + Shift count operands are probably signed more often than unsigned. + Warning about this would cause far more annoyance than good. + + * Warning about assigning a signed value to an unsigned variable. + + Such assignments must be very common; warning about them would + cause more annoyance than good. + + * Warning about unreachable code. + + It's very common to have unreachable code in machine-generated + programs. For example, this happens normally in some files of GNU + C itself. + + * Warning when a non-void function value is ignored. + + Coming as I do from a Lisp background, I balk at the idea that + there is something dangerous about discarding a value. There are + functions that return values which some callers may find useful; + it makes no sense to clutter the program with a cast to `void' + whenever the value isn't useful. + + * Assuming (for optimization) that the address of an external symbol + is never zero. + + This assumption is false on certain systems when `#pragma weak' is + used. + + * Making `-fshort-enums' the default. + + This would cause storage layout to be incompatible with most other + C compilers. And it doesn't seem very important, given that you + can get the same result in other ways. The case where it matters + most is when the enumeration-valued object is inside a structure, + and in that case you can specify a field width explicitly. + + * Making bitfields unsigned by default on particular machines where + "the ABI standard" says to do so. + + The ANSI C standard leaves it up to the implementation whether a + bitfield declared plain `int' is signed or not. This in effect + creates two alternative dialects of C. + + The GNU C compiler supports both dialects; you can specify the + signed dialect with `-fsigned-bitfields' and the unsigned dialect + with `-funsigned-bitfields'. However, this leaves open the + question of which dialect to use by default. + + Currently, the preferred dialect makes plain bitfields signed, + because this is simplest. Since `int' is the same as `signed int' + in every other context, it is cleanest for them to be the same in + bitfields as well. + + Some computer manufacturers have published Application Binary + Interface standards which specify that plain bitfields should be + unsigned. It is a mistake, however, to say anything about this + issue in an ABI. This is because the handling of plain bitfields + distinguishes two dialects of C. Both dialects are meaningful on + every type of machine. Whether a particular object file was + compiled using signed bitfields or unsigned is of no concern to + other object files, even if they access the same bitfields in the + same data structures. + + A given program is written in one or the other of these two + dialects. The program stands a chance to work on most any machine + if it is compiled with the proper dialect. It is unlikely to work + at all if compiled with the wrong dialect. + + Many users appreciate the GNU C compiler because it provides an + environment that is uniform across machines. These users would be + inconvenienced if the compiler treated plain bitfields differently + on certain machines. + + Occasionally users write programs intended only for a particular + machine type. On these occasions, the users would benefit if the + GNU C compiler were to support by default the same dialect as the + other compilers on that machine. But such applications are rare. + And users writing a program to run on more than one type of + machine cannot possibly benefit from this kind of compatibility. + + This is why GNU CC does and will treat plain bitfields in the same + fashion on all types of machines (by default). + + There are some arguments for making bitfields unsigned by default + on all machines. If, for example, this becomes a universal de + facto standard, it would make sense for GNU CC to go along with + it. This is something to be considered in the future. + + (Of course, users strongly concerned about portability should + indicate explicitly in each bitfield whether it is signed or not. + In this way, they write programs which have the same meaning in + both C dialects.) + + * Undefining `__STDC__' when `-ansi' is not used. + + Currently, GNU CC defines `__STDC__' as long as you don't use + `-traditional'. This provides good results in practice. + + Programmers normally use conditionals on `__STDC__' to ask whether + it is safe to use certain features of ANSI C, such as function + prototypes or ANSI token concatenation. Since plain `gcc' supports + all the features of ANSI C, the correct answer to these questions + is "yes". + + Some users try to use `__STDC__' to check for the availability of + certain library facilities. This is actually incorrect usage in + an ANSI C program, because the ANSI C standard says that a + conforming freestanding implementation should define `__STDC__' + even though it does not have the library facilities. `gcc -ansi + -pedantic' is a conforming freestanding implementation, and it is + therefore required to define `__STDC__', even though it does not + come with an ANSI C library. + + Sometimes people say that defining `__STDC__' in a compiler that + does not completely conform to the ANSI C standard somehow + violates the standard. This is illogical. The standard is a + standard for compilers that claim to support ANSI C, such as `gcc + -ansi'--not for other compilers such as plain `gcc'. Whatever the + ANSI C standard says is relevant to the design of plain `gcc' + without `-ansi' only for pragmatic reasons, not as a requirement. + + * Undefining `__STDC__' in C++. + + Programs written to compile with C++-to-C translators get the + value of `__STDC__' that goes with the C compiler that is + subsequently used. These programs must test `__STDC__' to + determine what kind of C preprocessor that compiler uses: whether + they should concatenate tokens in the ANSI C fashion or in the + traditional fashion. + + These programs work properly with GNU C++ if `__STDC__' is defined. + They would not work otherwise. + + In addition, many header files are written to provide prototypes + in ANSI C but not in traditional C. Many of these header files + can work without change in C++ provided `__STDC__' is defined. If + `__STDC__' is not defined, they will all fail, and will all need + to be changed to test explicitly for C++ as well. + + * Deleting "empty" loops. + + GNU CC does not delete "empty" loops because the most likely reason + you would put one in a program is to have a delay. Deleting them + will not make real programs run any faster, so it would be + pointless. + + It would be different if optimization of a nonempty loop could + produce an empty one. But this generally can't happen. + + * Making side effects happen in the same order as in some other + compiler. + + It is never safe to depend on the order of evaluation of side + effects. For example, a function call like this may very well + behave differently from one compiler to another: + + void func (int, int); + + int i = 2; + func (i++, i++); + + There is no guarantee (in either the C or the C++ standard language + definitions) that the increments will be evaluated in any + particular order. Either increment might happen first. `func' + might get the arguments `2, 3', or it might get `3, 2', or even + `2, 2'. + + * Not allowing structures with volatile fields in registers. + + Strictly speaking, there is no prohibition in the ANSI C standard + against allowing structures with volatile fields in registers, but + it does not seem to make any sense and is probably not what you + wanted to do. So the compiler will give an error message in this + case.  -File: gcc.info, Node: RTL, Next: Machine Desc, Prev: Passes, Up: Top +File: gcc.info, Node: Warnings and Errors, Prev: Non-bugs, Up: Trouble + +Warning Messages and Error Messages +=================================== + + The GNU compiler can produce two kinds of diagnostics: errors and +warnings. Each kind has a different purpose: + + *Errors* report problems that make it impossible to compile your + program. GNU CC reports errors with the source file name and line + number where the problem is apparent. + + *Warnings* report other unusual conditions in your code that *may* + indicate a problem, although compilation can (and does) proceed. + Warning messages also report the source file name and line number, + but include the text `warning:' to distinguish them from error + messages. + + Warnings may indicate danger points where you should check to make +sure that your program really does what you intend; or the use of +obsolete features; or the use of nonstandard features of GNU C or C++. +Many warnings are issued only if you ask for them, with one of the `-W' +options (for instance, `-Wall' requests a variety of useful warnings). + + GNU CC always tries to compile your program if possible; it never +gratuitously rejects a program whose meaning is clear merely because +(for instance) it fails to conform to a standard. In some cases, +however, the C and C++ standards specify that certain extensions are +forbidden, and a diagnostic *must* be issued by a conforming compiler. +The `-pedantic' option tells GNU CC to issue warnings in such cases; +`-pedantic-errors' says to make them errors instead. This does not +mean that *all* non-ANSI constructs get warnings or errors. + + *Note Options to Request or Suppress Warnings: Warning Options, for +more detail on these and related command-line options. + + +File: gcc.info, Node: Bugs, Next: Service, Prev: Trouble, Up: Top + +Reporting Bugs +************** -RTL Representation -****************** + Your bug reports play an essential role in making GNU CC reliable. - Most of the work of the compiler is done on an intermediate -representation called register transfer language. In this language, -the instructions to be output are described, pretty much one by one, in -an algebraic form that describes what the instruction does. - - RTL is inspired by Lisp lists. It has both an internal form, made -up of structures that point at other structures, and a textual form -that is used in the machine description and in printed debugging dumps. -The textual form uses nested parentheses to indicate the pointers in -the internal form. + When you encounter a problem, the first thing to do is to see if it +is already known. *Note Trouble::. If it isn't known, then you should +report the problem. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. (If it does not, look in the service directory; see +*Note Service::.) In any case, the principal function of a bug report +is to help the entire community by making the next version of GNU CC +work better. Bug reports are your contribution to the maintenance of +GNU CC. + + Since the maintainers are very overloaded, we cannot respond to every +bug report. However, if the bug has not been fixed, we are likely to +send you a patch and ask you to tell us whether it works. + + In order for a bug report to serve its purpose, you must include the +information that makes for fixing the bug. * Menu: -* RTL Objects:: Expressions vs vectors vs strings vs integers. -* Accessors:: Macros to access expression operands or vector elts. -* Flags:: Other flags in an RTL expression. -* Machine Modes:: Describing the size and format of a datum. -* Constants:: Expressions with constant values. -* Regs and Memory:: Expressions representing register contents or memory. -* Arithmetic:: Expressions representing arithmetic on other expressions. -* Comparisons:: Expressions representing comparison of expressions. -* Bit Fields:: Expressions representing bitfields in memory or reg. -* Conversions:: Extending, truncating, floating or fixing. -* RTL Declarations:: Declaring volatility, constancy, etc. -* Side Effects:: Expressions for storing in registers, etc. -* Incdec:: Embedded side-effects for autoincrement addressing. -* Assembler:: Representing `asm' with operands. -* Insns:: Expression types for entire insns. -* Calls:: RTL representation of function call insns. -* Sharing:: Some expressions are unique; others *must* be copied. -* Reading RTL:: Reading textual RTL from a file. +* Criteria: Bug Criteria. Have you really found a bug? +* Where: Bug Lists. Where to send your bug report. +* Reporting: Bug Reporting. How to report a bug effectively. +* Patches: Sending Patches. How to send a patch for GNU CC. +* Known: Trouble. Known problems. +* Help: Service. Where to ask for help.  -File: gcc.info, Node: RTL Objects, Next: Accessors, Prev: RTL, Up: RTL +File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs -RTL Object Types -================ +Have You Found a Bug? +===================== - RTL uses five kinds of objects: expressions, integers, wide integers, -strings and vectors. Expressions are the most important ones. An RTL -expression ("RTX", for short) is a C structure, but it is usually -referred to with a pointer; a type that is given the typedef name `rtx'. - - An integer is simply an `int'; their written form uses decimal -digits. A wide integer is an integral object whose type is -`HOST_WIDE_INT' (*note Config::.); their written form uses decimal -digits. - - A string is a sequence of characters. In core it is represented as a -`char *' in usual C fashion, and it is written in C syntax as well. -However, strings in RTL may never be null. If you write an empty -string in a machine description, it is represented in core as a null -pointer rather than as a pointer to a null character. In certain -contexts, these null pointers instead of strings are valid. Within RTL -code, strings are most commonly found inside `symbol_ref' expressions, -but they appear in other contexts in the RTL expressions that make up -machine descriptions. - - A vector contains an arbitrary number of pointers to expressions. -The number of elements in the vector is explicitly present in the -vector. The written form of a vector consists of square brackets -(`[...]') surrounding the elements, in sequence and with whitespace -separating them. Vectors of length zero are not created; null pointers -are used instead. - - Expressions are classified by "expression codes" (also called RTX -codes). The expression code is a name defined in `rtl.def', which is -also (in upper case) a C enumeration constant. The possible expression -codes and their meanings are machine-independent. The code of an RTX -can be extracted with the macro `GET_CODE (X)' and altered with -`PUT_CODE (X, NEWCODE)'. - - The expression code determines how many operands the expression -contains, and what kinds of objects they are. In RTL, unlike Lisp, you -cannot tell by looking at an operand what kind of object it is. -Instead, you must know from its context--from the expression code of -the containing expression. For example, in an expression of code -`subreg', the first operand is to be regarded as an expression and the -second operand as an integer. In an expression of code `plus', there -are two operands, both of which are to be regarded as expressions. In -a `symbol_ref' expression, there is one operand, which is to be -regarded as a string. - - Expressions are written as parentheses containing the name of the -expression type, its flags and machine mode if any, and then the -operands of the expression (separated by spaces). - - Expression code names in the `md' file are written in lower case, -but when they appear in C code they are written in upper case. In this -manual, they are shown as follows: `const_int'. + If you are not sure whether you have found a bug, here are some +guidelines: - In a few contexts a null pointer is valid where an expression is -normally wanted. The written form of this is `(nil)'. + * If the compiler gets a fatal signal, for any input whatever, that + is a compiler bug. Reliable compilers never crash. + + * If the compiler produces invalid assembly code, for any input + whatever (except an `asm' statement), that is a compiler bug, + unless the compiler reports errors (not just warnings) which would + ordinarily prevent the assembler from being run. + + * If the compiler produces valid assembly code that does not + correctly execute the input source code, that is a compiler bug. + + However, you must double-check to make sure, because you may have + run into an incompatibility between GNU C and traditional C (*note + Incompatibilities::.). These incompatibilities might be considered + bugs, but they are inescapable consequences of valuable features. + + Or you may have a program whose behavior is undefined, which + happened by chance to give the desired results with another C or + C++ compiler. + + For example, in many nonoptimizing compilers, you can write `x;' + at the end of a function instead of `return x;', with the same + results. But the value of the function is undefined if `return' + is omitted; it is not a bug when GNU CC produces different results. + + Problems often result from expressions with two increment + operators, as in `f (*p++, *p++)'. Your previous compiler might + have interpreted that expression the way you intended; GNU CC might + interpret it another way. Neither compiler is wrong. The bug is + in your code. + + After you have localized the error to a single source line, it + should be easy to check for these things. If your program is + correct and well defined, you have found a compiler bug. + + * If the compiler produces an error message for valid input, that is + a compiler bug. + + * If the compiler does not produce an error message for invalid + input, that is a compiler bug. However, you should note that your + idea of "invalid input" might be my idea of "an extension" or + "support for traditional practice". + + * If you are an experienced user of C or C++ compilers, your + suggestions for improvement of GNU CC or GNU C++ are welcome in + any case.  -File: gcc.info, Node: Accessors, Next: Flags, Prev: RTL Objects, Up: RTL +File: gcc.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs + +Where to Report Bugs +==================== + + Send bug reports for GNU C to `bug-gcc@prep.ai.mit.edu'. -Access to Operands + Send bug reports for GNU C++ to `bug-g++@prep.ai.mit.edu'. If your +bug involves the C++ class library libg++, send mail to +`bug-lib-g++@prep.ai.mit.edu'. If you're not sure, you can send the +bug report to both lists. + + *Do not send bug reports to `help-gcc@prep.ai.mit.edu' or to the +newsgroup `gnu.gcc.help'.* Most users of GNU CC do not want to receive +bug reports. Those that do, have asked to be on `bug-gcc' and/or +`bug-g++'. + + The mailing lists `bug-gcc' and `bug-g++' both have newsgroups which +serve as repeaters: `gnu.gcc.bug' and `gnu.g++.bug'. Each mailing list +and its newsgroup carry exactly the same messages. + + Often people think of posting bug reports to the newsgroup instead of +mailing them. This appears to work, but it has one problem which can be +crucial: a newsgroup posting does not contain a mail path back to the +sender. Thus, if maintainers need more information, they may be unable +to reach you. For this reason, you should always send bug reports by +mail to the proper mailing list. + + As a last resort, send bug reports on paper to: + + GNU Compiler Bugs + Free Software Foundation + 59 Temple Place - Suite 330 + Boston, MA 02111-1307, USA + + +File: gcc.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Bugs + +How to Report Bugs ================== - For each expression type `rtl.def' specifies the number of contained -objects and their kinds, with four possibilities: `e' for expression -(actually a pointer to an expression), `i' for integer, `w' for wide -integer, `s' for string, and `E' for vector of expressions. The -sequence of letters for an expression code is called its "format". -Thus, the format of `subreg' is `ei'. - - A few other format characters are used occasionally: - -`u' - `u' is equivalent to `e' except that it is printed differently in - debugging dumps. It is used for pointers to insns. - -`n' - `n' is equivalent to `i' except that it is printed differently in - debugging dumps. It is used for the line number or code number of - a `note' insn. - -`S' - `S' indicates a string which is optional. In the RTL objects in - core, `S' is equivalent to `s', but when the object is read, from - an `md' file, the string value of this operand may be omitted. An - omitted string is taken to be the null string. - -`V' - `V' indicates a vector which is optional. In the RTL objects in - core, `V' is equivalent to `E', but when the object is read from - an `md' file, the vector value of this operand may be omitted. An - omitted vector is effectively the same as a vector of no elements. - -`0' - `0' means a slot whose contents do not fit any normal category. - `0' slots are not printed at all in dumps, and are often used in - special ways by small parts of the compiler. - - There are macros to get the number of operands, the format, and the -class of an expression code: - -`GET_RTX_LENGTH (CODE)' - Number of operands of an RTX of code CODE. - -`GET_RTX_FORMAT (CODE)' - The format of an RTX of code CODE, as a C string. - -`GET_RTX_CLASS (CODE)' - A single character representing the type of RTX operation that code - CODE performs. - - The following classes are defined: - - `o' - An RTX code that represents an actual object, such as `reg' or - `mem'. `subreg' is not in this class. - - `<' - An RTX code for a comparison. The codes in this class are - `NE', `EQ', `LE', `LT', `GE', `GT', `LEU', `LTU', `GEU', - `GTU'. - - `1' - An RTX code for a unary arithmetic operation, such as `neg'. - - `c' - An RTX code for a commutative binary operation, other than - `NE' and `EQ' (which have class `<'). - - `2' - An RTX code for a noncommutative binary operation, such as - `MINUS'. - - `b' - An RTX code for a bitfield operation, either `ZERO_EXTRACT' or - `SIGN_EXTRACT'. - - `3' - An RTX code for other three input operations, such as - `IF_THEN_ELSE'. - - `i' - An RTX code for a machine insn (`INSN', `JUMP_INSN', and - `CALL_INSN'). - - `m' - An RTX code for something that matches in insns, such as - `MATCH_DUP'. - - `x' - All other RTX codes. - - Operands of expressions are accessed using the macros `XEXP', -`XINT', `XWINT' and `XSTR'. Each of these macros takes two arguments: -an expression-pointer (RTX) and an operand number (counting from zero). -Thus, - - XEXP (X, 2) - -accesses operand 2 of expression X, as an expression. - - XINT (X, 2) - -accesses the same operand as an integer. `XSTR', used in the same -fashion, would access it as a string. - - Any operand can be accessed as an integer, as an expression or as a -string. You must choose the correct method of access for the kind of -value actually stored in the operand. You would do this based on the -expression code of the containing expression. That is also how you -would know how many operands there are. - - For example, if X is a `subreg' expression, you know that it has two -operands which can be correctly accessed as `XEXP (X, 0)' and `XINT (X, -1)'. If you did `XINT (X, 0)', you would get the address of the -expression operand but cast as an integer; that might occasionally be -useful, but it would be cleaner to write `(int) XEXP (X, 0)'. `XEXP -(X, 1)' would also compile without error, and would return the second, -integer operand cast as an expression pointer, which would probably -result in a crash when accessed. Nothing stops you from writing `XEXP -(X, 28)' either, but this will access memory past the end of the -expression with unpredictable results. - - Access to operands which are vectors is more complicated. You can -use the macro `XVEC' to get the vector-pointer itself, or the macros -`XVECEXP' and `XVECLEN' to access the elements and length of a vector. - -`XVEC (EXP, IDX)' - Access the vector-pointer which is operand number IDX in EXP. - -`XVECLEN (EXP, IDX)' - Access the length (number of elements) in the vector which is in - operand number IDX in EXP. This value is an `int'. - -`XVECEXP (EXP, IDX, ELTNUM)' - Access element number ELTNUM in the vector which is in operand - number IDX in EXP. This value is an RTX. - - It is up to you to make sure that ELTNUM is not negative and is - less than `XVECLEN (EXP, IDX)'. - - All the macros defined in this section expand into lvalues and -therefore can be used to assign the operands, lengths and vector -elements as well as to access them. + The fundamental principle of reporting bugs usefully is this: +*report all the facts*. If you are not sure whether to state a fact or +leave it out, state it! + + Often people omit facts because they think they know what causes the +problem and they conclude that some details don't matter. Thus, you +might assume that the name of the variable you use in an example does +not matter. Well, probably it doesn't, but one cannot be sure. +Perhaps the bug is a stray memory reference which happens to fetch from +the location where that name is stored in memory; perhaps, if the name +were different, the contents of that location would fool the compiler +into doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + + Keep in mind that the purpose of a bug report is to enable someone to +fix the bug if it is not known. It isn't very important what happens if +the bug is already known. Therefore, always write your bug reports on +the assumption that the bug is not known. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. You +might as well expedite matters by sending them to begin with. + + Try to make your bug report self-contained. If we have to ask you +for more information, it is best if you include all the previous +information in your response, as well as the information that was +missing. + + Please report each bug in a separate message. This makes it easier +for us to track which bugs have been fixed and to forward your bugs +reports to the appropriate maintainer. + + Do not compress and encode any part of your bug report using programs +such as `uuencode'. If you do so it will slow down the processing of +your bug. If you must submit multiple large files, use `shar', which +allows us to read your message without having to run any decompression +programs. + + To enable someone to investigate the bug, you should include all +these things: + + * The version of GNU CC. You can get this by running it with the + `-v' option. + + Without this, we won't know whether there is any point in looking + for the bug in the current version of GNU CC. + + * A complete input file that will reproduce the bug. If the bug is + in the C preprocessor, send a source file and any header files + that it requires. If the bug is in the compiler proper (`cc1'), + run your source file through the C preprocessor by doing `gcc -E + SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the + bug report. (When you do this, use the same `-I', `-D' or `-U' + options that you used in actual compilation.) + + A single statement is not enough of an example. In order to + compile it, it must be embedded in a complete file of compiler + input; and the bug might depend on the details of how this is done. + + Without a real example one can compile, all anyone can do about + your bug report is wish you luck. It would be futile to try to + guess how to provoke the bug. For example, bugs in register + allocation and reloading frequently depend on every little detail + of the function they happen in. + + Even if the input file that fails comes from a GNU program, you + should still send the complete test case. Don't ask the GNU CC + maintainers to do the extra work of obtaining the program in + question--they are all overworked as it is. Also, the problem may + depend on what is in the header files on your system; it is + unreliable for the GNU CC maintainers to try the problem with the + header files available to them. By sending CPP output, you can + eliminate this source of uncertainty and save us a certain + percentage of wild goose chases. + + * The command arguments you gave GNU CC or GNU C++ to compile that + example and observe the bug. For example, did you use `-O'? To + guarantee you won't omit something important, list all the options. + + If we were to try to guess the arguments, we would probably guess + wrong and then we would not encounter the bug. + + * The type of machine you are using, and the operating system name + and version number. + + * The operands you gave to the `configure' command when you installed + the compiler. + + * A complete list of any modifications you have made to the compiler + source. (We don't promise to investigate the bug unless it + happens in an unmodified compiler. But if you've made + modifications and don't tell us, then you are sending us on a wild + goose chase.) + + Be precise about these changes. A description in English is not + enough--send a context diff for them. + + Adding files of your own (such as a machine description for a + machine we don't support) is a modification of the compiler source. + + * Details of any other deviations from the standard procedure for + installing GNU CC. + + * A description of what behavior you observe that you believe is + incorrect. For example, "The compiler gets a fatal signal," or, + "The assembler instruction at line 208 in the output is incorrect." + + Of course, if the bug is that the compiler gets a fatal signal, + then one can't miss it. But if the bug is incorrect output, the + maintainer might not notice unless it is glaringly wrong. None of + us has time to study all the assembler code from a 50-line C + program just on the chance that one instruction might be wrong. + We need *you* to do this part! + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of the compiler is out of synch, or you have + encountered a bug in the C library on your system. (This has + happened!) Your copy might crash and the copy here would not. If + you said to expect a crash, then when the compiler here fails to + crash, we would know that the bug was not happening. If you don't + say to expect a crash, then we would not know whether the bug was + happening. We would not be able to draw any conclusion from our + observations. + + If the problem is a diagnostic when compiling GNU CC with some + other compiler, say whether it is a warning or an error. + + Often the observed symptom is incorrect output when your program + is run. Sad to say, this is not enough information unless the + program is short and simple. None of us has time to study a large + program to figure out how it would work if compiled correctly, + much less which line of it was compiled wrong. So you will have + to do that. Tell us which source line it is, and what incorrect + result happens when that line is executed. A person who + understands the program can find this as easily as finding a bug + in the program itself. + + * If you send examples of assembler code output from GNU CC or GNU + C++, please use `-g' when you make them. The debugging information + includes source line numbers which are essential for correlating + the output with the input. + + * If you wish to mention something in the GNU CC source, refer to it + by context, not by line number. + + The line numbers in the development sources don't match those in + your sources. Your line numbers would convey no useful + information to the maintainers. + + * Additional information from a debugger might enable someone to + find a problem on a machine which he does not have available. + However, you need to think when you collect this information if + you want it to have any chance of being useful. + + For example, many people send just a backtrace, but that is never + useful by itself. A simple backtrace with arguments conveys little + about GNU CC because the compiler is largely data-driven; the same + functions are called over and over for different RTL insns, doing + different things depending on the details of the insn. + + Most of the arguments listed in the backtrace are useless because + they are pointers to RTL list structure. The numeric values of the + pointers, which the debugger prints in the backtrace, have no + significance whatever; all that matters is the contents of the + objects they point to (and most of the contents are other such + pointers). + + In addition, most compiler passes consist of one or more loops that + scan the RTL insn sequence. The most vital piece of information + about such a loop--which insn it has reached--is usually in a + local variable, not in an argument. + + What you need to provide in addition to a backtrace are the values + of the local variables for several stack frames up. When a local + variable or an argument is an RTX, first print its value and then + use the GDB command `pr' to print the RTL expression that it points + to. (If GDB doesn't run on your machine, use your debugger to call + the function `debug_rtx' with the RTX as an argument.) In + general, whenever a variable is a pointer, its value is no use + without the data it points to. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. You might as well save your time for something else. + + Of course, if you can find a simpler example to report *instead* of + the original one, that is a convenience. Errors in the output + will be easier to spot, running under the debugger will take less + time, etc. Most GNU CC bugs involve just one function, so the + most straightforward way to simplify an example is to delete all + the function definitions except the one where the bug occurs. + Those earlier in the file may be replaced by external declarations + if the crucial function depends on them. (Exception: inline + functions may affect compilation of functions defined later in the + file.) + + However, simplification is not vital; if you don't want to do this, + report the bug anyway and send the entire test case you used. + + * In particular, some people insert conditionals `#ifdef BUG' around + a statement which, if removed, makes the bug not happen. These + are just clutter; we won't pay any attention to them anyway. + Besides, you should send us cpp output, and that can't have + conditionals. + + * A patch for the bug. + + A patch for the bug is useful if it is a good one. But don't omit + the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems + with your patch and decide to fix the problem another way, or we + might not understand it at all. + + Sometimes with a program as complicated as GNU CC it is very hard + to construct an example that will make the program follow a + certain path through the code. If you don't send the example, we + won't be able to construct one, so we won't be able to verify that + the bug is fixed. + + And if we can't understand what bug you are trying to fix, or why + your patch should be an improvement, we won't install it. A test + case will help us to understand. + + *Note Sending Patches::, for guidelines on how to make it easy for + us to understand and install your patches. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even I can't guess right about + such things without first using the debugger to find the facts. + + * A core dump file. + + We have no way of examining a core dump for your type of machine + unless we have an identical system--and if we do have one, we + should be able to reproduce the crash ourselves.  -File: gcc.info, Node: Flags, Next: Machine Modes, Prev: Accessors, Up: RTL +File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs -Flags in an RTL Expression +Sending Patches for GNU CC ========================== - RTL expressions contain several flags (one-bit bitfields) that are -used in certain types of expression. Most often they are accessed with -the following macros: - -`MEM_VOLATILE_P (X)' - In `mem' expressions, nonzero for volatile memory references. - Stored in the `volatil' field and printed as `/v'. - -`MEM_IN_STRUCT_P (X)' - In `mem' expressions, nonzero for reference to an entire - structure, union or array, or to a component of one. Zero for - references to a scalar variable or through a pointer to a scalar. - Stored in the `in_struct' field and printed as `/s'. - -`REG_LOOP_TEST_P' - In `reg' expressions, nonzero if this register's entire life is - contained in the exit test code for some loop. Stored in the - `in_struct' field and printed as `/s'. - -`REG_USERVAR_P (X)' - In a `reg', nonzero if it corresponds to a variable present in the - user's source code. Zero for temporaries generated internally by - the compiler. Stored in the `volatil' field and printed as `/v'. - -`REG_FUNCTION_VALUE_P (X)' - Nonzero in a `reg' if it is the place in which this function's - value is going to be returned. (This happens only in a hard - register.) Stored in the `integrated' field and printed as `/i'. - - The same hard register may be used also for collecting the values - of functions called by this one, but `REG_FUNCTION_VALUE_P' is zero - in this kind of use. - -`SUBREG_PROMOTED_VAR_P' - Nonzero in a `subreg' if it was made when accessing an object that - was promoted to a wider mode in accord with the `PROMOTED_MODE' - machine description macro (*note Storage Layout::.). In this - case, the mode of the `subreg' is the declared mode of the object - and the mode of `SUBREG_REG' is the mode of the register that - holds the object. Promoted variables are always either sign- or - zero-extended to the wider mode on every assignment. Stored in - the `in_struct' field and printed as `/s'. - -`SUBREG_PROMOTED_UNSIGNED_P' - Nonzero in a `subreg' that has `SUBREG_PROMOTED_VAR_P' nonzero if - the object being referenced is kept zero-extended and zero if it - is kept sign-extended. Stored in the `unchanging' field and - printed as `/u'. - -`RTX_UNCHANGING_P (X)' - Nonzero in a `reg' or `mem' if the value is not changed. (This - flag is not set for memory references via pointers to constants. - Such pointers only guarantee that the object will not be changed - explicitly by the current function. The object might be changed by - other functions or by aliasing.) Stored in the `unchanging' field - and printed as `/u'. - -`RTX_INTEGRATED_P (INSN)' - Nonzero in an insn if it resulted from an in-line function call. - Stored in the `integrated' field and printed as `/i'. This may be - deleted; nothing currently depends on it. - -`SYMBOL_REF_USED (X)' - In a `symbol_ref', indicates that X has been used. This is - normally only used to ensure that X is only declared external - once. Stored in the `used' field. - -`SYMBOL_REF_FLAG (X)' - In a `symbol_ref', this is used as a flag for machine-specific - purposes. Stored in the `volatil' field and printed as `/v'. - -`LABEL_OUTSIDE_LOOP_P' - In `label_ref' expressions, nonzero if this is a reference to a - label that is outside the innermost loop containing the reference - to the label. Stored in the `in_struct' field and printed as `/s'. - -`INSN_DELETED_P (INSN)' - In an insn, nonzero if the insn has been deleted. Stored in the - `volatil' field and printed as `/v'. - -`INSN_ANNULLED_BRANCH_P (INSN)' - In an `insn' in the delay slot of a branch insn, indicates that an - annulling branch should be used. See the discussion under - `sequence' below. Stored in the `unchanging' field and printed as - `/u'. - -`INSN_FROM_TARGET_P (INSN)' - In an `insn' in a delay slot of a branch, indicates that the insn - is from the target of the branch. If the branch insn has - `INSN_ANNULLED_BRANCH_P' set, this insn should only be executed if - the branch is taken. For annulled branches with this bit clear, - the insn should be executed only if the branch is not taken. - Stored in the `in_struct' field and printed as `/s'. - -`CONSTANT_POOL_ADDRESS_P (X)' - Nonzero in a `symbol_ref' if it refers to part of the current - function's "constants pool". These are addresses close to the - beginning of the function, and GNU CC assumes they can be addressed - directly (perhaps with the help of base registers). Stored in the - `unchanging' field and printed as `/u'. - -`CONST_CALL_P (X)' - In a `call_insn', indicates that the insn represents a call to a - const function. Stored in the `unchanging' field and printed as - `/u'. - -`LABEL_PRESERVE_P (X)' - In a `code_label', indicates that the label can never be deleted. - Labels referenced by a non-local goto will have this bit set. - Stored in the `in_struct' field and printed as `/s'. - -`SCHED_GROUP_P (INSN)' - During instruction scheduling, in an insn, indicates that the - previous insn must be scheduled together with this insn. This is - used to ensure that certain groups of instructions will not be - split up by the instruction scheduling pass, for example, `use' - insns before a `call_insn' may not be separated from the - `call_insn'. Stored in the `in_struct' field and printed as `/s'. - - These are the fields which the above macros refer to: - -`used' - Normally, this flag is used only momentarily, at the end of RTL - generation for a function, to count the number of times an - expression appears in insns. Expressions that appear more than - once are copied, according to the rules for shared structure - (*note Sharing::.). - - In a `symbol_ref', it indicates that an external declaration for - the symbol has already been written. - - In a `reg', it is used by the leaf register renumbering code to - ensure that each register is only renumbered once. - -`volatil' - This flag is used in `mem', `symbol_ref' and `reg' expressions and - in insns. In RTL dump files, it is printed as `/v'. - - In a `mem' expression, it is 1 if the memory reference is volatile. - Volatile memory references may not be deleted, reordered or - combined. - - In a `symbol_ref' expression, it is used for machine-specific - purposes. - - In a `reg' expression, it is 1 if the value is a user-level - variable. 0 indicates an internal compiler temporary. - - In an insn, 1 means the insn has been deleted. - -`in_struct' - In `mem' expressions, it is 1 if the memory datum referred to is - all or part of a structure or array; 0 if it is (or might be) a - scalar variable. A reference through a C pointer has 0 because - the pointer might point to a scalar variable. This information - allows the compiler to determine something about possible cases of - aliasing. - - In an insn in the delay slot of a branch, 1 means that this insn - is from the target of the branch. - - During instruction scheduling, in an insn, 1 means that this insn - must be scheduled as part of a group together with the previous - insn. - - In `reg' expressions, it is 1 if the register has its entire life - contained within the test expression of some loop. - - In `subreg' expressions, 1 means that the `subreg' is accessing an - object that has had its mode promoted from a wider mode. - - In `label_ref' expressions, 1 means that the referenced label is - outside the innermost loop containing the insn in which the - `label_ref' was found. - - In `code_label' expressions, it is 1 if the label may never be - deleted. This is used for labels which are the target of - non-local gotos. - - In an RTL dump, this flag is represented as `/s'. - -`unchanging' - In `reg' and `mem' expressions, 1 means that the value of the - expression never changes. - - In `subreg' expressions, it is 1 if the `subreg' references an - unsigned object whose mode has been promoted to a wider mode. - - In an insn, 1 means that this is an annulling branch. - - In a `symbol_ref' expression, 1 means that this symbol addresses - something in the per-function constants pool. - - In a `call_insn', 1 means that this instruction is a call to a - const function. - - In an RTL dump, this flag is represented as `/u'. - -`integrated' - In some kinds of expressions, including insns, this flag means the - rtl was produced by procedure integration. - - In a `reg' expression, this flag indicates the register containing - the value to be returned by the current function. On machines - that pass parameters in registers, the same register number may be - used for parameters as well, but this flag is not set on such uses. + If you would like to write bug fixes or improvements for the GNU C +compiler, that is very helpful. Send suggested fixes to the bug report +mailing list, `bug-gcc@prep.ai.mit.edu'. + + Please follow these guidelines so we can study your patches +efficiently. If you don't follow these guidelines, your information +might still be useful, but using it will take extra work. Maintaining +GNU C is a lot of work in the best of circumstances, and we can't keep +up unless you do your best to help. + + * Send an explanation with your changes of what problem they fix or + what improvement they bring about. For a bug fix, just include a + copy of the bug report, and explain why the change fixes the bug. + + (Referring to a bug report is not as good as including it, because + then we will have to look it up, and we have probably already + deleted it if we've already fixed the bug.) + + * Always include a proper bug report for the problem you think you + have fixed. We need to convince ourselves that the change is + right before installing it. Even if it is right, we might have + trouble judging it if we don't have a way to reproduce the problem. + + * Include all the comments that are appropriate to help people + reading the source in the future understand why this change was + needed. + + * Don't mix together changes made for different reasons. Send them + *individually*. + + If you make two changes for separate reasons, then we might not + want to install them both. We might want to install just one. If + you send them all jumbled together in a single set of diffs, we + have to do extra work to disentangle them--to figure out which + parts of the change serve which purpose. If we don't have time + for this, we might have to ignore your changes entirely. + + If you send each change as soon as you have written it, with its + own explanation, then the two changes never get tangled up, and we + can consider each one properly without any extra work to + disentangle them. + + Ideally, each change you send should be impossible to subdivide + into parts that we might want to consider separately, because each + of its parts gets its motivation from the other parts. + + * Send each change as soon as that change is finished. Sometimes + people think they are helping us by accumulating many changes to + send them all together. As explained above, this is absolutely + the worst thing you could do. + + Since you should send each change separately, you might as well + send it right away. That gives us the option of installing it + immediately if it is important. + + * Use `diff -c' to make your diffs. Diffs without context are hard + for us to install reliably. More than that, they make it hard for + us to study the diffs to decide whether we want to install them. + Unidiff format is better than contextless diffs, but not as easy + to read as `-c' format. + + If you have GNU diff, use `diff -cp', which shows the name of the + function that each change occurs in. + + * Write the change log entries for your changes. We get lots of + changes, and we don't have time to do all the change log writing + ourselves. + + Read the `ChangeLog' file to see what sorts of information to put + in, and to learn the style that we use. The purpose of the change + log is to show people where to find what was changed. So you need + to be specific about what functions you changed; in large + functions, it's often helpful to indicate where within the + function the change was. + + On the other hand, once you have shown people where to find the + change, you need not explain its purpose. Thus, if you add a new + function, all you need to say about it is that it is new. If you + feel that the purpose needs explaining, it probably does--but the + explanation will be much more useful if you put it in comments in + the code. + + If you would like your name to appear in the header line for who + made the change, send us the header line. + + * When you write the fix, keep in mind that we can't install a + change that would break other systems. + + People often suggest fixing a problem by changing + machine-independent files such as `toplev.c' to do something + special that a particular system needs. Sometimes it is totally + obvious that such changes would break GNU CC for almost all users. + We can't possibly make a change like that. At best it might tell + us how to write another patch that would solve the problem + acceptably. + + Sometimes people send fixes that *might* be an improvement in + general--but it is hard to be sure of this. It's hard to install + such changes because we have to study them very carefully. Of + course, a good explanation of the reasoning by which you concluded + the change was correct can help convince us. + + The safest changes are changes to the configuration files for a + particular machine. These are safe because they can't create new + bugs on other machines. + + Please help us keep up with the workload by designing the patch in + a form that is good to install. + + +File: gcc.info, Node: Service, Next: VMS, Prev: Bugs, Up: Top + +How To Get Help with GNU CC +*************************** + + If you need help installing, using or changing GNU CC, there are two +ways to find it: + + * Send a message to a suitable network mailing list. First try + `bug-gcc@prep.ai.mit.edu', and if that brings no response, try + `help-gcc@prep.ai.mit.edu'. + + * Look in the service directory for someone who might help you for a + fee. The service directory is found in the file named `SERVICE' + in the GNU CC distribution.  -File: gcc.info, Node: Machine Modes, Next: Constants, Prev: Flags, Up: RTL +File: gcc.info, Node: VMS, Next: Portability, Prev: Service, Up: Top -Machine Modes -============= +Using GNU CC on VMS +******************* - A machine mode describes a size of data object and the -representation used for it. In the C code, machine modes are -represented by an enumeration type, `enum machine_mode', defined in -`machmode.def'. Each RTL expression has room for a machine mode and so -do certain kinds of tree expressions (declarations and types, to be -precise). - - In debugging dumps and machine descriptions, the machine mode of an -RTL expression is written after the expression code with a colon to -separate them. The letters `mode' which appear at the end of each -machine mode name are omitted. For example, `(reg:SI 38)' is a `reg' -expression with machine mode `SImode'. If the mode is `VOIDmode', it -is not written at all. - - Here is a table of machine modes. The term "byte" below refers to an -object of `BITS_PER_UNIT' bits (*note Storage Layout::.). - -`QImode' - "Quarter-Integer" mode represents a single byte treated as an - integer. - -`HImode' - "Half-Integer" mode represents a two-byte integer. - -`PSImode' - "Partial Single Integer" mode represents an integer which occupies - four bytes but which doesn't really use all four. On some - machines, this is the right mode to use for pointers. - -`SImode' - "Single Integer" mode represents a four-byte integer. - -`PDImode' - "Partial Double Integer" mode represents an integer which occupies - eight bytes but which doesn't really use all eight. On some - machines, this is the right mode to use for certain pointers. - -`DImode' - "Double Integer" mode represents an eight-byte integer. - -`TImode' - "Tetra Integer" (?) mode represents a sixteen-byte integer. - -`SFmode' - "Single Floating" mode represents a single-precision (four byte) - floating point number. - -`DFmode' - "Double Floating" mode represents a double-precision (eight byte) - floating point number. - -`XFmode' - "Extended Floating" mode represents a triple-precision (twelve - byte) floating point number. This mode is used for IEEE extended - floating point. - -`TFmode' - "Tetra Floating" mode represents a quadruple-precision (sixteen - byte) floating point number. - -`CCmode' - "Condition Code" mode represents the value of a condition code, - which is a machine-specific set of bits used to represent the - result of a comparison operation. Other machine-specific modes - may also be used for the condition code. These modes are not used - on machines that use `cc0' (see *note Condition Code::.). - -`BLKmode' - "Block" mode represents values that are aggregates to which none of - the other modes apply. In RTL, only memory references can have - this mode, and only if they appear in string-move or vector - instructions. On machines which have no such instructions, - `BLKmode' will not appear in RTL. - -`VOIDmode' - Void mode means the absence of a mode or an unspecified mode. For - example, RTL expressions of code `const_int' have mode `VOIDmode' - because they can be taken to have whatever mode the context - requires. In debugging dumps of RTL, `VOIDmode' is expressed by - the absence of any mode. - -`SCmode, DCmode, XCmode, TCmode' - These modes stand for a complex number represented as a pair of - floating point values. The floating point values are in `SFmode', - `DFmode', `XFmode', and `TFmode', respectively. - -`CQImode, CHImode, CSImode, CDImode, CTImode, COImode' - These modes stand for a complex number represented as a pair of - integer values. The integer values are in `QImode', `HImode', - `SImode', `DImode', `TImode', and `OImode', respectively. - - The machine description defines `Pmode' as a C macro which expands -into the machine mode used for addresses. Normally this is the mode -whose size is `BITS_PER_WORD', `SImode' on 32-bit machines. - - The only modes which a machine description must support are -`QImode', and the modes corresponding to `BITS_PER_WORD', -`FLOAT_TYPE_SIZE' and `DOUBLE_TYPE_SIZE'. The compiler will attempt to -use `DImode' for 8-byte structures and unions, but this can be -prevented by overriding the definition of `MAX_FIXED_MODE_SIZE'. -Alternatively, you can have the compiler use `TImode' for 16-byte -structures and unions. Likewise, you can arrange for the C type `short -int' to avoid using `HImode'. - - Very few explicit references to machine modes remain in the compiler -and these few references will soon be removed. Instead, the machine -modes are divided into mode classes. These are represented by the -enumeration type `enum mode_class' defined in `machmode.h'. The -possible mode classes are: - -`MODE_INT' - Integer modes. By default these are `QImode', `HImode', `SImode', - `DImode', and `TImode'. - -`MODE_PARTIAL_INT' - The "partial integer" modes, `PSImode' and `PDImode'. - -`MODE_FLOAT' - floating point modes. By default these are `SFmode', `DFmode', - `XFmode' and `TFmode'. - -`MODE_COMPLEX_INT' - Complex integer modes. (These are not currently implemented). - -`MODE_COMPLEX_FLOAT' - Complex floating point modes. By default these are `SCmode', - `DCmode', `XCmode', and `TCmode'. - -`MODE_FUNCTION' - Algol or Pascal function variables including a static chain. - (These are not currently implemented). - -`MODE_CC' - Modes representing condition code values. These are `CCmode' plus - any modes listed in the `EXTRA_CC_MODES' macro. *Note Jump - Patterns::, also see *Note Condition Code::. - -`MODE_RANDOM' - This is a catchall mode class for modes which don't fit into the - above classes. Currently `VOIDmode' and `BLKmode' are in - `MODE_RANDOM'. - - Here are some C macros that relate to machine modes: - -`GET_MODE (X)' - Returns the machine mode of the RTX X. - -`PUT_MODE (X, NEWMODE)' - Alters the machine mode of the RTX X to be NEWMODE. - -`NUM_MACHINE_MODES' - Stands for the number of machine modes available on the target - machine. This is one greater than the largest numeric value of any - machine mode. - -`GET_MODE_NAME (M)' - Returns the name of mode M as a string. - -`GET_MODE_CLASS (M)' - Returns the mode class of mode M. - -`GET_MODE_WIDER_MODE (M)' - Returns the next wider natural mode. For example, the expression - `GET_MODE_WIDER_MODE (QImode)' returns `HImode'. - -`GET_MODE_SIZE (M)' - Returns the size in bytes of a datum of mode M. - -`GET_MODE_BITSIZE (M)' - Returns the size in bits of a datum of mode M. - -`GET_MODE_MASK (M)' - Returns a bitmask containing 1 for all bits in a word that fit - within mode M. This macro can only be used for modes whose - bitsize is less than or equal to `HOST_BITS_PER_INT'. - -`GET_MODE_ALIGNMENT (M))' - Return the required alignment, in bits, for an object of mode M. - -`GET_MODE_UNIT_SIZE (M)' - Returns the size in bytes of the subunits of a datum of mode M. - This is the same as `GET_MODE_SIZE' except in the case of complex - modes. For them, the unit size is the size of the real or - imaginary part. - -`GET_MODE_NUNITS (M)' - Returns the number of units contained in a mode, i.e., - `GET_MODE_SIZE' divided by `GET_MODE_UNIT_SIZE'. - -`GET_CLASS_NARROWEST_MODE (C)' - Returns the narrowest mode in mode class C. - - The global variables `byte_mode' and `word_mode' contain modes whose -classes are `MODE_INT' and whose bitsizes are either `BITS_PER_UNIT' or -`BITS_PER_WORD', respectively. On 32-bit machines, these are `QImode' -and `SImode', respectively. + Here is how to use GNU CC on VMS. + +* Menu: + +* Include Files and VMS:: Where the preprocessor looks for the include files. +* Global Declarations:: How to do globaldef, globalref and globalvalue with + GNU CC. +* VMS Misc:: Misc information.  -File: gcc.info, Node: Constants, Next: Regs and Memory, Prev: Machine Modes, Up: RTL +File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS -Constant Expression Types -========================= +Include Files and VMS +===================== - The simplest RTL expressions are those that represent constant -values. + Due to the differences between the filesystems of Unix and VMS, GNU +CC attempts to translate file names in `#include' into names that VMS +will understand. The basic strategy is to prepend a prefix to the +specification of the include file, convert the whole filename to a VMS +filename, and then try to open the file. GNU CC tries various prefixes +one by one until one of them succeeds: + + 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is + where GNU C header files are traditionally stored. If you wish to + store header files in non-standard locations, then you can assign + the logical `GNU_CC_INCLUDE' to be a search list, where each + element of the list is suitable for use with a rooted logical. + + 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where + VAX-C header files are traditionally stored. + + 3. If the include file specification by itself is a valid VMS + filename, the preprocessor then uses this name with no prefix in + an attempt to open the include file. + + 4. If the file specification is not a valid VMS filename (i.e. does + not contain a device or a directory specifier, and contains a `/' + character), the preprocessor tries to convert it from Unix syntax + to VMS syntax. + + Conversion works like this: the first directory name becomes a + device, and the rest of the directories are converted into + VMS-format directory names. For example, the name `X11/foobar.h' + is translated to `X11:[000000]foobar.h' or `X11:foobar.h', + whichever one can be opened. This strategy allows you to assign a + logical name to point to the actual location of the header files. + + 5. If none of these strategies succeeds, the `#include' fails. + + Include directives of the form: + + #include foobar + +are a common source of incompatibility between VAX-C and GNU CC. VAX-C +treats this much like a standard `#include ' directive. That +is incompatible with the ANSI C behavior implemented by GNU CC: to +expand the name `foobar' as a macro. Macro expansion should eventually +yield one of the two standard formats for `#include': + + #include "FILE" + #include + + If you have this problem, the best solution is to modify the source +to convert the `#include' directives to one of the two standard forms. +That will work with either compiler. If you want a quick and dirty fix, +define the file names as macros with the proper expansion, like this: + + #define stdio + +This will work, as long as the name doesn't conflict with anything else +in the program. + + Another source of incompatibility is that VAX-C assumes that: + + #include "foobar" + +is actually asking for the file `foobar.h'. GNU CC does not make this +assumption, and instead takes what you ask for literally; it tries to +read the file `foobar'. The best way to avoid this problem is to +always specify the desired file extension in your include directives. + + GNU CC for VMS is distributed with a set of include files that is +sufficient to compile most general purpose programs. Even though the +GNU CC distribution does not contain header files to define constants +and structures for some VMS system-specific functions, there is no +reason why you cannot use GNU CC with any of these functions. You first +may have to generate or create header files, either by using the public +domain utility `UNSDL' (which can be found on a DECUS tape), or by +extracting the relevant modules from one of the system macro libraries, +and using an editor to construct a C header file. + + A `#include' file name cannot contain a DECNET node name. The +preprocessor reports an I/O error if you attempt to use a node name, +whether explicitly, or implicitly via a logical name. + + +File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS -`(const_int I)' - This type of expression represents the integer value I. I is - customarily accessed with the macro `INTVAL' as in `INTVAL (EXP)', - which is equivalent to `XWINT (EXP, 0)'. - - There is only one expression object for the integer value zero; it - is the value of the variable `const0_rtx'. Likewise, the only - expression for integer value one is found in `const1_rtx', the only - expression for integer value two is found in `const2_rtx', and the - only expression for integer value negative one is found in - `constm1_rtx'. Any attempt to create an expression of code - `const_int' and value zero, one, two or negative one will return - `const0_rtx', `const1_rtx', `const2_rtx' or `constm1_rtx' as - appropriate. - - Similarly, there is only one object for the integer whose value is - `STORE_FLAG_VALUE'. It is found in `const_true_rtx'. If - `STORE_FLAG_VALUE' is one, `const_true_rtx' and `const1_rtx' will - point to the same object. If `STORE_FLAG_VALUE' is -1, - `const_true_rtx' and `constm1_rtx' will point to the same object. - -`(const_double:M ADDR I0 I1 ...)' - Represents either a floating-point constant of mode M or an - integer constant too large to fit into `HOST_BITS_PER_WIDE_INT' - bits but small enough to fit within twice that number of bits (GNU - CC does not provide a mechanism to represent even larger - constants). In the latter case, M will be `VOIDmode'. - - ADDR is used to contain the `mem' expression that corresponds to - the location in memory that at which the constant can be found. If - it has not been allocated a memory location, but is on the chain - of all `const_double' expressions in this compilation (maintained - using an undisplayed field), ADDR contains `const0_rtx'. If it is - not on the chain, ADDR contains `cc0_rtx'. ADDR is customarily - accessed with the macro `CONST_DOUBLE_MEM' and the chain field via - `CONST_DOUBLE_CHAIN'. - - If M is `VOIDmode', the bits of the value are stored in I0 and I1. - I0 is customarily accessed with the macro `CONST_DOUBLE_LOW' and - I1 with `CONST_DOUBLE_HIGH'. - - If the constant is floating point (regardless of its precision), - then the number of integers used to store the value depends on the - size of `REAL_VALUE_TYPE' (*note Cross-compilation::.). The - integers represent a floating point number, but not precisely in - the target machine's or host machine's floating point format. To - convert them to the precise bit pattern used by the target - machine, use the macro `REAL_VALUE_TO_TARGET_DOUBLE' and friends - (*note Data Output::.). - - The macro `CONST0_RTX (MODE)' refers to an expression with value 0 - in mode MODE. If mode MODE is of mode class `MODE_INT', it - returns `const0_rtx'. Otherwise, it returns a `CONST_DOUBLE' - expression in mode MODE. Similarly, the macro `CONST1_RTX (MODE)' - refers to an expression with value 1 in mode MODE and similarly - for `CONST2_RTX'. - -`(const_string STR)' - Represents a constant string with value STR. Currently this is - used only for insn attributes (*note Insn Attributes::.) since - constant strings in C are placed in memory. - -`(symbol_ref:MODE SYMBOL)' - Represents the value of an assembler label for data. SYMBOL is a - string that describes the name of the assembler label. If it - starts with a `*', the label is the rest of SYMBOL not including - the `*'. Otherwise, the label is SYMBOL, usually prefixed with - `_'. - - The `symbol_ref' contains a mode, which is usually `Pmode'. - Usually that is the only mode for which a symbol is directly valid. - -`(label_ref LABEL)' - Represents the value of an assembler label for code. It contains - one operand, an expression, which must be a `code_label' that - appears in the instruction sequence to identify the place where - the label should go. - - The reason for using a distinct expression type for code label - references is so that jump optimization can distinguish them. - -`(const:M EXP)' - Represents a constant that is the result of an assembly-time - arithmetic computation. The operand, EXP, is an expression that - contains only constants (`const_int', `symbol_ref' and `label_ref' - expressions) combined with `plus' and `minus'. However, not all - combinations are valid, since the assembler cannot do arbitrary - arithmetic on relocatable symbols. - - M should be `Pmode'. - -`(high:M EXP)' - Represents the high-order bits of EXP, usually a `symbol_ref'. - The number of bits is machine-dependent and is normally the number - of bits specified in an instruction that initializes the high - order bits of a register. It is used with `lo_sum' to represent - the typical two-instruction sequence used in RISC machines to - reference a global memory location. +Global Declarations and VMS +=========================== - M should be `Pmode'. + GNU CC does not provide the `globalref', `globaldef' and +`globalvalue' keywords of VAX-C. You can get the same effect with an +obscure feature of GAS, the GNU assembler. (This requires GAS version +1.39 or later.) The following macros allow you to use this feature in +a fairly natural way: + + #ifdef __GNUC__ + #define GLOBALREF(TYPE,NAME) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) + #define GLOBALDEF(TYPE,NAME,VALUE) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ + = VALUE + #define GLOBALVALUEREF(TYPE,NAME) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) + #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ + = {VALUE} + #else + #define GLOBALREF(TYPE,NAME) \ + globalref TYPE NAME + #define GLOBALDEF(TYPE,NAME,VALUE) \ + globaldef TYPE NAME = VALUE + #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + globalvalue TYPE NAME = VALUE + #define GLOBALVALUEREF(TYPE,NAME) \ + globalvalue TYPE NAME + #endif + +(The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name +is removed by the assembler, after it has modified the attributes of +the symbol). These macros are provided in the VMS binaries +distribution in a header file `GNU_HACKS.H'. An example of the usage +is: + + GLOBALREF (int, ijk); + GLOBALDEF (int, jkl, 0); + + The macros `GLOBALREF' and `GLOBALDEF' cannot be used +straightforwardly for arrays, since there is no way to insert the array +dimension into the declaration at the right place. However, you can +declare an array with these macros if you first define a typedef for the +array type, like this: + + typedef int intvector[10]; + GLOBALREF (intvector, foo); + + Array and structure initializers will also break the macros; you can +define the initializer to be a macro of its own, or you can expand the +`GLOBALDEF' macro by hand. You may find a case where you wish to use +the `GLOBALDEF' macro with a large array, but you are not interested in +explicitly initializing each element of the array. In such cases you +can use an initializer like: `{0,}', which will initialize the entire +array to `0'. + + A shortcoming of this implementation is that a variable declared with +`GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, +the declaration: + + GLOBALVALUEREF(int, ijk); + +declares the variable `ijk' as an array of type `int [1]'. This is +done because a globalvalue is actually a constant; its "value" is what +the linker would normally consider an address. That is not how an +integer value works in C, but it is how an array works. So treating +the symbol as an array name gives consistent results--with the +exception that the value seems to have the wrong type. *Don't try to +access an element of the array.* It doesn't have any elements. The +array "address" may not be the address of actual storage. + + The fact that the symbol is an array may lead to warnings where the +variable is used. Insert type casts to avoid the warnings. Here is an +example; it takes advantage of the ANSI C feature allowing macros that +expand to use the same name as the macro itself. + + GLOBALVALUEREF (int, ss$_normal); + GLOBALVALUEDEF (int, xyzzy,123); + #ifdef __GNUC__ + #define ss$_normal ((int) ss$_normal) + #define xyzzy ((int) xyzzy) + #endif + + Don't use `globaldef' or `globalref' with a variable whose type is +an enumeration type; this is not implemented. Instead, make the +variable an integer, and use a `globalvaluedef' for each of the +enumeration values. An example of this would be: + + #ifdef __GNUC__ + GLOBALDEF (int, color, 0); + GLOBALVALUEDEF (int, RED, 0); + GLOBALVALUEDEF (int, BLUE, 1); + GLOBALVALUEDEF (int, GREEN, 3); + #else + enum globaldef color {RED, BLUE, GREEN = 3}; + #endif