--- gcc/gcc.info-16 2018/04/24 17:51:23 1.1.1.1 +++ gcc/gcc.info-16 2018/04/24 17:52:22 1.1.1.2 @@ -1,4 +1,4 @@ -This is Info file gcc.info, produced by Makeinfo-1.43 from the input +This is Info file gcc.info, produced by Makeinfo-1.44 from the input file gcc.texi. This file documents the use and the internals of the GNU compiler. @@ -24,7 +24,626 @@ approved by the Free Software Foundation English.  -File: gcc.info, Node: Config, Next: Index, Prev: Machine Macros, Up: Top +File: gcc.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Target Macros + +Controlling Debugging Information Format +======================================== + +`DBX_REGISTER_NUMBER (REGNO)' + A C expression that returns the DBX register number for the + compiler register number REGNO. In simple cases, the value of + this expression may be REGNO itself. But sometimes there are some + registers that the compiler knows about and DBX does not, or vice + versa. In such cases, some register may need to have one number + in the compiler and another for DBX. + + If two registers have consecutive numbers inside GNU CC, and they + can be used as a pair to hold a multiword value, then they *must* + have consecutive numbers after renumbering with + `DBX_REGISTER_NUMBER'. Otherwise, debuggers will be unable to + access such a pair, because they expect register pairs to be + consecutive in their own numbering scheme. + + If you find yourself defining `DBX_REGISTER_NUMBER' in way that + does not preserve register pairs, then what you must do instead is + redefine the actual register numbering scheme. + +`DBX_DEBUGGING_INFO' + Define this macro if GNU CC should produce debugging output for + DBX in response to the `-g' option. + +`SDB_DEBUGGING_INFO' + Define this macro if GNU CC should produce COFF-style debugging + output for SDB in response to the `-g' option. + +`DWARF_DEBUGGING_INFO' + Define this macro if GNU CC should produce dwarf format debugging + output in response to the `-g' option. + +`XCOFF_DEBUGGING_INFO' + Define this macro if GNU CC should produce XCOFF format debugging + output in response to the `-g' option. + +`DEFAULT_GDB_EXTENSIONS' + Define this macro to control whether GNU CC should by default + generate GDB's extended version of DBX debugging information + (assuming DBX-format debugging information is enabled at all). + If you don't define the macro, the default is 1: always generate + the extended information. + +`DEBUG_SYMS_TEXT' + Define this macro if all `.stabs' commands should be output while + in the text section. + +`DEBUGGER_AUTO_OFFSET (X)' + A C expression that returns the integer offset value for an + automatic variable having address X (an RTL expression). The + default computation assumes that X is based on the frame-pointer + and gives the offset from the frame-pointer. This is required + for targets that produce debugging output for DBX or COFF-style + debugging output for SDB and allow the frame-pointer to be + eliminated when the `-g' options is used. + +`DEBUGGER_ARG_OFFSET (OFFSET, X)' + A C expression that returns the integer offset value for an + argument having address X (an RTL expression). The nominal + offset is OFFSET. + +`ASM_STABS_OP' + A C string constant naming the assembler pseudo op to use instead + of `.stabs' to define an ordinary debugging symbol. If you don't + define this macro, `.stabs' is used. This macro applies only to + DBX debugging information format. + +`ASM_STABD_OP' + A C string constant naming the assembler pseudo op to use instead + of `.stabd' to define a debugging symbol whose value is the + current location. If you don't define this macro, `.stabd' is + used. This macro applies only to DBX debugging information + format. + +`ASM_STABN_OP' + A C string constant naming the assembler pseudo op to use instead + of `.stabn' to define a debugging symbol with no name. If you + don't define this macro, `.stabn' is used. This macro applies + only to DBX debugging information format. + +`PUT_SDB_...' + Define these macros to override the assembler syntax for the + special SDB assembler directives. See `sdbout.c' for a list of + these macros and their arguments. If the standard syntax is + used, you need not define them yourself. + +`SDB_DELIM' + Some assemblers do not support a semicolon as a delimiter, even + between SDB assembler directives. In that case, define this + macro to be the delimiter to use (usually `\n'). It is not + necessary to define a new set of `PUT_SDB_OP' macros if this is + the only change required. + +`SDB_GENERATE_FAKE' + Define this macro to override the usual method of constructing a + dummy name for anonymous structure and union types. See + `sdbout.c' for more information. + +`SDB_ALLOW_UNKNOWN_REFERENCES' + Define this macro to allow references to unknown structure, + union, or enumeration tags to be emitted. Standard COFF does not + allow handling of unknown references, MIPS ECOFF has support for + it. + +`SDB_ALLOW_FORWARD_REFERENCES' + Define this macro to allow references to structure, union, or + enumeration tags that have not yet been seen to be handled. Some + assemblers choke if forward tags are used, while some require it. + +`DBX_NO_XREFS' + Define this macro if DBX on your system does not support the + construct `xsTAGNAME'. On some systems, this construct is used to + describe a forward reference to a structure named TAGNAME. On + other systems, this construct is not supported at all. + +`DBX_CONTIN_LENGTH' + A symbol name in DBX-format debugging information is normally + continued (split into two separate `.stabs' directives) when it + exceeds a certain length (by default, 80 characters). On some + operating systems, DBX requires this splitting; on others, + splitting must not be done. You can inhibit splitting by + defining this macro with the value zero. You can override the + default splitting-length by defining this macro as an expression + for the length you desire. + +`DBX_CONTIN_CHAR' + Normally continuation is indicated by adding a `\' character to + the end of a `.stabs' string when a continuation follows. To use + a different character instead, define this macro as a character + constant for the character you want to use. Do not define this + macro if backslash is correct for your system. + +`DBX_WORKING_DIRECTORY' + Define this if DBX wants to have the current directory recorded + in each object file. + + Note that the working directory is always recorded if GDB + extensions are enabled. + +`DBX_STATIC_STAB_DATA_SECTION' + Define this macro if it is necessary to go to the data section + before outputting the `.stabs' pseudo-op for a non-global static + variable. + +`DBX_LBRAC_FIRST' + Define this macro if the `N_LBRAC' symbol for a block should + precede the debugging information for variables and functions + defined in that block. Normally, in DBX format, the `N_LBRAC' + symbol comes first. + +`DBX_FUNCTION_FIRST' + Define this macro if the DBX information for a function and its + arguments should precede the assembler code for the function. + Normally, in DBX format, the debugging information entirely + follows the assembler code. + +`DBX_OUTPUT_FUNCTION_END (STREAM, FUNCTION)' + Define this macro if the target machine requires special output + at the end of the debugging information for a function. The + definition should be a C statement (sans semicolon) to output the + appropriate information to STREAM. FUNCTION is the + `FUNCTION_DECL' node for the function. + +`DBX_OUTPUT_STANDARD_TYPES (SYMS)' + Define this macro if you need to control the order of output of + the standard data types at the beginning of compilation. The + argument SYMS is a `tree' which is a chain of all the predefined + global symbols, including names of data types. + + Normally, DBX output starts with definitions of the types for + integers and characters, followed by all the other predefined + types of the particular language in no particular order. + + On some machines, it is necessary to output different particular + types first. To do this, define `DBX_OUTPUT_STANDARD_TYPES' to + output those symbols in the necessary order. Any predefined + types that you don't explicitly output will be output afterward + in no particular order. + + Be careful not to define this macro so that it works only for C. + There are no global variables to access most of the built-in + types, because another language may have another set of types. + The way to output a particular type is to look through SYMS to + see if you can find it. Here is an example: + + { + tree decl; + for (decl = syms; decl; decl = TREE_CHAIN (decl)) + if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), "long int")) + dbxout_symbol (decl); + ... + } + + This does nothing if the expected type does not exist. + + See the function `init_decl_processing' in source file `c-decl.c' + to find the names to use for all the built-in C types. + +`DBX_OUTPUT_MAIN_SOURCE_FILENAME (STREAM, NAME)' + A C statement to output DBX debugging information to the stdio + stream STREAM which indicates that file NAME is the main source + file--the file specified as the input file for compilation. This + macro is called only once, at the beginning of compilation. + + This macro need not be defined if the standard form of output for + DBX debugging information is appropriate. + +`DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (STREAM, NAME)' + A C statement to output DBX debugging information to the stdio + stream STREAM which indicates that the current directory during + compilation is named NAME. + + This macro need not be defined if the standard form of output for + DBX debugging information is appropriate. + +`DBX_OUTPUT_MAIN_SOURCE_FILE_END (STREAM, NAME)' + A C statement to output DBX debugging information at the end of + compilation of the main source file NAME. + + If you don't define this macro, nothing special is output at the + end of compilation, which is correct for most machines. + +`DBX_OUTPUT_SOURCE_FILENAME (STREAM, NAME)' + A C statement to output DBX debugging information to the stdio + stream STREAM which indicates that file NAME is the current source + file. This output is generated each time input shifts to a + different source file as a result of `#include', the end of an + included file, or a `#line' command. + + This macro need not be defined if the standard form of output for + DBX debugging information is appropriate. + + +File: gcc.info, Node: Cross-compilation, Next: Misc, Prev: Debugging Info, Up: Target Macros + +Cross Compilation and Floating Point Format +=========================================== + + While all modern machines use 2's complement representation for +integers, there are a variety of representations for floating point +numbers. This means that in a cross-compiler the representation of +floating point numbers in the compiled program may be different from +that used in the machine doing the compilation. + + Because different representation systems may offer different +amounts of range and precision, the cross compiler cannot safely use +the host machine's floating point arithmetic. Therefore, floating +point constants must be represented in the target machine's format. +This means that the cross compiler cannot use `atof' to parse a +floating point constant; it must have its own special routine to use +instead. Also, constant folding must emulate the target machine's +arithmetic (or must not be done at all). + + The macros in the following table should be defined only if you are +cross compiling between different floating point formats. + + Otherwise, don't define them. Then default definitions will be set +up which use `double' as the data type, `==' to test for equality, etc. + + You don't need to worry about how many times you use an operand of +any of these macros. The compiler never uses operands which have side +effects. + +`REAL_VALUE_TYPE' + A macro for the C data type to be used to hold a floating point + value in the target machine's format. Typically this would be a + `struct' containing an array of `int'. + +`REAL_VALUES_EQUAL (X, Y)' + A macro for a C expression which compares for equality the two + values, X and Y, both of type `REAL_VALUE_TYPE'. + +`REAL_VALUES_LESS (X, Y)' + A macro for a C expression which tests whether X is less than Y, + both values being of type `REAL_VALUE_TYPE' and interpreted as + floating point numbers in the target machine's representation. + +`REAL_VALUE_LDEXP (X, SCALE)' + A macro for a C expression which performs the standard library + function `ldexp', but using the target machine's floating point + representation. Both X and the value of the expression have type + `REAL_VALUE_TYPE'. The second argument, SCALE, is an integer. + +`REAL_VALUE_FIX (X)' + A macro whose definition is a C expression to convert the + target-machine floating point value X to a signed integer. X has + type `REAL_VALUE_TYPE'. + +`REAL_VALUE_UNSIGNED_FIX (X)' + A macro whose definition is a C expression to convert the + target-machine floating point value X to an unsigned integer. X + has type `REAL_VALUE_TYPE'. + +`REAL_VALUE_FIX_TRUNCATE (X)' + A macro whose definition is a C expression to convert the + target-machine floating point value X to a signed integer, + rounding toward 0. X has type `REAL_VALUE_TYPE'. + +`REAL_VALUE_UNSIGNED_FIX_TRUNCATE (X)' + A macro whose definition is a C expression to convert the + target-machine floating point value X to an unsigned integer, + rounding toward 0. X has type `REAL_VALUE_TYPE'. + +`REAL_VALUE_ATOF (STRING)' + A macro for a C expression which converts STRING, an expression + of type `char *', into a floating point number in the target + machine's representation. The value has type `REAL_VALUE_TYPE'. + +`REAL_INFINITY' + Define this macro if infinity is a possible floating point value, + and therefore division by 0 is legitimate. + +`REAL_VALUE_ISINF (X)' + A macro for a C expression which determines whether X, a floating + point value, is infinity. The value has type `int'. By default, + this is defined to call `isinf'. + +`REAL_VALUE_ISNAN (X)' + A macro for a C expression which determines whether X, a floating + point value, is a "nan" (not-a-number). The value has type + `int'. By default, this is defined to call `isnan'. + + Define the following additional macros if you want to make floating +point constant folding work while cross compiling. If you don't +define them, cross compilation is still possible, but constant folding +will not happen for floating point values. + +`REAL_ARITHMETIC (OUTPUT, CODE, X, Y)' + A macro for a C statement which calculates an arithmetic + operation of the two floating point values X and Y, both of type + `REAL_VALUE_TYPE' in the target machine's representation, to + produce a result of the same type and representation which is + stored in OUTPUT (which will be a variable). + + The operation to be performed is specified by CODE, a tree code + which will always be one of the following: `PLUS_EXPR', + `MINUS_EXPR', `MULT_EXPR', `RDIV_EXPR', `MAX_EXPR', `MIN_EXPR'. + + The expansion of this macro is responsible for checking for + overflow. If overflow happens, the macro expansion should + execute the statement `return 0;', which indicates the inability + to perform the arithmetic operation requested. + +`REAL_VALUE_NEGATE (X)' + A macro for a C expression which returns the negative of the + floating point value X. Both X and the value of the expression + have type `REAL_VALUE_TYPE' and are in the target machine's + floating point representation. + + There is no way for this macro to report overflow, since overflow + can't happen in the negation operation. + +`REAL_VALUE_TRUNCATE (X)' + A macro for a C expression which converts the double-precision + floating point value X to single-precision. + + Both X and the value of the expression have type + `REAL_VALUE_TYPE' and are in the target machine's floating point + representation. However, the value should have an appropriate bit + pattern to be output properly as a single-precision floating + constant. + + There is no way for this macro to report overflow. + +`REAL_VALUE_TO_INT (LOW, HIGH, X)' + A macro for a C expression which converts a floating point value + X into a double-precision integer which is then stored into LOW + and HIGH, two variables of type INT. + +`REAL_VALUE_FROM_INT (X, LOW, HIGH)' + A macro for a C expression which converts a double-precision + integer found in LOW and HIGH, two variables of type INT, into a + floating point value which is then stored into X. + + +File: gcc.info, Node: Misc, Prev: Cross-compilation, Up: Target Macros + +Miscellaneous Parameters +======================== + +`PREDICATE_CODES' + Optionally define this if you have added predicates to + `MACHINE.c'. This macro is called within an initializer of an + array of structures. The first field in the structure is the + name of a predicate and the second field is an array of rtl + codes. For each predicate, list all rtl codes that can be in + expressions matched by the predicate. The list should have a + trailing comma. Here is an example of two entries in the list + for a typical RISC machine: + + #define PREDICATE_CODES \ + {"gen_reg_rtx_operand", {SUBREG, REG}}, \ + {"reg_or_short_cint_operand", {SUBREG, REG, CONST_INT}}, + + Defining this macro does not affect the generated code (however, + incorrect definitions that omit an rtl code that may be matched + by the predicate can cause the compiler to malfunction). + Instead, it allows the table built by `genrecog' to be more + compact and efficient, thus speeding up the compiler. The most + important predicates to include in the list specified by this + macro are thoses used in the most insn patterns. + +`CASE_VECTOR_MODE' + An alias for a machine mode name. This is the machine mode that + elements of a jump-table should have. + +`CASE_VECTOR_PC_RELATIVE' + Define this macro if jump-tables should contain relative + addresses. + +`CASE_DROPS_THROUGH' + Define this if control falls through a `case' insn when the index + value is out of range. This means the specified default-label is + actually ignored by the `case' insn proper. + +`BYTE_LOADS_ZERO_EXTEND' + Define this macro if an instruction to load a value narrower than + a word from memory into a register also zero-extends the value to + the whole register. + +`IMPLICIT_FIX_EXPR' + An alias for a tree code that should be used by default for + conversion of floating point values to fixed point. Normally, + `FIX_ROUND_EXPR' is used. + +`FIXUNS_TRUNC_LIKE_FIX_TRUNC' + Define this macro if the same instructions that convert a floating + point number to a signed fixed point number also convert validly + to an unsigned one. + +`EASY_DIV_EXPR' + An alias for a tree code that is the easiest kind of division to + compile code for in the general case. It may be + `TRUNC_DIV_EXPR', `FLOOR_DIV_EXPR', `CEIL_DIV_EXPR' or + `ROUND_DIV_EXPR'. These four division operators differ in how + they round the result to an integer. `EASY_DIV_EXPR' is used + when it is permissible to use any of those kinds of division and + the choice should be made on the basis of efficiency. + +`MOVE_MAX' + The maximum number of bytes that a single instruction can move + quickly from memory to memory. + +`SHIFT_COUNT_TRUNCATED' + Defining this macro causes the compiler to omit a sign-extend, + zero-extend, or bitwise `and' instruction that truncates the + count of a shift operation to a width equal to the number of bits + needed to represent the size of the object being shifted. On + machines that have instructions that act on bitfields at variable + positions, including `bit test' instructions, defining + `SHIFT_COUNT_TRUNCATED' also causes truncation not to be applied + to these instructions. + + If both types of instructions truncate the count (for shifts) and + position (for bitfield operations), or if no variable-position + bitfield instructions exist, you should define this macro. + + However, on some machines, such as the 80386 and the 680x0, + truncation only applies to shift operations and not the (real or + pretended) bitfield operations. Do not define + `SHIFT_COUNT_TRUNCATED' on such machines. Instead, add patterns + to the `md' file that include the implied truncation of the shift + instructions. + +`TRULY_NOOP_TRUNCATION (OUTPREC, INPREC)' + A C expression which is nonzero if on this machine it is safe to + "convert" an integer of INPREC bits to one of OUTPREC bits (where + OUTPREC is smaller than INPREC) by merely operating on it as if + it had only OUTPREC bits. + + On many machines, this expression can be 1. + + It is reported that suboptimal code can result when + `TRULY_NOOP_TRUNCATION' returns 1 for a pair of sizes for modes + for which `MODES_TIEABLE_P' is 0. If this is the case, making + `TRULY_NOOP_TRUNCATION' return 0 in such cases may improve things. + +`STORE_FLAG_VALUE' + A C expression describing the value returned by a comparison + operator and stored by a store-flag instruction (`sCOND') when the + condition is true. This description must apply to *all* the + `sCOND' patterns and all the comparison operators. + + A value of 1 or -1 means that the instruction implementing the + comparison operator returns exactly 1 or -1 when the comparison + is true and 0 when the comparison is false. Otherwise, the value + indicates which bits of the result are guaranteed to be 1 when + the comparison is true. This value is interpreted in the mode of + the comparison operation, which is given by the mode of the first + operand in the `sCOND' pattern. Either the low bit or the sign + bit of `STORE_FLAG_VALUE' be on. Presently, only those bits are + used by the compiler. + + If `STORE_FLAG_VALUE' is neither 1 or -1, the compiler will + generate code that depends only on the specified bits. It can + also replace comparison operators with equivalent operations if + they cause the required bits to be set, even if the remaining + bits are undefined. For example, on a machine whose comparison + operators return an `SImode' value and where `STORE_FLAG_VALUE' + is defined as `0x80000000', saying that just the sign bit is + relevant, the expression + + (ne:SI (and:SI X (const_int POWER-OF-2)) (const_int 0)) + + can be converted to + + (ashift:SI X (const_int N)) + + where N is the appropriate shift count to move the bit being + tested into the sign bit. + + There is no way to describe a machine that always sets the + low-order bit for a true value, but does not guarantee the value + of any other bits, but we do not know of any machine that has + such an instruction. If you are trying to port GNU CC to such a + machine, include an instruction to perform a logical-and of the + result with 1 in the pattern for the comparison operators and let + us know (*note Bug Reporting::.). + + Often, a machine will have multiple instructions that obtain a + value from a comparison (or the condition codes). Here are rules + to guide the choice of value for `STORE_FLAG_VALUE', and hence + the instructions to be used: + + * Use the shortest sequence that yields a valid definition for + `STORE_FLAG_VALUE'. It is more efficent for the compiler to + "normalize" the value (convert it to, e.g., 1 or 0) than for + the comparison operators to do so because there may be + opportunities to combine the normalization with other + operations. + + * For equal-length sequences, use a value of 1 or -1, with -1 + being slightly preferred on machines with expensive jumps + and 1 preferred on other machines. + + * As a second choice, choose a value of `0x80000001' if + instructions exist that set both the sign and low-order bits + but do not define the others. + + * Otherwise, use a value of `0x80000000'. + + You need not define `STORE_FLAG_VALUE' if the machine has no + store-flag instructions. + +`Pmode' + An alias for the machine mode for pointers. Normally the + definition can be + + #define Pmode SImode + +`FUNCTION_MODE' + An alias for the machine mode used for memory references to + functions being called, in `call' RTL expressions. On most + machines this should be `QImode'. + +`INTEGRATE_THRESHOLD (DECL)' + A C expression for the maximum number of instructions above which + the function DECL should not be inlined. DECL is a + `FUNCTION_DECL' node. + + The default definition of this macro is 64 plus 8 times the + number of arguments that the function accepts. Some people think + a larger threshold should be used on RISC machines. + +`SCCS_DIRECTIVE' + Define this if the preprocessor should ignore `#sccs' directives + and print no error message. + +`HANDLE_PRAGMA (STREAM)' + Define this macro if you want to implement any pragmas. If + defined, it should be a C statement to be executed when `#pragma' + is seen. The argument STREAM is the stdio input stream from + which the source text can be read. + + It is generally a bad idea to implement new uses of `#pragma'. + The only reason to define this macro is for compatibility with + other compilers that do support `#pragma' for the sake of any user + programs which already use it. + +`DOLLARS_IN_IDENTIFIERS' + Define this macro to control use of the character `$' in + identifier names. The value should be 0, 1, or 2. 0 means `$' + is not allowed by default; 1 means it is allowed by default if + `-traditional' is used; 2 means it is allowed by default provided + `-ansi' is not used. 1 is the default; there is no need to + define this macro in that case. + +`NO_DOLLAR_IN_LABEL' + Define this macro if the assembler does not accept the character + `$' in label names. By default constructors and destructors in + G++ have `$' in the identifiers. If this macro is defined, `.' + is used instead. + +`DEFAULT_MAIN_RETURN' + Define this macro if the target system expects every program's + `main' function to return a standard "success" value by default + (if no other value is explicitly returned). + + The definition should be a C statement (sans semicolon) to + generate the appropriate rtl instructions. It is used only when + compiling the end of `main'. + +`HAVE_ATEXIT' + Define this if the target system supports the function `atexit' + from the ANSI C standard. If this is not defined, and + `INIT_SECTION_ASM_OP' is not defined, a default `exit' function + will be provided to support C++. + +`EXIT_BODY' + Define this if your `exit' function needs to do something besides + calling an external function `_cleanup' before terminating with + `_exit'. The `EXIT_BODY' macro is only needed if netiher + `HAVE_ATEXIT' nor `INIT_SECTION_ASM_OP' are defined. + + +File: gcc.info, Node: Config, Next: Index, Prev: Target Macros, Up: Top The Configuration File ********************** @@ -123,6 +742,27 @@ there are some macros that vary: properly handle converting a function value to a pointer-to-function when it is used in an expression. +`HAVE_VPRINTF' + Define this if the library function `vprintf' is available on your + system. + +`HAVE_PUTENV' + Define this if the library function `putenv' is available on your + system. + +`NO_SYS_SIGLIST' + Define this if your system *does not* provide the variable + `sys_siglist'. + + Some systems do provide this variable, but with a different name + such as `_sys_siglist'. On these systems, you can define + `sys_siglist' as a macro which expands into the name actually + provided. + +`NO_STAB_H' + Define this if your system does not have the include file + `stab.h'. If `USG' is defined, `NO_STAB_H' is assumed. + In addition, configuration files for system V define `bcopy', `bzero' and `bcmp' as aliases. Some files define `alloca' as a macro when compiled with GNU CC, in order to take advantage of the benefit