--- gcc/gcc.info-10 2018/04/24 17:51:58 1.1.1.2 +++ gcc/gcc.info-10 2018/04/24 18:24:16 1.1.1.8 @@ -1,1156 +1,869 @@ -This is Info file gcc.info, produced by Makeinfo-1.44 from the input +This is Info file gcc.info, produced by Makeinfo-1.55 from the input file gcc.texi. This file documents the use and the internals of the GNU compiler. - Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc. + Published by the Free Software Foundation 59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA - Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. + 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 +preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also -that the section entitled "GNU General Public License" is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. +that the sections entitled "GNU General Public License," "Funding for +Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified -versions, except that the section entitled "GNU General Public -License" and this permission notice may be included in translations -approved by the Free Software Foundation instead of in the original -English. +versions, except that the sections entitled "GNU General Public +License," "Funding for Free Software," and "Protect Your Freedom--Fight +`Look And Feel'", and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English.  -File: gcc.info, Node: Simple Constraints, Next: Multi-Alternative, Prev: Constraints, Up: Constraints +File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: C Extensions + +Controlling Names Used in Assembler Code +======================================== + + You can specify the name to be used in the assembler code for a C +function or variable by writing the `asm' (or `__asm__') keyword after +the declarator as follows: + + int foo asm ("myfoo") = 2; + +This specifies that the name to be used for the variable `foo' in the +assembler code should be `myfoo' rather than the usual `_foo'. + + On systems where an underscore is normally prepended to the name of +a C function or variable, this feature allows you to define names for +the linker that do not start with an underscore. -Simple Constraints ------------------- + You cannot use `asm' in this way in a function *definition*; but you +can get the same effect by writing a declaration for the function +before its definition and putting `asm' there, like this: - The simplest kind of constraint is a string full of letters, each of -which describes one kind of operand that is permitted. Here are the -letters that are allowed: - -`m' - A memory operand is allowed, with any kind of address that the - machine supports in general. - -`o' - A memory operand is allowed, but only if the address is - "offsettable". This means that adding a small integer (actually, - the width in bytes of the operand, as determined by its machine - mode) may be added to the address and the result is also a valid - memory address. - - For example, an address which is constant is offsettable; so is an - address that is the sum of a register and a constant (as long as a - slightly larger constant is also within the range of - address-offsets supported by the machine); but an autoincrement - or autodecrement address is not offsettable. More complicated - indirect/indexed addresses may or may not be offsettable - depending on the other addressing modes that the machine supports. - - Note that in an output operand which can be matched by another - operand, the constraint letter `o' is valid only when accompanied - by both `<' (if the target machine has predecrement addressing) - and `>' (if the target machine has preincrement addressing). - -`V' - A memory operand that is not offsettable. In other words, - anything that would fit the `m' constraint but not the `o' - constraint. - -`<' - A memory operand with autodecrement addressing (either - predecrement or postdecrement) is allowed. - -`>' - A memory operand with autoincrement addressing (either - preincrement or postincrement) is allowed. - -`r' - A register operand is allowed provided that it is in a general - register. - -`d', `a', `f', ... - Other letters can be defined in machine-dependent fashion to - stand for particular classes of registers. `d', `a' and `f' are - defined on the 68000/68020 to stand for data, address and floating - point registers. - -`i' - An immediate integer operand (one with constant value) is allowed. - This includes symbolic constants whose values will be known only - at assembly time. - -`n' - An immediate integer operand with a known numeric value is - allowed. Many systems cannot support assembly-time constants for - operands less than a word wide. Constraints for these operands - should use `n' rather than `i'. - -`I', `J', `K', ... `P' - Other letters in the range `I' through `P' may be defined in a - machine-dependent fashion to permit immediate integer operands - with explicit integer values in specified ranges. For example, - on the 68000, `I' is defined to stand for the range of values 1 - to 8. This is the range permitted as a shift count in the shift - instructions. - -`E' - An immediate floating operand (expression code `const_double') is - allowed, but only if the target floating point format is the same - as that of the host machine (on which the compiler is running). - -`F' - An immediate floating operand (expression code `const_double') is - allowed. - -`G', `H' - `G' and `H' may be defined in a machine-dependent fashion to - permit immediate floating operands in particular ranges of values. - -`s' - An immediate integer operand whose value is not an explicit - integer is allowed. - - This might appear strange; if an insn allows a constant operand - with a value not known at compile time, it certainly must allow - any known value. So why use `s' instead of `i'? Sometimes it - allows better code to be generated. - - For example, on the 68000 in a fullword instruction it is - possible to use an immediate operand; but if the immediate value - is between -128 and 127, better code results from loading the - value into a register and using the register. This is because - the load into the register can be done with a `moveq' - instruction. We arrange for this to happen by defining the - letter `K' to mean "any integer outside the range -128 to 127", - and then specifying `Ks' in the operand constraints. - -`g' - Any register, memory or immediate integer operand is allowed, - except for registers that are not general registers. - -`X' - Any operand whatsoever is allowed, even if it does not satisfy - `general_operand'. This is normally used in the constraint of a - `match_scratch' when certain alternatives will not actually - require a scratch register. - -`0', `1', `2', ... `9' - An operand that matches the specified operand number is allowed. - If a digit is used together with letters within the same - alternative, the digit should come last. - - This is called a "matching constraint" and what it really means is - that the assembler has only a single operand that fills two roles - considered separate in the RTL insn. For example, an add insn - has two input operands and one output operand in the RTL, but on - most machines an add instruction really has only two operands, - one of them an input-output operand. - - Matching constraints work only in circumstances like that add - insn. More precisely, the two operands that match must include - one input-only operand and one output-only operand. Moreover, - the digit must be a smaller number than the number of the operand - that uses it in the constraint. - - For operands to match in a particular case usually means that they - are identical-looking RTL expressions. But in a few special cases - specific kinds of dissimilarity are allowed. For example, `*x' - as an input operand will match `*x++' as an output operand. For - proper results in such cases, the output template should always - use the output-operand's number when printing the operand. - -`p' - An operand that is a valid memory address is allowed. This is - for "load address" and "push address" instructions. - - `p' in the constraint must be accompanied by `address_operand' as - the predicate in the `match_operand'. This predicate interprets - the mode specified in the `match_operand' as the mode of the - memory reference for which the address would be valid. - -`Q', `R', `S', ... `U' - Letters in the range `Q' through `U' may be defined in a - machine-dependent fashion to stand for arbitrary operand types. - The machine description macro `EXTRA_CONSTRAINT' is passed the - operand as its first argument and the constraint letter as its - second operand. - - A typical use for this would be to distinguish certain types of - memory references that affect other insn operands. - - Do not define these constraint letters to accept register - references (`reg'); the reload pass does not expect this and - would not handle it properly. - - In order to have valid assembler code, each operand must satisfy -its constraint. But a failure to do so does not prevent the pattern -from applying to an insn. Instead, it directs the compiler to modify -the code so that the constraint will be satisfied. Usually this is -done by copying an operand into a register. - - Contrast, therefore, the two instruction patterns that follow: - - (define_insn "" - [(set (match_operand:SI 0 "general_operand" "r") - (plus:SI (match_dup 0) - (match_operand:SI 1 "general_operand" "r")))] - "" - "...") - -which has two operands, one of which must appear in two places, and - - (define_insn "" - [(set (match_operand:SI 0 "general_operand" "r") - (plus:SI (match_operand:SI 1 "general_operand" "0") - (match_operand:SI 2 "general_operand" "r")))] - "" - "...") - -which has three operands, two of which are required by a constraint to -be identical. If we are considering an insn of the form - - (insn N PREV NEXT - (set (reg:SI 3) - (plus:SI (reg:SI 6) (reg:SI 109))) - ...) - -the first pattern would not apply at all, because this insn does not -contain two identical subexpressions in the right place. The pattern -would say, "That does not look like an add instruction; try other -patterns." The second pattern would say, "Yes, that's an add -instruction, but there is something wrong with it." It would direct -the reload pass of the compiler to generate additional insns to make -the constraint true. The results might look like this: - - (insn N2 PREV N - (set (reg:SI 3) (reg:SI 6)) - ...) + extern func () asm ("FUNC"); - (insn N N2 NEXT - (set (reg:SI 3) - (plus:SI (reg:SI 3) (reg:SI 109))) - ...) - - It is up to you to make sure that each operand, in each pattern, has -constraints that can handle any RTL expression that could be present -for that operand. (When multiple alternatives are in use, each -pattern must, for each possible combination of operand expressions, -have at least one alternative which can handle that combination of -operands.) The constraints don't need to *allow* any possible -operand--when this is the case, they do not constrain--but they must -at least point the way to reloading any possible operand so that it -will fit. - - * If the constraint accepts whatever operands the predicate permits, - there is no problem: reloading is never necessary for this - operand. - - For example, an operand whose constraints permit everything except - registers is safe provided its predicate rejects registers. - - An operand whose predicate accepts only constant values is safe - provided its constraints include the letter `i'. If any possible - constant value is accepted, then nothing less than `i' will do; - if the predicate is more selective, then the constraints may also - be more selective. - - * Any operand expression can be reloaded by copying it into a - register. So if an operand's constraints allow some kind of - register, it is certain to be safe. It need not permit all - classes of registers; the compiler knows how to copy a register - into another register of the proper class in order to make an - instruction valid. - - * A nonoffsettable memory reference can be reloaded by copying the - address into a register. So if the constraint uses the letter - `o', all memory references are taken care of. - - * A constant operand can be reloaded by allocating space in memory - to hold it as preinitialized data. Then the memory reference can - be used in place of the constant. So if the constraint uses the - letters `o' or `m', constant operands are not a problem. - - * If the constraint permits a constant and a pseudo register used - in an insn was not allocated to a hard register and is equivalent - to a constant, the register will be replaced with the constant. - If the predicate does not permit a constant and the insn is - re-recognized for some reason, the compiler will crash. Thus the - predicate must always recognize any objects allowed by the - constraint. - - If the operand's predicate can recognize registers, but the -constraint does not permit them, it can make the compiler crash. When -this operand happens to be a register, the reload pass will be -stymied, because it does not know how to copy a register temporarily -into memory. + func (x, y) + int x, y; + ... + + It is up to you to make sure that the assembler names you choose do +not conflict with any other assembler symbols. Also, you must not use a +register name; that would produce completely invalid assembler code. +GNU CC does not as yet have the ability to store static variables in +registers. Perhaps that will be added.  -File: gcc.info, Node: Multi-Alternative, Next: Class Preferences, Prev: Simple Constraints, Up: Constraints +File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions -Multiple Alternative Constraints --------------------------------- +Variables in Specified Registers +================================ - Sometimes a single instruction has multiple alternative sets of -possible operands. For example, on the 68000, a logical-or -instruction can combine register or an immediate value into memory, or -it can combine any kind of operand into a register; but it cannot -combine one memory location into another. - - These constraints are represented as multiple alternatives. An -alternative can be described by a series of letters for each operand. -The overall constraint for an operand is made from the letters for -this operand from the first alternative, a comma, the letters for this -operand from the second alternative, a comma, and so on until the last -alternative. Here is how it is done for fullword logical-or on the -68000: - - (define_insn "iorsi3" - [(set (match_operand:SI 0 "general_operand" "=m,d") - (ior:SI (match_operand:SI 1 "general_operand" "%0,0") - (match_operand:SI 2 "general_operand" "dKs,dmKs")))] - ...) - - The first alternative has `m' (memory) for operand 0, `0' for -operand 1 (meaning it must match operand 0), and `dKs' for operand 2. -The second alternative has `d' (data register) for operand 0, `0' for -operand 1, and `dmKs' for operand 2. The `=' and `%' in the -constraints apply to all the alternatives; their meaning is explained -in the next section (*note Class Preferences::.). - - If all the operands fit any one alternative, the instruction is -valid. Otherwise, for each alternative, the compiler counts how many -instructions must be added to copy the operands so that that -alternative applies. The alternative requiring the least copying is -chosen. If two alternatives need the same amount of copying, the one -that comes first is chosen. These choices can be altered with the `?' -and `!' characters: - -`?' - Disparage slightly the alternative that the `?' appears in, as a - choice when no alternative applies exactly. The compiler regards - this alternative as one unit more costly for each `?' that appears - in it. - -`!' - Disparage severely the alternative that the `!' appears in. This - alternative can still be used if it fits without reloading, but - if reloading is needed, some other alternative will be used. - - When an insn pattern has multiple alternatives in its constraints, -often the appearance of the assembler code is determined mostly by -which alternative was matched. When this is so, the C code for -writing the assembler code can use the variable `which_alternative', -which is the ordinal number of the alternative that was actually -satisfied (0 for the first, 1 for the second alternative, etc.). -*Note Output Statement::. + GNU C allows you to put a few global variables into specified +hardware registers. You can also specify the register in which an +ordinary register variable should be allocated. + + * Global register variables reserve registers throughout the program. + This may be useful in programs such as programming language + interpreters which have a couple of global variables that are + accessed very often. + + * Local register variables in specific registers do not reserve the + registers. The compiler's data flow analysis is capable of + determining where the specified registers contain live values, and + where they are available for other uses. + + These local variables are sometimes convenient for use with the + extended `asm' feature (*note Extended Asm::.), if you want to + write one output of the assembler instruction directly into a + particular register. (This will work provided the register you + specify fits the constraints specified for that operand in the + `asm'.) + +* Menu: + +* Global Reg Vars:: +* Local Reg Vars::  -File: gcc.info, Node: Class Preferences, Next: Modifiers, Prev: Multi-Alternative, Up: Constraints +File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars + +Defining Global Register Variables +---------------------------------- -Register Class Preferences --------------------------- + You can define a global register variable in GNU C like this: - The operand constraints have another function: they enable the -compiler to decide which kind of hardware register a pseudo register -is best allocated to. The compiler examines the constraints that -apply to the insns that use the pseudo register, looking for the -machine-dependent letters such as `d' and `a' that specify classes of -registers. The pseudo register is put in whichever class gets the -most "votes". The constraint letters `g' and `r' also vote: they vote -in favor of a general register. The machine description says which -registers are considered general. - - Of course, on some machines all registers are equivalent, and no -register classes are defined. Then none of this complexity is -relevant. + register int *foo asm ("a5"); + +Here `a5' is the name of the register which should be used. Choose a +register which is normally saved and restored by function calls on your +machine, so that library routines will not clobber it. + + Naturally the register name is cpu-dependent, so you would need to +conditionalize your program according to cpu type. The register `a5' +would be a good choice on a 68000 for a variable of pointer type. On +machines with register windows, be sure to choose a "global" register +that is not affected magically by the function call mechanism. + + In addition, operating systems on one type of cpu may differ in how +they name the registers; then you would need additional conditionals. +For example, some 68000 operating systems call this register `%a5'. + + Eventually there may be a way of asking the compiler to choose a +register automatically, but first we need to figure out how it should +choose and how to enable you to guide the choice. No solution is +evident. + + Defining a global register variable in a certain register reserves +that register entirely for this use, at least within the current +compilation. The register will not be allocated for any other purpose +in the functions in the current compilation. The register will not be +saved and restored by these functions. Stores into this register are +never deleted even if they would appear to be dead, but references may +be deleted or moved or simplified. + + It is not safe to access the global register variables from signal +handlers, or from more than one thread of control, because the system +library routines may temporarily use the register for other things +(unless you recompile them specially for the task at hand). + + It is not safe for one function that uses a global register variable +to call another such function `foo' by way of a third function `lose' +that was compiled without knowledge of this variable (i.e. in a +different source file in which the variable wasn't declared). This is +because `lose' might save the register and put some other value there. +For example, you can't expect a global register variable to be +available in the comparison-function that you pass to `qsort', since +`qsort' might have put something else in that register. (If you are +prepared to recompile `qsort' with the same global register variable, +you can solve this problem.) + + If you want to recompile `qsort' or other source files which do not +actually use your global register variable, so that they will not use +that register for any other purpose, then it suffices to specify the +compiler option `-ffixed-REG'. You need not actually add a global +register declaration to their source code. + + A function which can alter the value of a global register variable +cannot safely be called from a function compiled without this variable, +because it could clobber the value the caller expects to find there on +return. Therefore, the function which is the entry point into the part +of the program that uses the global register variable must explicitly +save and restore the value which belongs to its caller. + + On most machines, `longjmp' will restore to each global register +variable the value it had at the time of the `setjmp'. On some +machines, however, `longjmp' will not change the value of global +register variables. To be portable, the function that called `setjmp' +should make other arrangements to save the values of the global register +variables, and to restore them in a `longjmp'. This way, the same +thing will happen regardless of what `longjmp' does. + + All global register variable declarations must precede all function +definitions. If such a declaration could appear after function +definitions, the declaration would be too late to prevent the register +from being used for other purposes in the preceding functions. + + Global register variables may not have initial values, because an +executable file has no means to supply initial contents for a register. + + On the Sparc, there are reports that g3 ... g7 are suitable +registers, but certain library functions, such as `getwd', as well as +the subroutines for division and remainder, modify g3 and g4. g1 and +g2 are local temporaries. + + On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of +course, it will not do to use more than a few of those.  -File: gcc.info, Node: Modifiers, Next: No Constraints, Prev: Class Preferences, Up: Constraints +File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars + +Specifying Registers for Local Variables +---------------------------------------- -Constraint Modifier Characters ------------------------------- + You can define a local register variable with a specified register +like this: -`=' - Means that this operand is write-only for this instruction: the - previous value is discarded and replaced by output data. - -`+' - Means that this operand is both read and written by the - instruction. - - When the compiler fixes up the operands to satisfy the - constraints, it needs to know which operands are inputs to the - instruction and which are outputs from it. `=' identifies an - output; `+' identifies an operand that is both input and output; - all other operands are assumed to be input only. - -`&' - Means (in a particular alternative) that this operand is written - before the instruction is finished using the input operands. - Therefore, this operand may not lie in a register that is used as - an input operand or as part of any memory address. - - `&' applies only to the alternative in which it is written. In - constraints with multiple alternatives, sometimes one alternative - requires `&' while others do not. See, for example, the `movdf' - insn of the 68000. - - `&' does not obviate the need to write `='. - -`%' - Declares the instruction to be commutative for this operand and - the following operand. This means that the compiler may - interchange the two operands if that is the cheapest way to make - all operands fit the constraints. This is often used in patterns - for addition instructions that really have only two operands: the - result must go in one of the arguments. Here for example, is how - the 68000 halfword-add instruction is defined: - - (define_insn "addhi3" - [(set (match_operand:HI 0 "general_operand" "=m,r") - (plus:HI (match_operand:HI 1 "general_operand" "%0,0") - (match_operand:HI 2 "general_operand" "di,g")))] - ...) - -`#' - Says that all following characters, up to the next comma, are to - be ignored as a constraint. They are significant only for - choosing register preferences. - -`*' - Says that the following character should be ignored when choosing - register preferences. `*' has no effect on the meaning of the - constraint as a constraint, and no effect on reloading. - - Here is an example: the 68000 has an instruction to sign-extend a - halfword in a data register, and can also sign-extend a value by - copying it into an address register. While either kind of - register is acceptable, the constraints on an address-register - destination are less strict, so it is best if register allocation - makes an address register its goal. Therefore, `*' is used so - that the `d' constraint letter (for data register) is ignored - when computing register preferences. - - (define_insn "extendhisi2" - [(set (match_operand:SI 0 "general_operand" "=*d,a") - (sign_extend:SI - (match_operand:HI 1 "general_operand" "0,g")))] - ...) + register int *foo asm ("a5"); + +Here `a5' is the name of the register which should be used. Note that +this is the same syntax used for defining global register variables, +but for a local variable it would appear within a function. + + Naturally the register name is cpu-dependent, but this is not a +problem, since specific registers are most often useful with explicit +assembler instructions (*note Extended Asm::.). Both of these things +generally require that you conditionalize your program according to cpu +type. + + In addition, operating systems on one type of cpu may differ in how +they name the registers; then you would need additional conditionals. +For example, some 68000 operating systems call this register `%a5'. + + Eventually there may be a way of asking the compiler to choose a +register automatically, but first we need to figure out how it should +choose and how to enable you to guide the choice. No solution is +evident. + + Defining such a register variable does not reserve the register; it +remains available for other uses in places where flow control determines +the variable's value is not live. However, these registers are made +unavailable for use in the reload pass. I would not be surprised if +excessive use of this feature leaves the compiler too few available +registers to compile certain functions.  -File: gcc.info, Node: No Constraints, Prev: Modifiers, Up: Constraints +File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions -Not Using Constraints ---------------------- +Alternate Keywords +================== - Some machines are so clean that operand constraints are not -required. For example, on the Vax, an operand valid in one context is -valid in any other context. On such a machine, every operand -constraint would be `g', excepting only operands of "load address" -instructions which are written as if they referred to a memory -location's contents but actual refer to its address. They would have -constraint `p'. - - For such machines, instead of writing `g' and `p' for all the -constraints, you can choose to write a description with empty -constraints. Then you write `""' for the constraint in every -`match_operand'. Address operands are identified by writing an -`address' expression around the `match_operand', not by their -constraints. - - When the machine description has just empty constraints, certain -parts of compilation are skipped, making the compiler faster. However, -few machines actually do not need constraints; all machine descriptions -now in existence use constraints. + The option `-traditional' disables certain keywords; `-ansi' +disables certain others. This causes trouble when you want to use GNU C +extensions, or ANSI C features, in a general-purpose header file that +should be usable by all programs, including ANSI C programs and +traditional ones. The keywords `asm', `typeof' and `inline' cannot be +used since they won't work in a program compiled with `-ansi', while +the keywords `const', `volatile', `signed', `typeof' and `inline' won't +work in a program compiled with `-traditional'. + + The way to solve these problems is to put `__' at the beginning and +end of each problematical keyword. For example, use `__asm__' instead +of `asm', `__const__' instead of `const', and `__inline__' instead of +`inline'. + + Other C compilers won't accept these alternative keywords; if you +want to compile with another compiler, you can define the alternate +keywords as macros to replace them with the customary keywords. It +looks like this: + + #ifndef __GNUC__ + #define __asm__ asm + #endif + + `-pedantic' causes warnings for many GNU C extensions. You can +prevent such warnings within one expression by writing `__extension__' +before the expression. `__extension__' has no effect aside from this.  -File: gcc.info, Node: Standard Names, Next: Pattern Ordering, Prev: Constraints, Up: Machine Desc +File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions -Standard Names for Patterns Used in Generation -============================================== +Incomplete `enum' Types +======================= - Here is a table of the instruction names that are meaningful in the -RTL generation pass of the compiler. Giving one of these names to an -instruction pattern tells the RTL generation pass that it can use the -pattern in to accomplish a certain task. - -`movM' - Here M stands for a two-letter machine mode name, in lower case. - This instruction pattern moves data with that machine mode from - operand 1 to operand 0. For example, `movsi' moves full-word - data. - - If operand 0 is a `subreg' with mode M of a register whose own - mode is wider than M, the effect of this instruction is to store - the specified value in the part of the register that corresponds - to mode M. The effect on the rest of the register is undefined. - - This class of patterns is special in several ways. First of all, - each of these names *must* be defined, because there is no other - way to copy a datum from one place to another. - - Second, these patterns are not used solely in the RTL generation - pass. Even the reload pass can generate move insns to copy - values from stack slots into temporary registers. When it does - so, one of the operands is a hard register and the other is an - operand that can need to be reloaded into a register. - - Therefore, when given such a pair of operands, the pattern must - generate RTL which needs no reloading and needs no temporary - registers--no registers other than the operands. For example, if - you support the pattern with a `define_expand', then in such a - case the `define_expand' mustn't call `force_reg' or any other - such function which might generate new pseudo registers. - - This requirement exists even for subword modes on a RISC machine - where fetching those modes from memory normally requires several - insns and some temporary registers. Look in `spur.md' to see how - the requirement can be satisfied. - - During reload a memory reference with an invalid address may be - passed as an operand. Such an address will be replaced with a - valid address later in the reload pass. In this case, nothing - may be done with the address except to use it as it stands. If - it is copied, it will not be replaced with a valid address. No - attempt should be made to make such an address into a valid - address and no routine (such as `change_address') that will do so - may be called. Note that `general_operand' will fail when - applied to such an address. - - The global variable `reload_in_progress' (which must be explicitly - declared if required) can be used to determine whether such - special handling is required. - - The variety of operands that have reloads depends on the rest of - the machine description, but typically on a RISC machine these - can only be pseudo registers that did not get hard registers, - while on other machines explicit memory references will get - optional reloads. - - If a scratch register is required to move an object to or from - memory, it can be allocated using `gen_reg_rtx' prior to reload. - But this is impossible during and after reload. If there are - cases needing scratch registers after reload, you must define - `SECONDARY_INPUT_RELOAD_CLASS' and/or - `SECONDARY_OUTPUT_RELOAD_CLASS' to detect them, and provide - patterns `reload_inM' or `reload_outM' to handle them. *Note - Register Classes::. - - The constraints on a `moveM' must permit moving any hard register - to any other hard register provided that `HARD_REGNO_MODE_OK' - permits mode M in both registers and `REGISTER_MOVE_COST' applied - to their classes returns a value of 2. - - It is obligatory to support floating point `moveM' instructions - into and out of any registers that can hold fixed point values, - because unions and structures (which have modes `SImode' or - `DImode') can be in those registers and they may have floating - point members. - - There may also be a need to support fixed point `moveM' - instructions in and out of floating point registers. - Unfortunately, I have forgotten why this was so, and I don't know - whether it is still true. If `HARD_REGNO_MODE_OK' rejects fixed - point values in floating point registers, then the constraints of - the fixed point `moveM' instructions must be designed to avoid - ever trying to reload into a floating point register. - -`reload_inM' -`reload_outM' - Like `movM', but used when a scratch register is required to move - between operand 0 and operand 1. Operand 2 describes the scratch - register. See the discussion of the `SECONDARY_RELOAD_CLASS' - macro in *note Register Classes::.. - -`movstrictM' - Like `movM' except that if operand 0 is a `subreg' with mode M of - a register whose natural mode is wider, the `movstrictM' - instruction is guaranteed not to alter any of the register except - the part which belongs to mode M. - -`addM3' - Add operand 2 and operand 1, storing the result in operand 0. - All operands must have mode M. This can be used even on - two-address machines, by means of constraints requiring operands - 1 and 0 to be the same location. - -`subM3', `mulM3' -`divM3', `udivM3', `modM3', `umodM3' -`sminM3', `smaxM3', `uminM3', `umaxM3' -`andM3', `iorM3', `xorM3' - Similar, for other arithmetic operations. - -`mulhisi3' - Multiply operands 1 and 2, which have mode `HImode', and store a - `SImode' product in operand 0. - -`mulqihi3', `mulsidi3' - Similar widening-multiplication instructions of other widths. - -`umulqihi3', `umulhisi3', `umulsidi3' - Similar widening-multiplication instructions that do unsigned - multiplication. - -`divmodM4' - Signed division that produces both a quotient and a remainder. - Operand 1 is divided by operand 2 to produce a quotient stored in - operand 0 and a remainder stored in operand 3. - - For machines with an instruction that produces both a quotient - and a remainder, provide a pattern for `divmodM4' but do not - provide patterns for `divM3' and `modM3'. This allows - optimization in the relatively common case when both the quotient - and remainder are computed. - - If an instruction that just produces a quotient or just a - remainder exists and is more efficient than the instruction that - produces both, write the output routine of `divmodM4' to call - `find_reg_note' and look for a `REG_UNUSED' note on the quotient - or remainder and generate the appropriate instruction. - -`udivmodM4' - Similar, but does unsigned division. - -`ashlM3' - Arithmetic-shift operand 1 left by a number of bits specified by - operand 2, and store the result in operand 0. Operand 2 has mode - `SImode', not mode M. - -`ashrM3', `lshlM3', `lshrM3', `rotlM3', `rotrM3' - Other shift and rotate instructions. - - Logical and arithmetic left shift are the same. Machines that do - not allow negative shift counts often have only one instruction - for shifting left. On such machines, you should define a pattern - named `ashlM3' and leave `lshlM3' undefined. - -`negM2' - Negate operand 1 and store the result in operand 0. - -`absM2' - Store the absolute value of operand 1 into operand 0. - -`sqrtM2' - Store the square root of operand 1 into operand 0. - -`ffsM2' - Store into operand 0 one plus the index of the least significant - 1-bit of operand 1. If operand 1 is zero, store zero. M is the - mode of operand 0; operand 1's mode is specified by the - instruction pattern, and the compiler will convert the operand to - that mode before generating the instruction. - -`one_cmplM2' - Store the bitwise-complement of operand 1 into operand 0. - -`cmpM' - Compare operand 0 and operand 1, and set the condition codes. - The RTL pattern should look like this: - - (set (cc0) (compare (match_operand:M 0 ...) - (match_operand:M 1 ...))) - -`tstM' - Compare operand 0 against zero, and set the condition codes. The - RTL pattern should look like this: - - (set (cc0) (match_operand:M 0 ...)) - - `tstM' patterns should not be defined for machines that do not - use `(cc0)'. Doing so would confuse the optimizer since it would - no longer be clear which `set' operations were comparisons. The - `cmpM' patterns should be used instead. - -`movstrM' - Block move instruction. The addresses of the destination and - source strings are the first two operands, and both are in mode - `Pmode'. The number of bytes to move is the third operand, in - mode M. - - The fourth operand is the known shared alignment of the source and - destination, in the form of a `const_int' rtx. Thus, if the - compiler knows that both source and destination are word-aligned, - it may provide the value 4 for this operand. - - These patterns need not give special consideration to the - possibility that the source and destination strings might overlap. - -`cmpstrM' - Block compare instruction, with five operands. Operand 0 is the - output; it has mode M. The remaining four operands are like the - operands of `movstrM'. The two memory blocks specified are - compared byte by byte in lexicographic order. The effect of the - instruction is to store a value in operand 0 whose sign indicates - the result of the comparison. - -`floatMN2' - Convert signed integer operand 1 (valid for fixed point mode M) to - floating point mode N and store in operand 0 (which has mode N). - -`floatunsMN2' - Convert unsigned integer operand 1 (valid for fixed point mode M) - to floating point mode N and store in operand 0 (which has mode - N). - -`fixMN2' - Convert operand 1 (valid for floating point mode M) to fixed - point mode N as a signed number and store in operand 0 (which has - mode N). This instruction's result is defined only when the - value of operand 1 is an integer. - -`fixunsMN2' - Convert operand 1 (valid for floating point mode M) to fixed - point mode N as an unsigned number and store in operand 0 (which - has mode N). This instruction's result is defined only when the - value of operand 1 is an integer. - -`ftruncM2' - Convert operand 1 (valid for floating point mode M) to an integer - value, still represented in floating point mode M, and store it - in operand 0 (valid for floating point mode M). - -`fix_truncMN2' - Like `fixMN2' but works for any floating point value of mode M by - converting the value to an integer. - -`fixuns_truncMN2' - Like `fixunsMN2' but works for any floating point value of mode M - by converting the value to an integer. - -`truncMN' - Truncate operand 1 (valid for mode M) to mode N and store in - operand 0 (which has mode N). Both modes must be fixed point or - both floating point. - -`extendMN' - Sign-extend operand 1 (valid for mode M) to mode N and store in - operand 0 (which has mode N). Both modes must be fixed point or - both floating point. - -`zero_extendMN' - Zero-extend operand 1 (valid for mode M) to mode N and store in - operand 0 (which has mode N). Both modes must be fixed point. - -`extv' - Extract a bit field from operand 1 (a register or memory - operand), where operand 2 specifies the width in bits and operand - 3 the starting bit, and store it in operand 0. Operand 0 must - have mode `word_mode'. Operand 1 may have mode `byte_mode' or - `word_mode'; often `word_mode' is allowed only for registers. - Operands 2 and 3 must be valid for `word_mode'. - - The RTL generation pass generates this instruction only with - constants for operands 2 and 3. - - The bit-field value is sign-extended to a full word integer - before it is stored in operand 0. - -`extzv' - Like `extv' except that the bit-field value is zero-extended. - -`insv' - Store operand 3 (which must be valid for `word_mode') into a bit - field in operand 0, where operand 1 specifies the width in bits - and operand 2 the starting bit. Operand 0 may have mode - `byte_mode' or `word_mode'; often `word_mode' is allowed only for - registers. Operands 1 and 2 must be valid for `word_mode'. - - The RTL generation pass generates this instruction only with - constants for operands 1 and 2. - -`sCOND' - Store zero or nonzero in the operand according to the condition - codes. Value stored is nonzero iff the condition COND is true. - COND is the name of a comparison operation expression code, such - as `eq', `lt' or `leu'. - - You specify the mode that the operand must have when you write the - `match_operand' expression. The compiler automatically sees - which mode you have used and supplies an operand of that mode. - - The value stored for a true condition must have 1 as its low bit, - or else must be negative. Otherwise the instruction is not - suitable and you should omit it from the machine description. - You describe to the compiler exactly which value is stored by - defining the macro `STORE_FLAG_VALUE' (*note Misc::.). If a - description cannot be found that can be used for all the `sCOND' - patterns, you should omit those operations from the machine - description. - - These operations may fail, but should do so only in relatively - uncommon cases; if they would fail for common cases involving - integer comparisons, it is best to omit these patterns. - - If these operations are omitted, the compiler will usually - generate code that copies the constant one to the target and - branches around an assignment of zero to the target. If this - code is more efficient than the potential instructions used for - the `sCOND' pattern followed by those required to convert the - result into a 1 or a zero in `SImode', you should omit the - `sCOND' operations from the machine description. - -`bCOND' - Conditional branch instruction. Operand 0 is a `label_ref' that - refers to the label to jump to. Jump if the condition codes meet - condition COND. - - Some machines do not follow the model assumed here where a - comparison instruction is followed by a conditional branch - instruction. In that case, the `cmpM' (and `tstM') patterns - should simply store the operands away and generate all the - required insns in a `define_expand' (*note Expander - Definitions::.) for the conditional branch operations. All calls - to expand `vCOND' patterns are immediately preceded by calls to - expand either a `cmpM' pattern or a `tstM' pattern. - - Machines that use a pseudo register for the condition code value, - or where the mode used for the comparison depends on the - condition being tested, should also use the above mechanism. - *Note Jump Patterns:: - - The above discussion also applies to `sCOND' patterns. - -`call' - Subroutine call instruction returning no value. Operand 0 is the - function to call; operand 1 is the number of bytes of arguments - pushed (in mode `SImode', except it is normally a `const_int'); - operand 2 is the number of registers used as operands. - - On most machines, operand 2 is not actually stored into the RTL - pattern. It is supplied for the sake of some RISC machines which - need to put this information into the assembler code; they can - put it in the RTL instead of operand 1. - - Operand 0 should be a `mem' RTX whose address is the address of - the function. Note, however, that this address can be a - `symbol_ref' expression even if it would not be a legitimate - memory address on the target machine. If it is also not a valid - argument for a call instruction, the pattern for this operation - should be a `define_expand' (*note Expander Definitions::.) that - places the address into a register and uses that register in the - call instruction. - -`call_value' - Subroutine call instruction returning a value. Operand 0 is the - hard register in which the value is returned. There are three - more operands, the same as the three operands of the `call' - instruction (but with numbers increased by one). - - Subroutines that return `BLKmode' objects use the `call' insn. - -`call_pop', `call_value_pop' - Similar to `call' and `call_value', except used if defined and if - `RETURN_POPS_ARGS' is non-zero. They should emit a `parallel' - that contains both the function call and a `set' to indicate the - adjustment made to the frame pointer. - - For machines where `RETURN_POPS_ARGS' can be non-zero, the use of - these patterns increases the number of functions for which the - frame pointer can be eliminated, if desired. - -`return' - Subroutine return instruction. This instruction pattern name - should be defined only if a single instruction can do all the - work of returning from a function. - - Like the `movM' patterns, this pattern is also used after the RTL - generation phase. In this case it is to support machines where - multiple instructions are usually needed to return from a - function, but some class of functions only requires one - instruction to implement a return. Normally, the applicable - functions are those which do not need to save any registers or - allocate stack space. - - For such machines, the condition specified in this pattern should - only be true when `reload_completed' is non-zero and the - function's epilogue would only be a single instruction. For - machines with register windows, the routine `leaf_function_p' may - be used to determine if a register window push is required. - - Machines that have conditional return instructions should define - patterns such as - - (define_insn "" - [(set (pc) - (if_then_else (match_operator 0 "comparison_operator" - [(cc0) (const_int 0)]) - (return) - (pc)))] - "CONDITION" - "...") - - where CONDITION would normally be the same condition specified on - the named `return' pattern. - -`nop' - No-op instruction. This instruction pattern name should always - be defined to output a no-op in assembler code. `(const_int 0)' - will do as an RTL pattern. - -`indirect_jump' - An instruction to jump to an address which is operand zero. This - pattern name is mandatory on all machines. - -`casesi' - Instruction to jump through a dispatch table, including bounds - checking. This instruction takes five operands: - - 1. The index to dispatch on, which has mode `SImode'. - - 2. The lower bound for indices in the table, an integer - constant. - - 3. The total range of indices in the table--the largest index - minus the smallest one (both inclusive). - - 4. A label that precedes the table itself. - - 5. A label to jump to if the index has a value outside the - bounds. (If the machine-description macro - `CASE_DROPS_THROUGH' is defined, then an out-of-bounds index - drops through to the code following the jump table instead - of jumping to this label. In that case, this label is not - actually used by the `casesi' instruction, but it is always - provided as an operand.) - - The table is a `addr_vec' or `addr_diff_vec' inside of a - `jump_insn'. The number of elements in the table is one plus the - difference between the upper bound and the lower bound. - -`tablejump' - Instruction to jump to a variable address. This is a low-level - capability which can be used to implement a dispatch table when - there is no `casesi' pattern. - - This pattern requires two operands: the address or offset, and a - label which should immediately precede the jump table. If the - macro `CASE_VECTOR_PC_RELATIVE' is defined then the first operand - is an offset which counts from the address of the table; - otherwise, it is an absolute address to jump to. - - The `tablejump' insn is always the last insn before the jump - table it uses. Its assembler code normally has no need to use the - second operand, but you should incorporate it in the RTL pattern - so that the jump optimizer will not delete the table as - unreachable code. + You can define an `enum' tag without specifying its possible values. +This results in an incomplete type, much like what you get if you write +`struct foo' without describing the elements. A later declaration +which does specify the possible values completes the type. + + You can't allocate variables or storage using the type while it is +incomplete. However, you can work with pointers to that type. + + This extension may not be very useful, but it makes the handling of +`enum' more consistent with the way `struct' and `union' are handled. + + This extension is not supported by GNU C++.  -File: gcc.info, Node: Pattern Ordering, Next: Dependent Patterns, Prev: Standard Names, Up: Machine Desc +File: gcc.info, Node: Function Names, Prev: Incomplete Enums, Up: C Extensions -When the Order of Patterns Matters -================================== +Function Names as Strings +========================= - Sometimes an insn can match more than one instruction pattern. -Then the pattern that appears first in the machine description is the -one used. Therefore, more specific patterns (patterns that will match -fewer things) and faster instructions (those that will produce better -code when they do match) should usually go first in the description. - - In some cases the effect of ordering the patterns can be used to -hide a pattern when it is not valid. For example, the 68000 has an -instruction for converting a fullword to floating point and another -for converting a byte to floating point. An instruction converting an -integer to floating point could match either one. We put the pattern -to convert the fullword first to make sure that one will be used -rather than the other. (Otherwise a large integer might be generated -as a single-byte immediate quantity, which would not work.) Instead of -using this pattern ordering it would be possible to make the pattern -for convert-a-byte smart enough to deal properly with any constant -value. + GNU CC predefines two string variables to be the name of the current +function. The variable `__FUNCTION__' is the name of the function as +it appears in the source. The variable `__PRETTY_FUNCTION__' is the +name of the function pretty printed in a language specific fashion. + + These names are always the same in a C function, but in a C++ +function they may be different. For example, this program: + + extern "C" { + extern int printf (char *, ...); + } + + class a { + public: + sub (int i) + { + printf ("__FUNCTION__ = %s\n", __FUNCTION__); + printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); + } + }; + + int + main (void) + { + a ax; + ax.sub (0); + return 0; + } + +gives this output: + + __FUNCTION__ = sub + __PRETTY_FUNCTION__ = int a::sub (int) + + These names are not macros: they are predefined string variables. +For example, `#ifdef __FUNCTION__' does not have any special meaning +inside a function, since the preprocessor does not do anything special +with the identifier `__FUNCTION__'.  -File: gcc.info, Node: Dependent Patterns, Next: Jump Patterns, Prev: Pattern Ordering, Up: Machine Desc +File: gcc.info, Node: C++ Extensions, Next: Trouble, Prev: C Extensions, Up: Top -Interdependence of Patterns -=========================== +Extensions to the C++ Language +****************************** - Every machine description must have a named pattern for each of the -conditional branch names `bCOND'. The recognition template must -always have the form - - (set (pc) - (if_then_else (COND (cc0) (const_int 0)) - (label_ref (match_operand 0 "" "")) - (pc))) - -In addition, every machine description must have an anonymous pattern -for each of the possible reverse-conditional branches. Their templates -look like - - (set (pc) - (if_then_else (COND (cc0) (const_int 0)) - (pc) - (label_ref (match_operand 0 "" "")))) - -They are necessary because jump optimization can turn -direct-conditional branches into reverse-conditional branches. - - It is often convenient to use the `match_operator' construct to -reduce the number of patterns that must be specified for branches. For -example, - - (define_insn "" - [(set (pc) - (if_then_else (match_operator 0 "comparison_operator" - [(cc0) (const_int 0)]) - (pc) - (label_ref (match_operand 1 "" ""))))] - "CONDITION" - "...") - - In some cases machines support instructions identical except for the -machine mode of one or more operands. For example, there may be -"sign-extend halfword" and "sign-extend byte" instructions whose -patterns are + The GNU compiler provides these extensions to the C++ language (and +you can also use most of the C language extensions in your C++ +programs). If you want to write code that checks whether these +features are available, you can test for the GNU compiler the same way +as for C programs: check for a predefined macro `__GNUC__'. You can +also use `__GNUG__' to test specifically for GNU C++ (*note Standard +Predefined Macros: (cpp.info)Standard Predefined.). + +* Menu: + +* Naming Results:: Giving a name to C++ function return values. +* Min and Max:: C++ Minimum and maximum operators. +* Destructors and Goto:: Goto is safe to use in C++ even when destructors + are needed. +* C++ Interface:: You can use a single C++ header file for both + declarations and definitions. +* Template Instantiation:: Methods for ensuring that exactly one copy of + each needed template instantiation is emitted. +* C++ Signatures:: You can specify abstract types to get subtype + polymorphism independent from inheritance. - (set (match_operand:SI 0 ...) - (extend:SI (match_operand:HI 1 ...))) - - (set (match_operand:SI 0 ...) - (extend:SI (match_operand:QI 1 ...))) + +File: gcc.info, Node: Naming Results, Next: Min and Max, Up: C++ Extensions + +Named Return Values in C++ +========================== -Constant integers do not specify a machine mode, so an instruction to -extend a constant value could match either pattern. The pattern it -actually will match is the one that appears first in the file. For -correct results, this must be the one for the widest possible mode -(`HImode', here). If the pattern matches the `QImode' instruction, -the results will be incorrect if the constant value does not actually -fit that mode. - - Such instructions to extend constants are rarely generated because -they are optimized away, but they do occasionally happen in -nonoptimized compilations. - - If a constraint in a pattern allows a constant, the reload pass may -replace a register with a constant permitted by the constraint in some -cases. Similarly for memory references. You must ensure that the -predicate permits all objects allowed by the constraints to prevent the -compiler from crashing. - - Because of this substitution, you should not provide separate -patterns for increment and decrement instructions. Instead, they -should be generated from the same pattern that supports -register-register add insns by examining the operands and generating -the appropriate machine instruction. + GNU C++ extends the function-definition syntax to allow you to +specify a name for the result of a function outside the body of the +definition, in C++ programs: + + TYPE + FUNCTIONNAME (ARGS) return RESULTNAME; + { + ... + BODY + ... + } + + You can use this feature to avoid an extra constructor call when a +function result has a class type. For example, consider a function +`m', declared as `X v = m ();', whose result is of class `X': + + X + m () + { + X b; + b.a = 23; + return b; + } + + Although `m' appears to have no arguments, in fact it has one +implicit argument: the address of the return value. At invocation, the +address of enough space to hold `v' is sent in as the implicit argument. +Then `b' is constructed and its `a' field is set to the value 23. +Finally, a copy constructor (a constructor of the form `X(X&)') is +applied to `b', with the (implicit) return value location as the +target, so that `v' is now bound to the return value. + + But this is wasteful. The local `b' is declared just to hold +something that will be copied right out. While a compiler that +combined an "elision" algorithm with interprocedural data flow analysis +could conceivably eliminate all of this, it is much more practical to +allow you to assist the compiler in generating efficient code by +manipulating the return value explicitly, thus avoiding the local +variable and copy constructor altogether. + + Using the extended GNU C++ function-definition syntax, you can avoid +the temporary allocation and copying by naming `r' as your return value +at the outset, and assigning to its `a' field directly: + + X + m () return r; + { + r.a = 23; + } + +The declaration of `r' is a standard, proper declaration, whose effects +are executed *before* any of the body of `m'. + + Functions of this type impose no additional restrictions; in +particular, you can execute `return' statements, or return implicitly by +reaching the end of the function body ("falling off the edge"). Cases +like + + X + m () return r (23); + { + return; + } + +(or even `X m () return r (23); { }') are unambiguous, since the return +value `r' has been initialized in either case. The following code may +be hard to read, but also works predictably: + + X + m () return r; + { + X b; + return b; + } + + The return value slot denoted by `r' is initialized at the outset, +but the statement `return b;' overrides this value. The compiler deals +with this by destroying `r' (calling the destructor if there is one, or +doing nothing if there is not), and then reinitializing `r' with `b'. + + This extension is provided primarily to help people who use +overloaded operators, where there is a great need to control not just +the arguments, but the return values of functions. For classes where +the copy constructor incurs a heavy performance penalty (especially in +the common case where there is a quick default constructor), this is a +major savings. The disadvantage of this extension is that you do not +control when the default constructor for the return value is called: it +is always called at the beginning.  -File: gcc.info, Node: Jump Patterns, Next: Insn Canonicalizations, Prev: Dependent Patterns, Up: Machine Desc +File: gcc.info, Node: Min and Max, Next: Destructors and Goto, Prev: Naming Results, Up: C++ Extensions + +Minimum and Maximum Operators in C++ +==================================== -Defining Jump Instruction Patterns -================================== + It is very convenient to have operators which return the "minimum" +or the "maximum" of two arguments. In GNU C++ (but not in GNU C), + +`A ? B' + is the "maximum", returning the larger of the numeric values A and + B. + + These operations are not primitive in ordinary C++, since you can +use a macro to return the minimum of two things in C++, as in the +following example. + + #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) + +You might then use `int min = MIN (i, j);' to set MIN to the minimum +value of variables I and J. + + However, side effects in `X' or `Y' may cause unintended behavior. +For example, `MIN (i++, j++)' will fail, incrementing the smaller +counter twice. A GNU C extension allows you to write safe macros that +avoid this kind of problem (*note Naming an Expression's Type: Naming +Types.). However, writing `MIN' and `MAX' as macros also forces you to +use function-call notation notation for a fundamental arithmetic +operation. Using GNU C++ extensions, you can write `int min = i ?' are built into the compiler, they properly +handle expressions with side-effects; `int min = i++ ; + template ostream& operator << (ostream&, const A&); + + This strategy will work with code written for either model. If + you are using code written for the Cfront model, the file + containing a class template and the file containing its member + templates should be implemented in the same translation unit. + + A slight variation on this approach is to use the flag + -falt-external-templates instead; this flag causes template + instances to be emitted in the translation unit that implements + the header where they are first instantiated, rather than the one + which implements the file where the templates are defined. This + header must be the same in all translation units, or things are + likely to break. + + *Note Declarations and Definitions in One Header: C++ Interface, + for more discussion of these pragmas. + + 3. Explicitly instantiate all the template instances you use, and + compile with -fno-implicit-templates. This is probably your best + bet; it may require more knowledge of exactly which templates you + are using, but it's less mysterious than the previous approach, + and it doesn't require any `#pragma's or other g++-specific code. + You can scatter the instantiations throughout your program, you + can create one big file to do all the instantiations, or you can + create tiny files like + + #include "Foo.h" + #include "Foo.cc" + + template class Foo; + + for each instance you need, and create a template instantiation + library from those. I'm partial to the last, but your mileage may + vary. If you are using Cfront-model code, you can probably get + away with not using -fno-implicit-templates when compiling files + that don't `#include' the member template definitions. + + +File: gcc.info, Node: C++ Signatures, Prev: Template Instantiation, Up: C++ Extensions + +Type Abstraction using Signatures +================================= + + In GNU C++, you can use the keyword `signature' to define a +completely abstract class interface as a datatype. You can connect this +abstraction with actual classes using signature pointers. If you want +to use signatures, run the GNU compiler with the `-fhandle-signatures' +command-line option. (With this option, the compiler reserves a second +keyword `sigof' as well, for a future extension.) + + Roughly, signatures are type abstractions or interfaces of classes. +Some other languages have similar facilities. C++ signatures are +related to ML's signatures, Haskell's type classes, definition modules +in Modula-2, interface modules in Modula-3, abstract types in Emerald, +type modules in Trellis/Owl, categories in Scratchpad II, and types in +POOL-I. For a more detailed discussion of signatures, see `Signatures: +A Language Extension for Improving Type Abstraction and Subtype +Polymorphism in C++' by Gerald Baumgartner and Vincent F. Russo (Tech +report CSD-TR-95-051, Dept. of Computer Sciences, Purdue University, +August 1995, a slightly improved version appeared in +*Software--Practice & Experience*, 25(8), pp. 863-889, August 1995). +You can get the tech report by anonymous FTP from `ftp.cs.purdue.edu' +in `pub/gb/Signature-design.ps.gz'. + + Syntactically, a signature declaration is a collection of member +function declarations and nested type declarations. For example, this +signature declaration defines a new abstract type `S' with member +functions `int foo ()' and `int bar (int)': + + signature S + { + int foo (); + int bar (int); + }; + + Since signature types do not include implementation definitions, you +cannot write an instance of a signature directly. Instead, you can +define a pointer to any class that contains the required interfaces as a +"signature pointer". Such a class "implements" the signature type. + + To use a class as an implementation of `S', you must ensure that the +class has public member functions `int foo ()' and `int bar (int)'. +The class can have other member functions as well, public or not; as +long as it offers what's declared in the signature, it is suitable as +an implementation of that signature type. + + For example, suppose that `C' is a class that meets the requirements +of signature `S' (`C' "conforms to" `S'). Then + + C obj; + S * p = &obj; + +defines a signature pointer `p' and initializes it to point to an +object of type `C'. The member function call `int i = p->foo ();' +executes `obj.foo ()'. + + Abstract virtual classes provide somewhat similar facilities in +standard C++. There are two main advantages to using signatures +instead: + + 1. Subtyping becomes independent from inheritance. A class or + signature type `T' is a subtype of a signature type `S' + independent of any inheritance hierarchy as long as all the member + functions declared in `S' are also found in `T'. So you can + define a subtype hierarchy that is completely independent from any + inheritance (implementation) hierarchy, instead of being forced to + use types that mirror the class inheritance hierarchy. + + 2. Signatures allow you to work with existing class hierarchies as + implementations of a signature type. If those class hierarchies + are only available in compiled form, you're out of luck with + abstract virtual classes, since an abstract virtual class cannot + be retrofitted on top of existing class hierarchies. So you would + be required to write interface classes as subtypes of the abstract + virtual class. + + There is one more detail about signatures. A signature declaration +can contain member function *definitions* as well as member function +declarations. A signature member function with a full definition is +called a *default implementation*; classes need not contain that +particular interface in order to conform. For example, a class `C' can +conform to the signature + + signature T + { + int f (int); + int f0 () { return f (0); }; + }; + +whether or not `C' implements the member function `int f0 ()'. If you +define `C::f0', that definition takes precedence; otherwise, the +default implementation `S::f0' applies. + + +File: gcc.info, Node: Trouble, Next: Bugs, Prev: C++ Extensions, Up: Top + +Known Causes of Trouble with GNU CC +*********************************** + + This section describes known problems that affect users of GNU CC. +Most of these are not GNU CC bugs per se--if they were, we would fix +them. But the result for a user may be like the result of a bug. + + Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +* Menu: + +* Actual Bugs:: Bugs we will fix later. +* Installation Problems:: Problems that manifest when you install GNU CC. +* Cross-Compiler Problems:: Common problems of cross compiling with GNU CC. +* Interoperation:: Problems using GNU CC with other compilers, + and with certain linkers, assemblers and debuggers. +* External Bugs:: Problems compiling certain programs. +* Incompatibilities:: GNU CC is incompatible with traditional C. +* Fixed Headers:: GNU C uses corrected versions of system header files. + This is necessary, but doesn't always work smoothly. +* Standard Libraries:: GNU C uses the system C library, which might not be + compliant with the ISO/ANSI C standard. +* Disappointments:: Regrettable things we can't change, but not quite bugs. +* C++ Misunderstandings:: Common misunderstandings with GNU C++. +* Protoize Caveats:: Things to watch out for when using `protoize'. +* Non-bugs:: Things we think are right, but some others disagree. +* Warnings and Errors:: Which problems in your code get warnings, + and which get errors. + + +File: gcc.info, Node: Actual Bugs, Next: Installation Problems, Up: Trouble - For most machines, GNU CC assumes that the machine has a condition -code. A comparison insn sets the condition code, recording the -results of both signed and unsigned comparison of the given operands. -A separate branch insn tests the condition code and branches or not -according its value. The branch insns come in distinct signed and -unsigned flavors. Many common machines, such as the Vax, the 68000 -and the 32000, work this way. - - Some machines have distinct signed and unsigned compare -instructions, and only one set of conditional branch instructions. -The easiest way to handle these machines is to treat them just like -the others until the final stage where assembly code is written. At -this time, when outputting code for the compare instruction, peek -ahead at the following branch using `next_cc0_user (insn)'. (The -variable `insn' refers to the insn being output, in the output-writing -code in an instruction pattern.) If the RTL says that is an unsigned -branch, output an unsigned compare; otherwise output a signed compare. - When the branch itself is output, you can treat signed and unsigned -branches identically. - - The reason you can do this is that GNU CC always generates a pair of -consecutive RTL insns, possibly separated by `note' insns, one to set -the condition code and one to test it, and keeps the pair inviolate -until the end. - - To go with this technique, you must define the machine-description -macro `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no -compare instruction is superfluous. - - Some machines have compare-and-branch instructions and no condition -code. A similar technique works for them. When it is time to -"output" a compare instruction, record its operands in two static -variables. When outputting the branch-on-condition-code instruction -that follows, actually output a compare-and-branch instruction that -uses the remembered operands. - - It also works to define patterns for compare-and-branch -instructions. In optimizing compilation, the pair of compare and -branch instructions will be combined according to these patterns. But -this does not happen if optimization is not requested. So you must -use one of the solutions above in addition to any special patterns you -define. - - In many RISC machines, most instructions do not affect the condition -code and there may not even be a separate condition code register. On -these machines, the restriction that the definition and use of the -condition code be adjacent insns is not necessary and can prevent -important optimizations. For example, on the IBM RS/6000, there is a -delay for taken branches unless the condition code register is set -three instructions earlier than the conditional branch. The -instruction scheduler cannot perform this optimization if it is not -permitted to separate the definition and use of the condition code -register. - - On these machines, do not use `(cc0)', but instead use a register -to represent the condition code. If there is a specific condition code -register in the machine, use a hard register. If the condition code or -comparison result can be placed in any general register, or if there -are multiple condition registers, use a pseudo register. - - On some machines, the type of branch instruction generated may -depend on the way the condition code was produced; for example, on the -68k and Sparc, setting the condition code directly from an add or -subtract instruction does not clear the overflow bit the way that a -test instruction does, so a different branch instruction must be used -for some conditional branches. For machines that use `(cc0)', the set -and use of the condition code must be adjacent (separated only by -`note' insns) allowing flags in `cc_status' to be used. (*Note -Condition Code::.) Also, the comparison and branch insns can be -located from each other by using the functions `prev_cc0_setter' and -`next_cc0_user'. - - However, this is not true on machines that do not use `(cc0)'. On -those machines, no assumptions can be made about the adjacency of the -compare and branch insns and the above methods cannot be used. -Instead, we use the machine mode of the condition code register to -record different formats of the condition code register. - - Registers used to store the condition code value should have a mode -that is in class `MODE_CC'. Normally, it will be `CCmode'. If -additional modes are required (as for the add example mentioned above -in the Sparc), define the macro `EXTRA_CC_MODES' to list the -additional modes required (*note Condition Code::.). Also define -`EXTRA_CC_NAMES' to list the names of those modes and `SELECT_CC_MODE' -to choose a mode given an operand of a compare. - - If it is known during RTL generation that a different mode will be -required (for example, if the machine has separate compare instructions -for signed and unsigned quantities, like most IBM processors), they can -be specified at that time. - - If the cases that require different modes would be made by -instruction combination, the macro `SELECT_CC_MODE' determines which -machine mode should be used for the comparison result. The patterns -should be written using that mode. To support the case of the add on -the Sparc discussed above, we have the pattern - - (define_insn "" - [(set (reg:CC_NOOV 0) - (compare:CC_NOOV (plus:SI (match_operand:SI 0 "register_operand" "%r") - (match_operand:SI 1 "arith_operand" "rI")) - (const_int 0)))] - "" - "...") +Actual Bugs We Haven't Fixed Yet +================================ - The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for -comparisons whose argument is a `plus'. + * The `fixincludes' script interacts badly with automounters; if the + directory of system header files is automounted, it tends to be + unmounted while `fixincludes' is running. This would seem to be a + bug in the automounter. We don't know any good way to work around + it. + + * The `fixproto' script will sometimes add prototypes for the + `sigsetjmp' and `siglongjmp' functions that reference the + `jmp_buf' type before that type is defined. To work around this, + edit the offending file and place the typedef in front of the + prototypes. + + * There are several obscure case of mis-using struct, union, and + enum tags that are not detected as errors by the compiler. + + * When `-pedantic-errors' is specified, GNU C will incorrectly give + an error message when a function name is specified in an expression + involving the comma operator. + + * Loop unrolling doesn't work properly for certain C++ programs. + This is a bug in the C++ front end. It sometimes emits incorrect + debug info, and the loop unrolling code is unable to recover from + this error. - \ No newline at end of file