![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tm.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to tm.texi CVS log | Up to [GCC 2.x] / gcc |
1.1.1.5 ! root 1: @c Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc. 1.1 root 2: @c This is part of the GCC manual. 3: @c For copying conditions, see the file gcc.texi. 4: 1.1.1.3 root 5: @node Target Macros 1.1.1.2 root 6: @chapter Target Description Macros 1.1 root 7: @cindex machine description macros 1.1.1.2 root 8: @cindex target description macros 9: @cindex macros, target description 1.1 root 10: @cindex @file{tm.h} macros 11: 12: In addition to the file @file{@var{machine}.md}, a machine description 13: includes a C header file conventionally given the name 14: @file{@var{machine}.h}. This header file defines numerous macros 15: that convey the information about the target machine that does not fit 16: into the scheme of the @file{.md} file. The file @file{tm.h} should be 17: a link to @file{@var{machine}.h}. The header file @file{config.h} 18: includes @file{tm.h} and most compiler source files include 19: @file{config.h}. 20: 21: @menu 22: * Driver:: Controlling how the driver runs the compilation passes. 23: * Run-time Target:: Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}. 24: * Storage Layout:: Defining sizes and alignments of data. 25: * Type Layout:: Defining sizes and properties of basic user data types. 26: * Registers:: Naming and describing the hardware registers. 27: * Register Classes:: Defining the classes of hardware registers. 28: * Stack and Calling:: Defining which way the stack grows and by how much. 29: * Varargs:: Defining the varargs macros. 30: * Trampolines:: Code set up at run time to enter a nested function. 31: * Library Calls:: Controlling how library routines are implicitly called. 32: * Addressing Modes:: Defining addressing modes valid for memory operands. 33: * Condition Code:: Defining how insns update the condition code. 34: * Costs:: Defining relative costs of different operations. 35: * Sections:: Dividing storage into text, data, and other sections. 36: * PIC:: Macros for position independent code. 37: * Assembler Format:: Defining how to write insns and pseudo-ops to output. 38: * Debugging Info:: Defining the format of debugging output. 39: * Cross-compilation:: Handling floating point for cross-compilers. 40: * Misc:: Everything else. 41: @end menu 42: 1.1.1.2 root 43: @node Driver 1.1 root 44: @section Controlling the Compilation Driver, @file{gcc} 45: @cindex driver 46: @cindex controlling the compilation driver 47: 48: @table @code 49: @findex SWITCH_TAKES_ARG 50: @item SWITCH_TAKES_ARG (@var{char}) 51: A C expression which determines whether the option @samp{-@var{char}} 52: takes arguments. The value should be the number of arguments that 53: option takes--zero, for many options. 54: 55: By default, this macro is defined to handle the standard options 56: properly. You need not define it unless you wish to add additional 57: options which take arguments. 58: 59: @findex WORD_SWITCH_TAKES_ARG 60: @item WORD_SWITCH_TAKES_ARG (@var{name}) 61: A C expression which determines whether the option @samp{-@var{name}} 62: takes arguments. The value should be the number of arguments that 63: option takes--zero, for many options. This macro rather than 64: @code{SWITCH_TAKES_ARG} is used for multi-character option names. 65: 1.1.1.5 ! root 66: By default, this macro is defined as ! 67: @code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options ! 68: properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you ! 69: wish to add additional options which take arguments. Any redefinition ! 70: should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for ! 71: additional options. 1.1 root 72: 73: @findex SWITCHES_NEED_SPACES 74: @item SWITCHES_NEED_SPACES 75: A string-valued C expression which is nonempty if the linker needs a 76: space between the @samp{-L} or @samp{-o} option and its argument. 77: 78: If this macro is not defined, the default value is 0. 79: 80: @findex CPP_SPEC 81: @item CPP_SPEC 82: A C string constant that tells the GNU CC driver program options to 83: pass to CPP. It can also specify how to translate options you 84: give to GNU CC into options for GNU CC to pass to the CPP. 85: 86: Do not define this macro if it does not need to do anything. 87: 1.1.1.5 ! root 88: @findex NO_BUILTIN_SIZE_TYPE ! 89: @item NO_BUILTIN_SIZE_TYPE ! 90: If this macro is defined, the preprocessor will not define the builtin macro ! 91: @code{__SIZE_TYPE__}. The macro @code{__SIZE_TYPE__} must then be defined ! 92: by @code{CPP_SPEC} instead. ! 93: ! 94: This should be defined if @code{SIZE_TYPE} depends on target dependent flags ! 95: which are not accessible to the preprocessor. Otherwise, it should not ! 96: be defined. ! 97: ! 98: @findex NO_BUILTIN_PTRDIFF_TYPE ! 99: @item NO_BUILTIN_PTRDIFF_TYPE ! 100: If this macro is defined, the preprocessor will not define the builtin macro ! 101: @code{__PTRDIFF_TYPE__}. The macro @code{__PTRDIFF_TYPE__} must then be ! 102: defined by @code{CPP_SPEC} instead. ! 103: ! 104: This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags ! 105: which are not accessible to the preprocessor. Otherwise, it should not ! 106: be defined. ! 107: 1.1 root 108: @findex SIGNED_CHAR_SPEC 109: @item SIGNED_CHAR_SPEC 110: A C string constant that tells the GNU CC driver program options to 111: pass to CPP. By default, this macro is defined to pass the option 112: @samp{-D__CHAR_UNSIGNED__} to CPP if @code{char} will be treated as 113: @code{unsigned char} by @code{cc1}. 114: 115: Do not define this macro unless you need to override the default 116: definition. 117: 118: @findex CC1_SPEC 119: @item CC1_SPEC 120: A C string constant that tells the GNU CC driver program options to 121: pass to @code{cc1}. It can also specify how to translate options you 122: give to GNU CC into options for GNU CC to pass to the @code{cc1}. 123: 124: Do not define this macro if it does not need to do anything. 125: 126: @findex CC1PLUS_SPEC 127: @item CC1PLUS_SPEC 128: A C string constant that tells the GNU CC driver program options to 129: pass to @code{cc1plus}. It can also specify how to translate options you 130: give to GNU CC into options for GNU CC to pass to the @code{cc1plus}. 131: 132: Do not define this macro if it does not need to do anything. 133: 134: @findex ASM_SPEC 135: @item ASM_SPEC 136: A C string constant that tells the GNU CC driver program options to 137: pass to the assembler. It can also specify how to translate options 138: you give to GNU CC into options for GNU CC to pass to the assembler. 139: See the file @file{sun3.h} for an example of this. 140: 141: Do not define this macro if it does not need to do anything. 142: 143: @findex ASM_FINAL_SPEC 144: @item ASM_FINAL_SPEC 145: A C string constant that tells the GNU CC driver program how to 146: run any programs which cleanup after the normal assembler. 147: Normally, this is not needed. See the file @file{mips.h} for 148: an example of this. 149: 150: Do not define this macro if it does not need to do anything. 151: 152: @findex LINK_SPEC 153: @item LINK_SPEC 154: A C string constant that tells the GNU CC driver program options to 155: pass to the linker. It can also specify how to translate options you 156: give to GNU CC into options for GNU CC to pass to the linker. 157: 158: Do not define this macro if it does not need to do anything. 159: 160: @findex LIB_SPEC 161: @item LIB_SPEC 162: Another C string constant used much like @code{LINK_SPEC}. The difference 163: between the two is that @code{LIB_SPEC} is used at the end of the 164: command given to the linker. 165: 166: If this macro is not defined, a default is provided that 167: loads the standard C library from the usual place. See @file{gcc.c}. 168: 169: @findex STARTFILE_SPEC 170: @item STARTFILE_SPEC 171: Another C string constant used much like @code{LINK_SPEC}. The 172: difference between the two is that @code{STARTFILE_SPEC} is used at 173: the very beginning of the command given to the linker. 174: 175: If this macro is not defined, a default is provided that loads the 176: standard C startup file from the usual place. See @file{gcc.c}. 177: 178: @findex ENDFILE_SPEC 179: @item ENDFILE_SPEC 180: Another C string constant used much like @code{LINK_SPEC}. The 181: difference between the two is that @code{ENDFILE_SPEC} is used at 182: the very end of the command given to the linker. 183: 184: Do not define this macro if it does not need to do anything. 185: 186: @findex LINK_LIBGCC_SPECIAL 187: @item LINK_LIBGCC_SPECIAL 1.1.1.5 ! root 188: Define this macro meaning that @code{gcc} should find the library ! 189: @file{libgcc.a} by hand, rather than passing the argument @samp{-lgcc} ! 190: to tell the linker to do the search; also, @code{gcc} should not ! 191: generate @samp{-L} options to pass to the linker (as it normally does). ! 192: ! 193: @findex LINK_LIBGCC_SPECIAL_1 ! 194: @item LINK_LIBGCC_SPECIAL_1 1.1 root 195: Define this macro meaning that @code{gcc} should find the 196: library @file{libgcc.a} by hand, rather than passing the argument 197: @samp{-lgcc} to tell the linker to do the search. 198: 199: @findex RELATIVE_PREFIX_NOT_LINKDIR 200: @item RELATIVE_PREFIX_NOT_LINKDIR 201: Define this macro to tell @code{gcc} that it should only translate 202: a @samp{-B} prefix into a @samp{-L} linker option if the prefix 203: indicates an absolute file name. 204: 205: @findex STANDARD_EXEC_PREFIX 206: @item STANDARD_EXEC_PREFIX 207: Define this macro as a C string constant if you wish to override the 1.1.1.2 root 208: standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to 1.1 root 209: try when searching for the executable files of the compiler. 210: 211: @findex MD_EXEC_PREFIX 212: @item MD_EXEC_PREFIX 213: If defined, this macro is an additional prefix to try after 214: @code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 215: when the @samp{-b} option is used, or the compiler is built as a cross 216: compiler. 217: 218: @findex STANDARD_STARTFILE_PREFIX 219: @item STANDARD_STARTFILE_PREFIX 220: Define this macro as a C string constant if you wish to override the 1.1.1.3 root 221: standard choice of @file{/usr/local/lib/} as the default prefix to 1.1 root 222: try when searching for startup files such as @file{crt0.o}. 223: 224: @findex MD_STARTFILE_PREFIX 225: @item MD_STARTFILE_PREFIX 1.1.1.3 root 226: If defined, this macro supplies an additional prefix to try after the 227: standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 228: @samp{-b} option is used, or when the compiler is built as a cross 1.1 root 229: compiler. 230: 1.1.1.3 root 231: @findex MD_STARTFILE_PREFIX_1 232: @item MD_STARTFILE_PREFIX_1 233: If defined, this macro supplies yet another prefix to try after the 234: standard prefixes. It is not searched when the @samp{-b} option is 235: used, or when the compiler is built as a cross compiler. 236: 1.1 root 237: @findex LOCAL_INCLUDE_DIR 238: @item LOCAL_INCLUDE_DIR 239: Define this macro as a C string constant if you wish to override the 240: standard choice of @file{/usr/local/include} as the default prefix to 241: try when searching for local header files. @code{LOCAL_INCLUDE_DIR} 242: comes before @code{SYSTEM_INCLUDE_DIR} in the search order. 243: 244: Cross compilers do not use this macro and do not search either 245: @file{/usr/local/include} or its replacement. 246: 247: @findex SYSTEM_INCLUDE_DIR 248: @item SYSTEM_INCLUDE_DIR 249: Define this macro as a C string constant if you wish to specify a 250: system-specific directory to search for header files before the standard 251: directory. @code{SYSTEM_INCLUDE_DIR} comes before 252: @code{STANDARD_INCLUDE_DIR} in the search order. 253: 254: Cross compilers do not use this macro and do not search the directory 255: specified. 256: 257: @findex STANDARD_INCLUDE_DIR 258: @item STANDARD_INCLUDE_DIR 259: Define this macro as a C string constant if you wish to override the 260: standard choice of @file{/usr/include} as the default prefix to 261: try when searching for header files. 262: 263: Cross compilers do not use this macro and do not search either 264: @file{/usr/include} or its replacement. 265: 266: @findex INCLUDE_DEFAULTS 267: @item INCLUDE_DEFAULTS 268: Define this macro if you wish to override the entire default search path 269: for include files. The default search path includes 1.1.1.5 ! root 270: @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, ! 271: @code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and ! 272: @code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} ! 273: and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, ! 274: and specify private search areas for GCC. The directory ! 275: @code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 1.1 root 276: 277: The definition should be an initializer for an array of structures. 278: Each array element should have two elements: the directory name (a 279: string constant) and a flag for C++-only directories. Mark the end of 280: the array with a null element. For example, here is the definition used 281: for VMS: 282: 283: @example 284: #define INCLUDE_DEFAULTS \ 285: @{ \ 286: @{ "GNU_GXX_INCLUDE:", 1@}, \ 287: @{ "GNU_CC_INCLUDE:", 0@}, \ 288: @{ "SYS$SYSROOT:[SYSLIB.]", 0@}, \ 289: @{ ".", 0@}, \ 290: @{ 0, 0@} \ 291: @} 292: @end example 293: @end table 294: 295: Here is the order of prefixes tried for exec files: 296: 297: @enumerate 298: @item 299: Any prefixes specified by the user with @samp{-B}. 300: 301: @item 302: The environment variable @code{GCC_EXEC_PREFIX}, if any. 303: 304: @item 305: The directories specified by the environment variable @code{COMPILER_PATH}. 306: 307: @item 308: The macro @code{STANDARD_EXEC_PREFIX}. 309: 310: @item 311: @file{/usr/lib/gcc/}. 312: 313: @item 314: The macro @code{MD_EXEC_PREFIX}, if any. 315: @end enumerate 316: 317: Here is the order of prefixes tried for startfiles: 318: 319: @enumerate 320: @item 321: Any prefixes specified by the user with @samp{-B}. 322: 323: @item 324: The environment variable @code{GCC_EXEC_PREFIX}, if any. 325: 326: @item 327: The directories specified by the environment variable @code{LIBRARY_PATH}. 328: 329: @item 330: The macro @code{STANDARD_EXEC_PREFIX}. 331: 332: @item 333: @file{/usr/lib/gcc/}. 334: 335: @item 336: The macro @code{MD_EXEC_PREFIX}, if any. 337: 338: @item 339: The macro @code{MD_STARTFILE_PREFIX}, if any. 340: 341: @item 342: The macro @code{STANDARD_STARTFILE_PREFIX}. 343: 344: @item 345: @file{/lib/}. 346: 347: @item 348: @file{/usr/lib/}. 349: @end enumerate 350: 1.1.1.2 root 351: @node Run-time Target 1.1 root 352: @section Run-time Target Specification 353: @cindex run-time target specification 354: @cindex predefined macros 355: @cindex target specifications 356: 357: @table @code 358: @findex CPP_PREDEFINES 359: @item CPP_PREDEFINES 360: Define this to be a string constant containing @samp{-D} options to 361: define the predefined macros that identify this machine and system. 362: These macros will be predefined unless the @samp{-ansi} option is 363: specified. 364: 365: In addition, a parallel set of macros are predefined, whose names are 366: made by appending @samp{__} at the beginning and at the end. These 367: @samp{__} macros are permitted by the ANSI standard, so they are 368: predefined regardless of whether @samp{-ansi} is specified. 369: 370: For example, on the Sun, one can use the following value: 371: 1.1.1.5 ! root 372: @smallexample 1.1 root 373: "-Dmc68000 -Dsun -Dunix" 1.1.1.5 ! root 374: @end smallexample 1.1 root 375: 376: The result is to define the macros @code{__mc68000__}, @code{__sun__} 377: and @code{__unix__} unconditionally, and the macros @code{mc68000}, 378: @code{sun} and @code{unix} provided @samp{-ansi} is not specified. 379: 380: @findex STDC_VALUE 381: @item STDC_VALUE 382: Define the value to be assigned to the built-in macro @code{__STDC__}. 383: The default is the value @samp{1}. 384: 385: @findex extern int target_flags 386: @item extern int target_flags; 387: This declaration should be present. 388: 389: @cindex optional hardware or system features 390: @cindex features, optional, in system conventions 391: @item TARGET_@dots{} 392: This series of macros is to allow compiler command arguments to 393: enable or disable the use of optional features of the target machine. 394: For example, one machine description serves both the 68000 and 395: the 68020; a command argument tells the compiler whether it should 396: use 68020-only instructions or not. This command argument works 397: by means of a macro @code{TARGET_68020} that tests a bit in 398: @code{target_flags}. 399: 400: Define a macro @code{TARGET_@var{featurename}} for each such option. 401: Its definition should test a bit in @code{target_flags}; for example: 402: 1.1.1.5 ! root 403: @smallexample 1.1 root 404: #define TARGET_68020 (target_flags & 1) 1.1.1.5 ! root 405: @end smallexample 1.1 root 406: 407: One place where these macros are used is in the condition-expressions 408: of instruction patterns. Note how @code{TARGET_68020} appears 409: frequently in the 68000 machine description file, @file{m68k.md}. 410: Another place they are used is in the definitions of the other 411: macros in the @file{@var{machine}.h} file. 412: 413: @findex TARGET_SWITCHES 414: @item TARGET_SWITCHES 415: This macro defines names of command options to set and clear 416: bits in @code{target_flags}. Its definition is an initializer 417: with a subgrouping for each command option. 418: 419: Each subgrouping contains a string constant, that defines the option 420: name, and a number, which contains the bits to set in 421: @code{target_flags}. A negative number says to clear bits instead; 422: the negative of the number is which bits to clear. The actual option 423: name is made by appending @samp{-m} to the specified name. 424: 425: One of the subgroupings should have a null string. The number in 426: this grouping is the default value for @code{target_flags}. Any 427: target options act starting with that value. 428: 429: Here is an example which defines @samp{-m68000} and @samp{-m68020} 430: with opposite meanings, and picks the latter as the default: 431: 1.1.1.5 ! root 432: @smallexample 1.1 root 433: #define TARGET_SWITCHES \ 434: @{ @{ "68020", 1@}, \ 435: @{ "68000", -1@}, \ 436: @{ "", 1@}@} 1.1.1.5 ! root 437: @end smallexample 1.1 root 438: 439: @findex TARGET_OPTIONS 440: @item TARGET_OPTIONS 441: This macro is similar to @code{TARGET_SWITCHES} but defines names of command 442: options that have values. Its definition is an initializer with a 443: subgrouping for each command option. 444: 445: Each subgrouping contains a string constant, that defines the fixed part 446: of the option name, and the address of a variable. The variable, type 447: @code{char *}, is set to the variable part of the given option if the fixed 448: part matches. The actual option name is made by appending @samp{-m} to the 449: specified name. 450: 451: Here is an example which defines @samp{-mshort-data-@var{number}}. If the 452: given option is @samp{-mshort-data-512}, the variable @code{m88k_short_data} 453: will be set to the string @code{"512"}. 454: 1.1.1.5 ! root 455: @smallexample 1.1 root 456: extern char *m88k_short_data; 1.1.1.5 ! root 457: #define TARGET_OPTIONS \ ! 458: @{ @{ "short-data-", &m88k_short_data @} @} ! 459: @end smallexample 1.1 root 460: 461: @findex TARGET_VERSION 462: @item TARGET_VERSION 463: This macro is a C statement to print on @code{stderr} a string 464: describing the particular machine description choice. Every machine 465: description should define @code{TARGET_VERSION}. For example: 466: 1.1.1.5 ! root 467: @smallexample 1.1 root 468: #ifdef MOTOROLA 1.1.1.5 ! root 469: #define TARGET_VERSION \ ! 470: fprintf (stderr, " (68k, Motorola syntax)"); 1.1 root 471: #else 1.1.1.5 ! root 472: #define TARGET_VERSION \ ! 473: fprintf (stderr, " (68k, MIT syntax)"); 1.1 root 474: #endif 1.1.1.5 ! root 475: @end smallexample 1.1 root 476: 477: @findex OVERRIDE_OPTIONS 478: @item OVERRIDE_OPTIONS 479: Sometimes certain combinations of command options do not make sense on 480: a particular target machine. You can define a macro 481: @code{OVERRIDE_OPTIONS} to take account of this. This macro, if 482: defined, is executed once just after all the command options have been 483: parsed. 484: 485: Don't use this macro to turn on various extra optimizations for 486: @samp{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 487: 488: @findex OPTIMIZATION_OPTIONS 489: @item OPTIMIZATION_OPTIONS (@var{level}) 490: Some machines may desire to change what optimizations are performed for 491: various optimization levels. This macro, if defined, is executed once 492: just after the optimization level is determined and before the remainder 493: of the command options have been parsed. Values set in this macro are 494: used as the default values for the other command line options. 495: 496: @var{level} is the optimization level specified; 2 if -O2 is specified, 497: 1 if -O is specified, and 0 if neither is specified. 498: 499: @strong{Do not examine @code{write_symbols} in this macro!} 500: The debugging options are not supposed to alter the generated code. 501: @end table 502: 1.1.1.2 root 503: @node Storage Layout 1.1 root 504: @section Storage Layout 505: @cindex storage layout 506: 507: Note that the definitions of the macros in this table which are sizes or 508: alignments measured in bits do not need to be constant. They can be C 509: expressions that refer to static variables, such as the @code{target_flags}. 510: @xref{Run-time Target}. 511: 512: @table @code 513: @findex BITS_BIG_ENDIAN 514: @item BITS_BIG_ENDIAN 515: Define this macro to be the value 1 if the most significant bit in a 516: byte has the lowest number; otherwise define it to be the value zero. 517: This means that bit-field instructions count from the most significant 1.1.1.5 ! root 518: bit. If the machine has no bit-field instructions, then this must still ! 519: be defined, but it doesn't matter which value it is defined to. 1.1 root 520: 521: This macro does not affect the way structure fields are packed into 522: bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 523: 524: @findex BYTES_BIG_ENDIAN 525: @item BYTES_BIG_ENDIAN 526: Define this macro to be 1 if the most significant byte in a word has the 527: lowest number. 528: 529: @findex WORDS_BIG_ENDIAN 530: @item WORDS_BIG_ENDIAN 531: Define this macro to be 1 if, in a multiword object, the most 1.1.1.4 root 532: significant word has the lowest number. This applies to both memory 533: locations and registers; GNU CC fundamentally assumes that the order of 534: words in memory is the same as the order in registers. 1.1 root 535: 536: @findex BITS_PER_UNIT 537: @item BITS_PER_UNIT 1.1.1.5 ! root 538: Define this macro to be the number of bits in an addressable storage ! 539: unit (byte); normally 8. 1.1 root 540: 541: @findex BITS_PER_WORD 542: @item BITS_PER_WORD 543: Number of bits in a word; normally 32. 544: 545: @findex MAX_BITS_PER_WORD 546: @item MAX_BITS_PER_WORD 547: Maximum number of bits in a word. If this is undefined, the default is 548: @code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 549: largest value that @code{BITS_PER_WORD} can have at run-time. 550: 551: @findex UNITS_PER_WORD 552: @item UNITS_PER_WORD 553: Number of storage units in a word; normally 4. 554: 555: @findex POINTER_SIZE 556: @item POINTER_SIZE 557: Width of a pointer, in bits. 558: 1.1.1.4 root 559: @findex PROMOTE_MODE 560: @item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 561: A macro to update @var{m} and @var{unsignedp} when an object whose type 562: is @var{type} and which has the specified mode and signedness is to be 563: stored in a register. This macro is only called when @var{type} is a 564: scalar type. 565: 566: On most RISC machines, which only have operations that operate on a full 567: register, define this macro to set @var{m} to @code{word_mode} if 568: @var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 569: cases, only integer modes should be widened because wider-precision 570: floating-point operations are usually more expensive than their narrower 571: counterparts. 572: 573: For most machines, the macro definition does not change @var{unsignedp}. 574: However, some machines, have instructions that preferentially handle 1.1.1.5 ! root 575: either signed or unsigned quantities of certain modes. For example, on 1.1.1.4 root 576: the DEC Alpha, 32-bit loads from memory and 32-bit add instructions 577: sign-extend the result to 64 bits. On such machines, set 578: @var{unsignedp} according to which kind of extension is more efficient. 579: 580: Do not define this macro if it would never modify @var{m}. 581: 582: @findex PROMOTE_FUNCTION_ARGS 583: @item PROMOTE_FUNCTION_ARGS 584: Define this macro if the promotion described by @code{PROMOTE_MODE} 585: should also be done for outgoing function arguments. 586: 587: @findex PROMOTE_FUNCTION_RETURN 588: @item PROMOTE_FUNCTION_RETURN 589: Define this macro if the promotion described by @code{PROMOTE_MODE} 590: should also be done for the return value of functions. 591: 592: If this macro is defined, @code{FUNCTION_VALUE} must perform the same 593: promotions done by @code{PROMOTE_MODE}. 594: 1.1 root 595: @findex PARM_BOUNDARY 596: @item PARM_BOUNDARY 597: Normal alignment required for function parameters on the stack, in 1.1.1.4 root 598: bits. All stack parameters receive at least this much alignment 1.1 root 599: regardless of data type. On most machines, this is the same as the 600: size of an integer. 601: 602: @findex STACK_BOUNDARY 603: @item STACK_BOUNDARY 604: Define this macro if you wish to preserve a certain alignment for 605: the stack pointer. The definition is a C expression 606: for the desired alignment (measured in bits). 607: 608: @cindex @code{PUSH_ROUNDING}, interaction with @code{STACK_BOUNDARY} 609: If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned 610: to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies a 611: less strict alignment than @code{STACK_BOUNDARY}, the stack may be 612: momentarily unaligned while pushing arguments. 613: 614: @findex FUNCTION_BOUNDARY 615: @item FUNCTION_BOUNDARY 616: Alignment required for a function entry point, in bits. 617: 618: @findex BIGGEST_ALIGNMENT 619: @item BIGGEST_ALIGNMENT 620: Biggest alignment that any data type can require on this machine, in bits. 621: 622: @findex BIGGEST_FIELD_ALIGNMENT 623: @item BIGGEST_FIELD_ALIGNMENT 624: Biggest alignment that any structure field can require on this machine, 1.1.1.3 root 625: in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 626: structure fields only. 1.1 root 627: 628: @findex MAX_OFILE_ALIGNMENT 629: @item MAX_OFILE_ALIGNMENT 630: Biggest alignment supported by the object file format of this machine. 631: Use this macro to limit the alignment which can be specified using the 632: @code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 633: the default value is @code{BIGGEST_ALIGNMENT}. 634: 635: @findex DATA_ALIGNMENT 636: @item DATA_ALIGNMENT (@var{type}, @var{basic-align}) 637: If defined, a C expression to compute the alignment for a static 638: variable. @var{type} is the data type, and @var{basic-align} is the 639: alignment that the object would ordinarily have. The value of this 640: macro is used instead of that alignment to align the object. 641: 642: If this macro is not defined, then @var{basic-align} is used. 643: 644: @findex strcpy 645: One use of this macro is to increase alignment of medium-size data to 646: make it all fit in fewer cache lines. Another is to cause character 647: arrays to be word-aligned so that @code{strcpy} calls that copy 648: constants to character arrays can be done inline. 649: 650: @findex CONSTANT_ALIGNMENT 651: @item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 652: If defined, a C expression to compute the alignment given to a constant 653: that is being placed in memory. @var{constant} is the constant and 654: @var{basic-align} is the alignment that the object would ordinarily 655: have. The value of this macro is used instead of that alignment to 656: align the object. 657: 658: If this macro is not defined, then @var{basic-align} is used. 659: 660: The typical use of this macro is to increase alignment for string 661: constants to be word aligned so that @code{strcpy} calls that copy 662: constants can be done inline. 663: 664: @findex EMPTY_FIELD_BOUNDARY 665: @item EMPTY_FIELD_BOUNDARY 666: Alignment in bits to be given to a structure bit field that follows an 667: empty field such as @code{int : 0;}. 668: 1.1.1.2 root 669: Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment 670: that results from an empty field. 671: 1.1 root 672: @findex STRUCTURE_SIZE_BOUNDARY 673: @item STRUCTURE_SIZE_BOUNDARY 674: Number of bits which any structure or union's size must be a multiple of. 675: Each structure or union's size is rounded up to a multiple of this. 676: 677: If you do not define this macro, the default is the same as 678: @code{BITS_PER_UNIT}. 679: 680: @findex STRICT_ALIGNMENT 681: @item STRICT_ALIGNMENT 1.1.1.2 root 682: Define this macro to be the value 1 if instructions will fail to work 683: if given data not on the nominal alignment. If instructions will merely 684: go slower in that case, define this macro as 0. 1.1 root 685: 686: @findex PCC_BITFIELD_TYPE_MATTERS 687: @item PCC_BITFIELD_TYPE_MATTERS 688: Define this if you wish to imitate the way many other C compilers handle 689: alignment of bitfields and the structures that contain them. 690: 691: The behavior is that the type written for a bitfield (@code{int}, 692: @code{short}, or other integer type) imposes an alignment for the 693: entire structure, as if the structure really did contain an ordinary 694: field of that type. In addition, the bitfield is placed within the 695: structure so that it would fit within such a field, not crossing a 696: boundary for it. 697: 698: Thus, on most machines, a bitfield whose type is written as @code{int} 699: would not cross a four-byte boundary, and would force four-byte 700: alignment for the whole structure. (The alignment used may not be four 701: bytes; it is controlled by the other alignment parameters.) 702: 703: If the macro is defined, its definition should be a C expression; 704: a nonzero value for the expression enables this behavior. 705: 706: Note that if this macro is not defined, or its value is zero, some 707: bitfields may cross more than one alignment boundary. The compiler can 708: support such references if there are @samp{insv}, @samp{extv}, and 709: @samp{extzv} insns that can directly reference memory. 710: 711: The other known way of making bitfields work is to define 712: @code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 713: Then every structure can be accessed with fullwords. 714: 715: Unless the machine has bitfield instructions or you define 716: @code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 717: @code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 718: 1.1.1.4 root 719: If your aim is to make GNU CC use the same conventions for laying out 720: bitfields as are used by another compiler, here is how to investigate 721: what the other compiler does. Compile and run this program: 722: 723: @example 724: struct foo1 725: @{ 726: char x; 727: char :0; 728: char y; 729: @}; 730: 731: struct foo2 732: @{ 733: char x; 734: int :0; 735: char y; 736: @}; 737: 738: main () 739: @{ 1.1.1.5 ! root 740: printf ("Size of foo1 is %d\n", ! 741: sizeof (struct foo1)); ! 742: printf ("Size of foo2 is %d\n", ! 743: sizeof (struct foo2)); 1.1.1.4 root 744: exit (0); 745: @} 746: @end example 747: 748: If this prints 2 and 5, then the compiler's behavior is what you would 749: get from @code{PCC_BITFIELD_TYPE_MATTERS}. 750: 1.1 root 751: @findex BITFIELD_NBYTES_LIMITED 752: @item BITFIELD_NBYTES_LIMITED 753: Like PCC_BITFIELD_TYPE_MATTERS except that its effect is limited to 754: aligning a bitfield within the structure. 755: 756: @findex ROUND_TYPE_SIZE 757: @item ROUND_TYPE_SIZE (@var{struct}, @var{size}, @var{align}) 758: Define this macro as an expression for the overall size of a structure 759: (given by @var{struct} as a tree node) when the size computed from the 760: fields is @var{size} and the alignment is @var{align}. 761: 762: The default is to round @var{size} up to a multiple of @var{align}. 763: 764: @findex ROUND_TYPE_ALIGN 765: @item ROUND_TYPE_ALIGN (@var{struct}, @var{computed}, @var{specified}) 766: Define this macro as an expression for the alignment of a structure 767: (given by @var{struct} as a tree node) if the alignment computed in the 768: usual way is @var{computed} and the alignment explicitly specified was 769: @var{specified}. 770: 771: The default is to use @var{specified} if it is larger; otherwise, use 772: the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 773: 774: @findex MAX_FIXED_MODE_SIZE 775: @item MAX_FIXED_MODE_SIZE 776: An integer expression for the size in bits of the largest integer 777: machine mode that should actually be used. All integer machine modes of 778: this size or smaller can be used for structures and unions with the 779: appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 780: (DImode)} is assumed. 781: 782: @findex CHECK_FLOAT_VALUE 783: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value}) 784: A C statement to validate the value @var{value} (of type 785: @code{double}) for mode @var{mode}. This means that you check whether 786: @var{value} fits within the possible range of values for mode 787: @var{mode} on this target machine. The mode @var{mode} is always 788: @code{SFmode} or @code{DFmode}. 789: 790: @findex error 791: If @var{value} is not valid, you should call @code{error} to print an 792: error message and then assign some valid value to @var{value}. 793: Allowing an invalid value to go through the compiler can produce 794: incorrect assembler code which may even cause Unix assemblers to 795: crash. 796: 797: This macro need not be defined if there is no work for it to do. 798: 799: @findex TARGET_FLOAT_FORMAT 800: @item TARGET_FLOAT_FORMAT 801: A code distinguishing the floating point format of the target machine. 802: There are three defined values: 803: 804: @table @code 805: @findex IEEE_FLOAT_FORMAT 806: @item IEEE_FLOAT_FORMAT 807: This code indicates IEEE floating point. It is the default; there is no 808: need to define this macro when the format is IEEE. 809: 810: @findex VAX_FLOAT_FORMAT 811: @item VAX_FLOAT_FORMAT 812: This code indicates the peculiar format used on the Vax. 813: 814: @findex UNKNOWN_FLOAT_FORMAT 815: @item UNKNOWN_FLOAT_FORMAT 816: This code indicates any other format. 817: @end table 818: 819: The value of this macro is compared with @code{HOST_FLOAT_FORMAT} 820: (@pxref{Config}) to determine whether the target machine has the same 821: format as the host machine. If any other formats are actually in use on 822: supported machines, new codes should be defined for them. 823: @end table 824: 1.1.1.2 root 825: @node Type Layout 1.1 root 826: @section Layout of Source Language Data Types 827: 828: These macros define the sizes and other characteristics of the standard 829: basic data types used in programs being compiled. Unlike the macros in 830: the previous section, these apply to specific features of C and related 831: languages, rather than to fundamental aspects of storage layout. 832: 833: @table @code 834: @findex INT_TYPE_SIZE 835: @item INT_TYPE_SIZE 836: A C expression for the size in bits of the type @code{int} on the 837: target machine. If you don't define this, the default is one word. 838: 839: @findex SHORT_TYPE_SIZE 840: @item SHORT_TYPE_SIZE 841: A C expression for the size in bits of the type @code{short} on the 842: target machine. If you don't define this, the default is half a word. 843: (If this would be less than one storage unit, it is rounded up to one 844: unit.) 845: 846: @findex LONG_TYPE_SIZE 847: @item LONG_TYPE_SIZE 848: A C expression for the size in bits of the type @code{long} on the 849: target machine. If you don't define this, the default is one word. 850: 851: @findex LONG_LONG_TYPE_SIZE 852: @item LONG_LONG_TYPE_SIZE 853: A C expression for the size in bits of the type @code{long long} on the 854: target machine. If you don't define this, the default is two 855: words. 856: 857: @findex CHAR_TYPE_SIZE 858: @item CHAR_TYPE_SIZE 859: A C expression for the size in bits of the type @code{char} on the 860: target machine. If you don't define this, the default is one quarter 861: of a word. (If this would be less than one storage unit, it is rounded up 862: to one unit.) 863: 864: @findex FLOAT_TYPE_SIZE 865: @item FLOAT_TYPE_SIZE 866: A C expression for the size in bits of the type @code{float} on the 867: target machine. If you don't define this, the default is one word. 868: 869: @findex DOUBLE_TYPE_SIZE 870: @item DOUBLE_TYPE_SIZE 871: A C expression for the size in bits of the type @code{double} on the 872: target machine. If you don't define this, the default is two 873: words. 874: 875: @findex LONG_DOUBLE_TYPE_SIZE 876: @item LONG_DOUBLE_TYPE_SIZE 877: A C expression for the size in bits of the type @code{long double} on 878: the target machine. If you don't define this, the default is two 879: words. 880: 881: @findex DEFAULT_SIGNED_CHAR 882: @item DEFAULT_SIGNED_CHAR 883: An expression whose value is 1 or 0, according to whether the type 884: @code{char} should be signed or unsigned by default. The user can 885: always override this default with the options @samp{-fsigned-char} 886: and @samp{-funsigned-char}. 887: 888: @findex DEFAULT_SHORT_ENUMS 889: @item DEFAULT_SHORT_ENUMS 890: A C expression to determine whether to give an @code{enum} type 891: only as many bytes as it takes to represent the range of possible values 892: of that type. A nonzero value means to do that; a zero value means all 893: @code{enum} types should be allocated like @code{int}. 894: 895: If you don't define the macro, the default is 0. 896: 897: @findex SIZE_TYPE 898: @item SIZE_TYPE 899: A C expression for a string describing the name of the data type to use 900: for size values. The typedef name @code{size_t} is defined using the 901: contents of the string. 902: 903: The string can contain more than one keyword. If so, separate them with 904: spaces, and write first any length keyword, then @code{unsigned} if 905: appropriate, and finally @code{int}. The string must exactly match one 906: of the data type names defined in the function 907: @code{init_decl_processing} in the file @file{c-decl.c}. You may not 908: omit @code{int} or change the order---that would cause the compiler to 909: crash on startup. 910: 911: If you don't define this macro, the default is @code{"long unsigned 912: int"}. 913: 914: @findex PTRDIFF_TYPE 915: @item PTRDIFF_TYPE 916: A C expression for a string describing the name of the data type to use 917: for the result of subtracting two pointers. The typedef name 918: @code{ptrdiff_t} is defined using the contents of the string. See 919: @code{SIZE_TYPE} above for more information. 920: 921: If you don't define this macro, the default is @code{"long int"}. 922: 923: @findex WCHAR_TYPE 924: @item WCHAR_TYPE 925: A C expression for a string describing the name of the data type to use 926: for wide characters. The typedef name @code{wchar_t} is defined using 927: the contents of the string. See @code{SIZE_TYPE} above for more 928: information. 929: 930: If you don't define this macro, the default is @code{"int"}. 931: 932: @findex WCHAR_TYPE_SIZE 933: @item WCHAR_TYPE_SIZE 934: A C expression for the size in bits of the data type for wide 935: characters. This is used in @code{cpp}, which cannot make use of 936: @code{WCHAR_TYPE}. 937: 938: @findex OBJC_INT_SELECTORS 939: @item OBJC_INT_SELECTORS 940: Define this macro if the type of Objective C selectors should be 941: @code{int}. 942: 943: If this macro is not defined, then selectors should have the type 944: @code{struct objc_selector *}. 945: 1.1.1.3 root 946: @findex OBJC_SELECTORS_WITHOUT_LABELS 947: @item OBJC_SELECTORS_WITHOUT_LABELS 948: Define this macro if the compiler can group all the selectors together 949: into a vector and use just one label at the beginning of the vector. 950: Otherwise, the compiler must give each selector its own assembler 951: label. 952: 953: On certain machines, it is important to have a separate label for each 954: selector because this enables the linker to eliminate duplicate selectors. 1.1 root 955: 956: @findex TARGET_BELL 957: @item TARGET_BELL 958: A C constant expression for the integer value for escape sequence 959: @samp{\a}. 960: 961: @findex TARGET_TAB 962: @findex TARGET_BS 963: @findex TARGET_NEWLINE 964: @item TARGET_BS 965: @itemx TARGET_TAB 966: @itemx TARGET_NEWLINE 967: C constant expressions for the integer values for escape sequences 968: @samp{\b}, @samp{\t} and @samp{\n}. 969: 970: @findex TARGET_VT 971: @findex TARGET_FF 972: @findex TARGET_CR 973: @item TARGET_VT 974: @itemx TARGET_FF 975: @itemx TARGET_CR 976: C constant expressions for the integer values for escape sequences 977: @samp{\v}, @samp{\f} and @samp{\r}. 978: @end table 979: 1.1.1.2 root 980: @node Registers 1.1 root 981: @section Register Usage 982: @cindex register usage 983: 984: This section explains how to describe what registers the target machine 985: has, and how (in general) they can be used. 986: 987: The description of which registers a specific instruction can use is 988: done with register classes; see @ref{Register Classes}. For information 989: on using registers to access a stack frame, see @ref{Frame Registers}. 990: For passing values in registers, see @ref{Register Arguments}. 991: For returning values in registers, see @ref{Scalar Return}. 992: 993: @menu 994: * Register Basics:: Number and kinds of registers. 995: * Allocation Order:: Order in which registers are allocated. 996: * Values in Registers:: What kinds of values each reg can hold. 997: * Leaf Functions:: Renumbering registers for leaf functions. 998: * Stack Registers:: Handling a register stack such as 80387. 999: * Obsolete Register Macros:: Macros formerly used for the 80387. 1000: @end menu 1001: 1002: @node Register Basics 1003: @subsection Basic Characteristics of Registers 1004: 1005: @table @code 1006: @findex FIRST_PSEUDO_REGISTER 1007: @item FIRST_PSEUDO_REGISTER 1008: Number of hardware registers known to the compiler. They receive 1009: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 1010: pseudo register's number really is assigned the number 1011: @code{FIRST_PSEUDO_REGISTER}. 1012: 1013: @item FIXED_REGISTERS 1014: @findex FIXED_REGISTERS 1015: @cindex fixed register 1016: An initializer that says which registers are used for fixed purposes 1017: all throughout the compiled code and are therefore not available for 1018: general allocation. These would include the stack pointer, the frame 1019: pointer (except on machines where that can be used as a general 1020: register when no frame pointer is needed), the program counter on 1021: machines where that is considered one of the addressable registers, 1022: and any other numbered register with a standard use. 1023: 1024: This information is expressed as a sequence of numbers, separated by 1025: commas and surrounded by braces. The @var{n}th number is 1 if 1026: register @var{n} is fixed, 0 otherwise. 1027: 1028: The table initialized from this macro, and the table initialized by 1029: the following one, may be overridden at run time either automatically, 1030: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 1031: the user with the command options @samp{-ffixed-@var{reg}}, 1032: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}. 1033: 1034: @findex CALL_USED_REGISTERS 1035: @item CALL_USED_REGISTERS 1036: @cindex call-used register 1037: @cindex call-clobbered register 1038: @cindex call-saved register 1039: Like @code{FIXED_REGISTERS} but has 1 for each register that is 1040: clobbered (in general) by function calls as well as for fixed 1041: registers. This macro therefore identifies the registers that are not 1042: available for general allocation of values that must live across 1043: function calls. 1044: 1045: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 1046: automatically saves it on function entry and restores it on function 1047: exit, if the register is used within the function. 1048: 1049: @findex CONDITIONAL_REGISTER_USAGE 1050: @findex fixed_regs 1051: @findex call_used_regs 1052: @item CONDITIONAL_REGISTER_USAGE 1053: Zero or more C statements that may conditionally modify two variables 1054: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char 1055: []}) after they have been initialized from the two preceding macros. 1056: 1057: This is necessary in case the fixed or call-clobbered registers depend 1058: on target flags. 1059: 1060: You need not define this macro if it has no work to do. 1061: 1062: @cindex disabling certain registers 1063: @cindex controlling register usage 1064: If the usage of an entire class of registers depends on the target 1065: flags, you may indicate this to GCC by using this macro to modify 1066: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the 1067: registers in the classes which should not be used by GCC. Also define 1068: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it 1069: is called with a letter for a class that shouldn't be used. 1070: 1071: (However, if this class is not included in @code{GENERAL_REGS} and all 1072: of the insn patterns whose constraints permit this class are 1073: controlled by target switches, then GCC will automatically avoid using 1074: these registers when the target switches are opposed to them.) 1075: 1076: @findex NON_SAVING_SETJMP 1077: @item NON_SAVING_SETJMP 1078: If this macro is defined and has a nonzero value, it means that 1079: @code{setjmp} and related functions fail to save the registers, or that 1080: @code{longjmp} fails to restore them. To compensate, the compiler 1081: avoids putting variables in registers in functions that use 1082: @code{setjmp}. 1083: 1.1.1.5 ! root 1084: @findex INCOMING_REGNO ! 1085: @item INCOMING_REGNO (@var{out}) ! 1086: Define this macro if the target machine has register windows. This C ! 1087: expression returns the register number as seen by the called function ! 1088: corresponding to the register number @var{out} as seen by the calling ! 1089: function. Return @var{out} if register number @var{out} is not an ! 1090: outbound register. ! 1091: ! 1092: @findex OUTGOING_REGNO ! 1093: @item OUTGOING_REGNO (@var{in}) ! 1094: Define this macro if the target machine has register windows. This C ! 1095: expression returns the register number as seen by the calling function ! 1096: corresponding to the register number @var{in} as seen by the called ! 1097: function. Return @var{in} if register number @var{in} is not an inbound ! 1098: register. ! 1099: 1.1 root 1100: @ignore 1101: @findex PC_REGNUM 1102: @item PC_REGNUM 1103: If the program counter has a register number, define this as that 1104: register number. Otherwise, do not define it. 1105: @end ignore 1106: @end table 1107: 1108: @node Allocation Order 1109: @subsection Order of Allocation of Registers 1110: @cindex order of register allocation 1111: @cindex register allocation order 1112: 1113: @table @code 1114: @findex REG_ALLOC_ORDER 1115: @item REG_ALLOC_ORDER 1116: If defined, an initializer for a vector of integers, containing the 1117: numbers of hard registers in the order in which GNU CC should prefer 1118: to use them (from most preferred to least). 1119: 1120: If this macro is not defined, registers are used lowest numbered first 1121: (all else being equal). 1122: 1123: One use of this macro is on machines where the highest numbered 1124: registers must always be saved and the save-multiple-registers 1125: instruction supports only sequences of consecutive registers. On such 1126: machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 1127: the highest numbered allocatable register first. 1128: 1129: @findex ORDER_REGS_FOR_LOCAL_ALLOC 1130: @item ORDER_REGS_FOR_LOCAL_ALLOC 1131: A C statement (sans semicolon) to choose the order in which to allocate 1132: hard registers for pseudo-registers local to a basic block. 1133: 1.1.1.5 ! root 1134: Store the desired register order in the array @code{reg_alloc_order}. ! 1135: Element 0 should be the register to allocate first; element 1, the next ! 1136: register; and so on. 1.1 root 1137: 1138: The macro body should not assume anything about the contents of 1139: @code{reg_alloc_order} before execution of the macro. 1140: 1141: On most machines, it is not necessary to define this macro. 1142: @end table 1143: 1144: @node Values in Registers 1145: @subsection How Values Fit in Registers 1146: 1147: This section discusses the macros that describe which kinds of values 1148: (specifically, which machine modes) each register can hold, and how many 1149: consecutive registers are needed for a given mode. 1150: 1151: @table @code 1152: @findex HARD_REGNO_NREGS 1153: @item HARD_REGNO_NREGS (@var{regno}, @var{mode}) 1154: A C expression for the number of consecutive hard registers, starting 1155: at register number @var{regno}, required to hold a value of mode 1156: @var{mode}. 1157: 1158: On a machine where all registers are exactly one word, a suitable 1159: definition of this macro is 1160: 1.1.1.5 ! root 1161: @smallexample 1.1 root 1162: #define HARD_REGNO_NREGS(REGNO, MODE) \ 1163: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 1164: / UNITS_PER_WORD)) 1.1.1.5 ! root 1165: @end smallexample 1.1 root 1166: 1167: @findex HARD_REGNO_MODE_OK 1168: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 1169: A C expression that is nonzero if it is permissible to store a value 1170: of mode @var{mode} in hard register number @var{regno} (or in several 1171: registers starting with that one). For a machine where all registers 1172: are equivalent, a suitable definition is 1173: 1.1.1.5 ! root 1174: @smallexample 1.1 root 1175: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1 1.1.1.5 ! root 1176: @end smallexample 1.1 root 1177: 1178: It is not necessary for this macro to check for the numbers of fixed 1179: registers, because the allocation mechanism considers them to be always 1180: occupied. 1181: 1182: @cindex register pairs 1183: On some machines, double-precision values must be kept in even/odd 1184: register pairs. The way to implement that is to define this macro 1185: to reject odd register numbers for such modes. 1186: 1187: @ignore 1188: @c I think this is not true now 1189: GNU CC assumes that it can always move values between registers and 1190: (suitably addressed) memory locations. If it is impossible to move a 1191: value of a certain mode between memory and certain registers, then 1192: @code{HARD_REGNO_MODE_OK} must not allow this mode in those registers. 1193: @end ignore 1194: 1195: The minimum requirement for a mode to be OK in a register is that the 1196: @samp{mov@var{mode}} instruction pattern support moves between the 1197: register and any other hard register for which the mode is OK; and that 1198: moving a value into the register and back out not alter it. 1199: 1200: Since the same instruction used to move @code{SImode} will work for all 1201: narrower integer modes, it is not necessary on any machine for 1202: @code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 1203: you define patterns @samp{movhi}, etc., to take advantage of this. This 1204: is useful because of the interaction between @code{HARD_REGNO_MODE_OK} 1205: and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 1206: to be tieable. 1207: 1208: Many machines have special registers for floating point arithmetic. 1209: Often people assume that floating point machine modes are allowed only 1210: in floating point registers. This is not true. Any registers that 1211: can hold integers can safely @emph{hold} a floating point machine 1212: mode, whether or not floating arithmetic can be done on it in those 1213: registers. Integer move instructions can be used to move the values. 1214: 1215: On some machines, though, the converse is true: fixed-point machine 1216: modes may not go in floating registers. This is true if the floating 1217: registers normalize any value stored in them, because storing a 1218: non-floating value there would garble it. In this case, 1219: @code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 1220: floating registers. But if the floating registers do not automatically 1221: normalize, if you can store any bit pattern in one and retrieve it 1222: unchanged without a trap, then any machine mode may go in a floating 1.1.1.3 root 1223: register, so you can define this macro to say so. 1224: 1225: On some machines, such as the Sparc and the Mips, we get better code 1226: by defining @code{HARD_REGNO_MODE_OK} to forbid integers in floating 1227: registers, even though the hardware is capable of handling them. This 1228: is because transferring values between floating registers and general 1229: registers is so slow that it is better to keep the integer in memory. 1.1 root 1230: 1231: The primary significance of special floating registers is rather that 1232: they are the registers acceptable in floating point arithmetic 1233: instructions. However, this is of no concern to 1234: @code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 1235: constraints for those instructions. 1236: 1237: On some machines, the floating registers are especially slow to access, 1238: so that it is better to store a value in a stack frame than in such a 1239: register if floating point arithmetic is not being done. As long as the 1240: floating registers are not in class @code{GENERAL_REGS}, they will not 1241: be used unless some pattern's constraint asks for one. 1242: 1243: @findex MODES_TIEABLE_P 1244: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 1245: A C expression that is nonzero if it is desirable to choose register 1246: allocation so as to avoid move instructions between a value of mode 1247: @var{mode1} and a value of mode @var{mode2}. 1248: 1249: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 1250: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different 1251: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, 1252: @var{mode2})} must be zero. 1253: @end table 1254: 1255: @node Leaf Functions 1256: @subsection Handling Leaf Functions 1257: 1258: @cindex leaf functions 1259: @cindex functions, leaf 1.1.1.4 root 1260: On some machines, a leaf function (i.e., one which makes no calls) can run 1.1 root 1261: more efficiently if it does not make its own register window. Often this 1262: means it is required to receive its arguments in the registers where they 1263: are passed by the caller, instead of the registers where they would 1.1.1.3 root 1264: normally arrive. 1265: 1266: The special treatment for leaf functions generally applies only when 1267: other conditions are met; for example, often they may use only those 1268: registers for its own variables and temporaries. We use the term ``leaf 1269: function'' to mean a function that is suitable for this special 1270: handling, so that functions with no calls are not necessarily ``leaf 1271: functions''. 1.1 root 1272: 1273: GNU CC assigns register numbers before it knows whether the function is 1274: suitable for leaf function treatment. So it needs to renumber the 1275: registers in order to output a leaf function. The following macros 1276: accomplish this. 1277: 1278: @table @code 1279: @findex LEAF_REGISTERS 1280: @item LEAF_REGISTERS 1281: A C initializer for a vector, indexed by hard register number, which 1282: contains 1 for a register that is allowable in a candidate for leaf 1283: function treatment. 1284: 1285: If leaf function treatment involves renumbering the registers, then the 1286: registers marked here should be the ones before renumbering---those that 1287: GNU CC would ordinarily allocate. The registers which will actually be 1288: used in the assembler code, after renumbering, should not be marked with 1 1289: in this vector. 1290: 1291: Define this macro only if the target machine offers a way to optimize 1292: the treatment of leaf functions. 1293: 1294: @findex LEAF_REG_REMAP 1295: @item LEAF_REG_REMAP (@var{regno}) 1296: A C expression whose value is the register number to which @var{regno} 1297: should be renumbered, when a function is treated as a leaf function. 1298: 1299: If @var{regno} is a register number which should not appear in a leaf 1300: function before renumbering, then the expression should yield -1, which 1301: will cause the compiler to abort. 1302: 1303: Define this macro only if the target machine offers a way to optimize the 1304: treatment of leaf functions, and registers need to be renumbered to do 1305: this. 1306: 1307: @findex REG_LEAF_ALLOC_ORDER 1308: @item REG_LEAF_ALLOC_ORDER 1309: If defined, an initializer for a vector of integers, containing the 1310: numbers of hard registers in the order in which the GNU CC should prefer 1311: to use them (from most preferred to least) in a leaf function. If this 1312: macro is not defined, REG_ALLOC_ORDER is used for both non-leaf and 1313: leaf-functions. 1.1.1.5 ! root 1314: @c *important*.. is the above all-caps phrase supposed tobe in code ! 1315: @c font? --mew 2feb93 1.1 root 1316: @end table 1317: 1318: @findex leaf_function 1.1.1.5 ! root 1319: Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must ! 1320: treat leaf functions specially. It can test the C variable ! 1321: @code{leaf_function} which is nonzero for leaf functions. (The variable ! 1322: @code{leaf_function} is defined only if @code{LEAF_REGISTERS} is ! 1323: defined.) ! 1324: @c changed this to fix overfull. ALSO: why the "it" at the beginning ! 1325: @c of the next paragraph?! --mew 2feb93 1.1 root 1326: 1327: @node Stack Registers 1328: @subsection Registers That Form a Stack 1329: 1330: There are special features to handle computers where some of the 1331: ``registers'' form a stack, as in the 80387 coprocessor for the 80386. 1332: Stack registers are normally written by pushing onto the stack, and are 1333: numbered relative to the top of the stack. 1334: 1335: Currently, GNU CC can only handle one group of stack-like registers, and 1336: they must be consecutively numbered. 1337: 1338: @table @code 1339: @findex STACK_REGS 1340: @item STACK_REGS 1341: Define this if the machine has any stack-like registers. 1342: 1343: @findex FIRST_STACK_REG 1344: @item FIRST_STACK_REG 1345: The number of the first stack-like register. This one is the top 1346: of the stack. 1347: 1348: @findex LAST_STACK_REG 1349: @item LAST_STACK_REG 1350: The number of the last stack-like register. This one is the bottom of 1351: the stack. 1352: @end table 1353: 1354: @node Obsolete Register Macros 1355: @subsection Obsolete Macros for Controlling Register Usage 1356: 1357: These features do not work very well. They exist because they used to 1358: be required to generate correct code for the 80387 coprocessor of the 1359: 80386. They are no longer used by that machine description and may be 1360: removed in a later version of the compiler. Don't use them! 1361: 1362: @table @code 1363: @findex OVERLAPPING_REGNO_P 1364: @item OVERLAPPING_REGNO_P (@var{regno}) 1365: If defined, this is a C expression whose value is nonzero if hard 1366: register number @var{regno} is an overlapping register. This means a 1367: hard register which overlaps a hard register with a different number. 1368: (Such overlap is undesirable, but occasionally it allows a machine to 1369: be supported which otherwise could not be.) This macro must return 1370: nonzero for @emph{all} the registers which overlap each other. GNU CC 1371: can use an overlapping register only in certain limited ways. It can 1372: be used for allocation within a basic block, and may be spilled for 1373: reloading; that is all. 1374: 1375: If this macro is not defined, it means that none of the hard registers 1376: overlap each other. This is the usual situation. 1377: 1378: @findex INSN_CLOBBERS_REGNO_P 1379: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno}) 1380: If defined, this is a C expression whose value should be nonzero if 1381: the insn @var{insn} has the effect of mysteriously clobbering the 1382: contents of hard register number @var{regno}. By ``mysterious'' we 1383: mean that the insn's RTL expression doesn't describe such an effect. 1384: 1385: If this macro is not defined, it means that no insn clobbers registers 1386: mysteriously. This is the usual situation; all else being equal, 1387: it is best for the RTL expression to show all the activity. 1388: 1389: @cindex death notes 1390: @findex PRESERVE_DEATH_INFO_REGNO_P 1391: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno}) 1392: If defined, this is a C expression whose value is nonzero if accurate 1393: @code{REG_DEAD} notes are needed for hard register number @var{regno} 1394: at the time of outputting the assembler code. When this is so, a few 1395: optimizations that take place after register allocation and could 1396: invalidate the death notes are not done when this register is 1397: involved. 1398: 1399: You would arrange to preserve death info for a register when some of the 1400: code in the machine description which is executed to write the assembler 1401: code looks at the death notes. This is necessary only when the actual 1402: hardware feature which GNU CC thinks of as a register is not actually a 1403: register of the usual sort. (It might, for example, be a hardware 1404: stack.) 1405: 1406: If this macro is not defined, it means that no death notes need to be 1407: preserved. This is the usual situation. 1408: @end table 1409: 1.1.1.2 root 1410: @node Register Classes 1.1 root 1411: @section Register Classes 1412: @cindex register class definitions 1413: @cindex class definitions, register 1414: 1415: On many machines, the numbered registers are not all equivalent. 1416: For example, certain registers may not be allowed for indexed addressing; 1417: certain registers may not be allowed in some instructions. These machine 1418: restrictions are described to the compiler using @dfn{register classes}. 1419: 1420: You define a number of register classes, giving each one a name and saying 1421: which of the registers belong to it. Then you can specify register classes 1422: that are allowed as operands to particular instruction patterns. 1423: 1424: @findex ALL_REGS 1425: @findex NO_REGS 1426: In general, each register will belong to several classes. In fact, one 1427: class must be named @code{ALL_REGS} and contain all the registers. Another 1428: class must be named @code{NO_REGS} and contain no registers. Often the 1429: union of two classes will be another class; however, this is not required. 1430: 1431: @findex GENERAL_REGS 1432: One of the classes must be named @code{GENERAL_REGS}. There is nothing 1433: terribly special about the name, but the operand constraint letters 1434: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 1435: the same as @code{ALL_REGS}, just define it as a macro which expands 1436: to @code{ALL_REGS}. 1437: 1438: Order the classes so that if class @var{x} is contained in class @var{y} 1439: then @var{x} has a lower class number than @var{y}. 1440: 1441: The way classes other than @code{GENERAL_REGS} are specified in operand 1442: constraints is through machine-dependent operand constraint letters. 1443: You can define such letters to correspond to various classes, then use 1444: them in operand constraints. 1445: 1446: You should define a class for the union of two classes whenever some 1447: instruction allows both classes. For example, if an instruction allows 1448: either a floating point (coprocessor) register or a general register for a 1449: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 1450: which includes both of them. Otherwise you will get suboptimal code. 1451: 1452: You must also specify certain redundant information about the register 1453: classes: for each class, which classes contain it and which ones are 1454: contained in it; for each pair of classes, the largest class contained 1455: in their union. 1456: 1457: When a value occupying several consecutive registers is expected in a 1458: certain class, all the registers used must belong to that class. 1459: Therefore, register classes cannot be used to enforce a requirement for 1460: a register pair to start with an even-numbered register. The way to 1461: specify this requirement is with @code{HARD_REGNO_MODE_OK}. 1462: 1463: Register classes used for input-operands of bitwise-and or shift 1464: instructions have a special requirement: each such class must have, for 1465: each fixed-point machine mode, a subclass whose registers can transfer that 1466: mode to or from memory. For example, on some machines, the operations for 1467: single-byte values (@code{QImode}) are limited to certain registers. When 1468: this is so, each register class that is used in a bitwise-and or shift 1469: instruction must have a subclass consisting of registers from which 1470: single-byte values can be loaded or stored. This is so that 1471: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 1472: 1473: @table @code 1474: @findex enum reg_class 1475: @item enum reg_class 1476: An enumeral type that must be defined with all the register class names 1477: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} 1478: must be the last register class, followed by one more enumeral value, 1479: @code{LIM_REG_CLASSES}, which is not a register class but rather 1480: tells how many classes there are. 1481: 1482: Each register class has a number, which is the value of casting 1483: the class name to type @code{int}. The number serves as an index 1484: in many of the tables described below. 1485: 1486: @findex N_REG_CLASSES 1487: @item N_REG_CLASSES 1488: The number of distinct register classes, defined as follows: 1489: 1490: @example 1491: #define N_REG_CLASSES (int) LIM_REG_CLASSES 1492: @end example 1493: 1494: @findex REG_CLASS_NAMES 1495: @item REG_CLASS_NAMES 1496: An initializer containing the names of the register classes as C string 1497: constants. These names are used in writing some of the debugging dumps. 1498: 1499: @findex REG_CLASS_CONTENTS 1500: @item REG_CLASS_CONTENTS 1501: An initializer containing the contents of the register classes, as integers 1502: which are bit masks. The @var{n}th integer specifies the contents of class 1503: @var{n}. The way the integer @var{mask} is interpreted is that 1504: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 1505: 1506: When the machine has more than 32 registers, an integer does not suffice. 1507: Then the integers are replaced by sub-initializers, braced groupings containing 1508: several integers. Each sub-initializer must be suitable as an initializer 1509: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 1510: 1511: @findex REGNO_REG_CLASS 1512: @item REGNO_REG_CLASS (@var{regno}) 1513: A C expression whose value is a register class containing hard register 1.1.1.4 root 1514: @var{regno}. In general there is more than one such class; choose a class 1.1 root 1515: which is @dfn{minimal}, meaning that no smaller class also contains the 1516: register. 1517: 1518: @findex BASE_REG_CLASS 1519: @item BASE_REG_CLASS 1520: A macro whose definition is the name of the class to which a valid 1521: base register must belong. A base register is one used in an address 1522: which is the register value plus a displacement. 1523: 1524: @findex INDEX_REG_CLASS 1525: @item INDEX_REG_CLASS 1526: A macro whose definition is the name of the class to which a valid 1527: index register must belong. An index register is one used in an 1528: address where its value is either multiplied by a scale factor or 1529: added to another register (as well as added to a displacement). 1530: 1531: @findex REG_CLASS_FROM_LETTER 1532: @item REG_CLASS_FROM_LETTER (@var{char}) 1533: A C expression which defines the machine-dependent operand constraint 1534: letters for register classes. If @var{char} is such a letter, the 1535: value should be the register class corresponding to it. Otherwise, 1.1.1.2 root 1536: the value should be @code{NO_REGS}. The register letter @samp{r}, 1537: corresponding to class @code{GENERAL_REGS}, will not be passed 1538: to this macro; you do not need to handle it. 1.1 root 1539: 1540: @findex REGNO_OK_FOR_BASE_P 1541: @item REGNO_OK_FOR_BASE_P (@var{num}) 1542: A C expression which is nonzero if register number @var{num} is 1543: suitable for use as a base register in operand addresses. It may be 1544: either a suitable hard register or a pseudo register that has been 1545: allocated such a hard register. 1546: 1547: @findex REGNO_OK_FOR_INDEX_P 1548: @item REGNO_OK_FOR_INDEX_P (@var{num}) 1549: A C expression which is nonzero if register number @var{num} is 1550: suitable for use as an index register in operand addresses. It may be 1551: either a suitable hard register or a pseudo register that has been 1552: allocated such a hard register. 1553: 1554: The difference between an index register and a base register is that 1555: the index register may be scaled. If an address involves the sum of 1556: two registers, neither one of them scaled, then either one may be 1557: labeled the ``base'' and the other the ``index''; but whichever 1558: labeling is used must fit the machine's constraints of which registers 1559: may serve in each capacity. The compiler will try both labelings, 1560: looking for one that is valid, and will reload one or both registers 1561: only if neither labeling works. 1562: 1563: @findex PREFERRED_RELOAD_CLASS 1564: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 1565: A C expression that places additional restrictions on the register class 1566: to use when it is necessary to copy value @var{x} into a register in class 1567: @var{class}. The value is a register class; perhaps @var{class}, or perhaps 1.1.1.5 ! root 1568: another, smaller class. On many machines, the following definition is ! 1569: safe: 1.1 root 1570: 1571: @example 1572: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 1573: @end example 1574: 1575: Sometimes returning a more restrictive class makes better code. For 1576: example, on the 68000, when @var{x} is an integer constant that is in range 1577: for a @samp{moveq} instruction, the value of this macro is always 1578: @code{DATA_REGS} as long as @var{class} includes the data registers. 1579: Requiring a data register guarantees that a @samp{moveq} will be used. 1580: 1581: If @var{x} is a @code{const_double}, by returning @code{NO_REGS} 1582: you can force @var{x} into a memory constant. This is useful on 1583: certain machines where immediate floating values cannot be loaded into 1584: certain kinds of registers. 1585: 1.1.1.4 root 1586: @findex PREFERRED_OUTPUT_RELOAD_CLASS 1587: @item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 1588: Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 1589: input reloads. If you don't define this macro, the default is to use 1590: @var{class}, unchanged. 1591: 1.1 root 1592: @findex LIMIT_RELOAD_CLASS 1593: @item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 1594: A C expression that places additional restrictions on the register class 1595: to use when it is necessary to be able to hold a value of mode 1596: @var{mode} in a reload register for which class @var{class} would 1597: ordinarily be used. 1598: 1599: Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 1600: there are certain modes that simply can't go in certain reload classes. 1601: 1602: The value is a register class; perhaps @var{class}, or perhaps another, 1603: smaller class. 1604: 1605: Don't define this macro unless the target machine has limitations which 1606: require the macro to do something nontrivial. 1607: 1608: @findex SECONDARY_RELOAD_CLASS 1609: @findex SECONDARY_INPUT_RELOAD_CLASS 1610: @findex SECONDARY_OUTPUT_RELOAD_CLASS 1611: @item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 1612: @itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 1613: @itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 1614: Many machines have some registers that cannot be copied directly to or 1615: from memory or even from other types of registers. An example is the 1616: @samp{MQ} register, which on most machines, can only be copied to or 1617: from general registers, but not memory. Some machines allow copying all 1618: registers to and from memory, but require a scratch register for stores 1619: to some memory locations (e.g., those with symbolic address on the RT, 1620: and those with certain symbolic address on the Sparc when compiling 1621: PIC). In some cases, both an intermediate and a scratch register are 1622: required. 1623: 1624: You should define these macros to indicate to the reload phase that it may 1625: need to allocate at least one register for a reload in addition to the 1626: register to contain the data. Specifically, if copying @var{x} to a 1627: register @var{class} in @var{mode} requires an intermediate register, 1628: you should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 1629: largest register class all of whose registers can be used as 1630: intermediate registers or scratch registers. 1631: 1632: If copying a register @var{class} in @var{mode} to @var{x} requires an 1.1.1.5 ! root 1633: intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} ! 1634: should be defined to return the largest register class required. If the ! 1635: requirements for input and output reloads are the same, the macro ! 1636: @code{SECONDARY_RELOAD_CLASS} should be used instead of defining both ! 1637: macros identically. 1.1 root 1638: 1639: The values returned by these macros are often @code{GENERAL_REGS}. 1640: Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 1641: can be directly copied to or from a register of @var{class} in 1642: @var{mode} without requiring a scratch register. Do not define this 1643: macro if it would always return @code{NO_REGS}. 1644: 1645: If a scratch register is required (either with or without an 1646: intermediate register), you should define patterns for 1647: @samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 1648: (@pxref{Standard Names}. These patterns, which will normally be 1649: implemented with a @code{define_expand}, should be similar to the 1650: @samp{mov@var{m}} patterns, except that operand 2 is the scratch 1651: register. 1652: 1653: Define constraints for the reload register and scratch register that 1654: contain a single register class. If the original reload register (whose 1655: class is @var{class}) can meet the constraint given in the pattern, the 1656: value returned by these macros is used for the class of the scratch 1657: register. Otherwise, two additional reload registers are required. 1658: Their classes are obtained from the constraints in the insn pattern. 1659: 1660: @var{x} might be a pseudo-register or a @code{subreg} of a 1661: pseudo-register, which could either be in a hard register or in memory. 1662: Use @code{true_regnum} to find out; it will return -1 if the pseudo is 1663: in memory and the hard register number if it is in a register. 1664: 1665: These macros should not be used in the case where a particular class of 1666: registers can only be copied to memory and not to another class of 1667: registers. In that case, secondary reload registers are not needed and 1668: would not be helpful. Instead, a stack location must be used to perform 1669: the copy and the @code{mov@var{m}} pattern should use memory as a 1670: intermediate storage. This case often occurs between floating-point and 1671: general registers. 1672: 1.1.1.4 root 1673: @findex SECONDARY_MEMORY_NEEDED 1674: @item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 1675: Certain machines have the property that some registers cannot be copied 1676: to some other registers without using memory. Define this macro on 1677: those machines to be a C expression that is non-zero if objects of mode 1678: @var{m} in registers of @var{class1} can only be copied to registers of 1679: class @var{class2} by storing a register of @var{class1} into memory 1680: and loading that memory location into a register of @var{class2}. 1681: 1682: Do not define this macro if its value would always be zero. 1683: 1.1.1.5 ! root 1684: @findex SECONDARY_MEMORY_NEEDED_RTX ! 1685: @item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) ! 1686: Normally, when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler ! 1687: will allocate a stack slot when a memory location for a register copy ! 1688: is needed. If this macro is defined, the compiler instead uses the ! 1689: memory location defined by this macro. ! 1690: 1.1 root 1691: @findex SMALL_REGISTER_CLASSES 1692: @item SMALL_REGISTER_CLASSES 1693: Normally the compiler will avoid choosing spill registers from registers 1694: that have been explicitly mentioned in the rtl (these registers are 1695: normally those used to pass parameters and return values). However, 1696: some machines have so few registers of certain classes that there would 1697: not be enough registers to use as spill registers if this were done. 1698: 1.1.1.5 ! root 1699: You should define @code{SMALL_REGISTER_CLASSES} on those machines. When ! 1700: it is defined, the compiler allows registers explicitly used in the rtl ! 1701: to be used as spill registers but prevents the compiler from extending ! 1702: the lifetime of these registers. 1.1 root 1703: 1704: Defining this macro is always safe, but unnecessarily defining this macro 1705: will reduce the amount of optimizations that can be performed in some 1706: cases. If this macro is not defined but needs to be, the compiler will 1707: run out of reload registers and print a fatal error message. 1708: 1709: For most machines, this macro should not be defined. 1710: 1.1.1.5 ! root 1711: @findex CLASS_LIKELY_SPILLED_P ! 1712: @item CLASS_LIKELY_SPILLED_P (@var{class}) ! 1713: A C expression whose value is nonzero if pseudos that have been assigned ! 1714: to registers of class @var{class} would likely be spilled because ! 1715: registers of @var{class} are needed for spill registers. ! 1716: ! 1717: The default value of this macro returns 1 if @var{class} has exactly one ! 1718: register and zero otherwise. On most machines, this default should be ! 1719: used. Only define this macro to some other expression if pseudo ! 1720: allocated by @file{local-alloc.c} end up in memory because their hard ! 1721: registers were needed for spill regisers. If this macro returns nonzero ! 1722: for those classes, those pseudos will only be allocated by ! 1723: @file{global.c}, which knows how to reallocate the pseudo to another ! 1724: register. If there would not be another register available for ! 1725: reallocation, you should not change the definition of this macro since ! 1726: the only effect of such a definition would be to slow down register ! 1727: allocation. ! 1728: 1.1 root 1729: @findex CLASS_MAX_NREGS 1730: @item CLASS_MAX_NREGS (@var{class}, @var{mode}) 1731: A C expression for the maximum number of consecutive registers 1732: of class @var{class} needed to hold a value of mode @var{mode}. 1733: 1734: This is closely related to the macro @code{HARD_REGNO_NREGS}. 1735: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 1736: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})} 1737: for all @var{regno} values in the class @var{class}. 1738: 1739: This macro helps control the handling of multiple-word values 1740: in the reload pass. 1741: @end table 1742: 1743: Three other special macros describe which operands fit which constraint 1744: letters. 1745: 1746: @table @code 1747: @findex CONST_OK_FOR_LETTER_P 1748: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 1749: A C expression that defines the machine-dependent operand constraint letters 1750: that specify particular ranges of integer values. If @var{c} is one 1751: of those letters, the expression should check that @var{value}, an integer, 1752: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is 1753: not one of those letters, the value should be 0 regardless of @var{value}. 1754: 1755: @findex CONST_DOUBLE_OK_FOR_LETTER_P 1756: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 1757: A C expression that defines the machine-dependent operand constraint 1758: letters that specify particular ranges of @code{const_double} values. 1759: 1760: If @var{c} is one of those letters, the expression should check that 1761: @var{value}, an RTX of code @code{const_double}, is in the appropriate 1762: range and return 1 if so, 0 otherwise. If @var{c} is not one of those 1763: letters, the value should be 0 regardless of @var{value}. 1764: 1765: @code{const_double} is used for all floating-point constants and for 1766: @code{DImode} fixed-point constants. A given letter can accept either 1767: or both kinds of values. It can use @code{GET_MODE} to distinguish 1768: between these kinds. 1769: 1770: @findex EXTRA_CONSTRAINT 1771: @item EXTRA_CONSTRAINT (@var{value}, @var{c}) 1772: A C expression that defines the optional machine-dependent constraint 1773: letters that can be used to segregate specific types of operands, 1774: usually memory references, for the target machine. Normally this macro 1775: will not be defined. If it is required for a particular target machine, 1776: it should return 1 if @var{value} corresponds to the operand type 1777: represented by the constraint letter @var{c}. If @var{c} is not defined 1778: as an extra constraint, the value returned should be 0 regardless of 1779: @var{value}. 1780: 1781: For example, on the ROMP, load instructions cannot have their output in r0 if 1782: the memory reference contains a symbolic address. Constraint letter 1783: @samp{Q} is defined as representing a memory address that does 1784: @emph{not} contain a symbolic address. An alternative is specified with 1785: a @samp{Q} constraint on the input and @samp{r} on the output. The next 1786: alternative specifies @samp{m} on the input and a register class that 1787: does not include r0 on the output. 1788: @end table 1789: 1.1.1.2 root 1790: @node Stack and Calling 1.1.1.5 ! root 1791: @section Stack Layout and Calling Conventions 1.1 root 1792: @cindex calling conventions 1793: 1794: @menu 1795: * Frame Layout:: 1796: * Frame Registers:: 1797: * Elimination:: 1798: * Stack Arguments:: 1799: * Register Arguments:: 1800: * Scalar Return:: 1801: * Aggregate Return:: 1802: * Caller Saves:: 1803: * Function Entry:: 1804: * Profiling:: 1805: @end menu 1806: 1807: @node Frame Layout 1808: @subsection Basic Stack Layout 1809: @cindex stack frame layout 1810: @cindex frame layout 1811: 1812: @table @code 1813: @findex STACK_GROWS_DOWNWARD 1814: @item STACK_GROWS_DOWNWARD 1815: Define this macro if pushing a word onto the stack moves the stack 1816: pointer to a smaller address. 1817: 1818: When we say, ``define this macro if @dots{},'' it means that the 1819: compiler checks this macro only with @code{#ifdef} so the precise 1820: definition used does not matter. 1821: 1822: @findex FRAME_GROWS_DOWNWARD 1823: @item FRAME_GROWS_DOWNWARD 1824: Define this macro if the addresses of local variable slots are at negative 1825: offsets from the frame pointer. 1826: 1827: @findex ARGS_GROW_DOWNWARD 1828: @item ARGS_GROW_DOWNWARD 1829: Define this macro if successive arguments to a function occupy decreasing 1830: addresses on the stack. 1831: 1832: @findex STARTING_FRAME_OFFSET 1833: @item STARTING_FRAME_OFFSET 1834: Offset from the frame pointer to the first local variable slot to be allocated. 1835: 1.1.1.5 ! root 1836: If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by ! 1837: subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. ! 1838: Otherwise, it is found by adding the length of the first slot to the ! 1839: value @code{STARTING_FRAME_OFFSET}. ! 1840: @c i'm not sure if the above is still correct.. had to change it to get ! 1841: @c rid of an overfull. --mew 2feb93 1.1 root 1842: 1843: @findex STACK_POINTER_OFFSET 1844: @item STACK_POINTER_OFFSET 1845: Offset from the stack pointer register to the first location at which 1846: outgoing arguments are placed. If not specified, the default value of 1847: zero is used. This is the proper value for most machines. 1848: 1849: If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 1850: the first location at which outgoing arguments are placed. 1851: 1852: @findex FIRST_PARM_OFFSET 1853: @item FIRST_PARM_OFFSET (@var{fundecl}) 1854: Offset from the argument pointer register to the first argument's 1855: address. On some machines it may depend on the data type of the 1856: function. 1857: 1858: If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 1859: the first argument's address. 1860: 1861: @findex STACK_DYNAMIC_OFFSET 1862: @item STACK_DYNAMIC_OFFSET (@var{fundecl}) 1863: Offset from the stack pointer register to an item dynamically allocated 1864: on the stack, e.g., by @code{alloca}. 1865: 1866: The default value for this macro is @code{STACK_POINTER_OFFSET} plus the 1867: length of the outgoing arguments. The default is correct for most 1868: machines. See @file{function.c} for details. 1869: 1870: @findex DYNAMIC_CHAIN_ADDRESS 1871: @item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 1872: A C expression whose value is RTL representing the address in a stack 1873: frame where the pointer to the caller's frame is stored. Assume that 1874: @var{frameaddr} is an RTL expression for the address of the stack frame 1875: itself. 1876: 1877: If you don't define this macro, the default is to return the value 1878: of @var{frameaddr}---that is, the stack frame address is also the 1879: address of the stack word that points to the previous frame. 1.1.1.5 ! root 1880: ! 1881: @findex SETUP_FRAME_ADDRESSES ! 1882: @item SERTUP_FRAME_ADDRESSES () ! 1883: If defined, a C expression that produces the machine-specific code to ! 1884: setup the stack so that arbitrary frames can be accessed. For example, ! 1885: on the Sparc, we must flush all of the register windows to the stack ! 1886: before we can access arbitrary stack frames. ! 1887: This macro will seldom need to be defined. ! 1888: ! 1889: @findex RETURN_ADDR_RTX ! 1890: @item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) ! 1891: A C expression whose value is RTL representing the value of the return ! 1892: address for the frame @var{count} steps up from the current frame. ! 1893: @var{frameaddr} is the frame pointer of the @var{count} frame, or ! 1894: the frame pointer of the @var{count} @minus{} 1 frame if ! 1895: @code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. ! 1896: ! 1897: @findex RETURN_ADDR_IN_PREVIOUS_FRAME ! 1898: @item RETURN_ADDR_IN_PREVIOUS_FRAME ! 1899: Define this if the return address of a particular stack frame is accessed ! 1900: from the frame pointer of the previous stack frame. 1.1 root 1901: @end table 1902: 1903: @node Frame Registers 1904: @subsection Registers That Address the Stack Frame 1905: 1906: @table @code 1907: @findex STACK_POINTER_REGNUM 1908: @item STACK_POINTER_REGNUM 1909: The register number of the stack pointer register, which must also be a 1910: fixed register according to @code{FIXED_REGISTERS}. On most machines, 1911: the hardware determines which register this is. 1912: 1913: @findex FRAME_POINTER_REGNUM 1914: @item FRAME_POINTER_REGNUM 1915: The register number of the frame pointer register, which is used to 1916: access automatic variables in the stack frame. On some machines, the 1917: hardware determines which register this is. On other machines, you can 1918: choose any register you wish for this purpose. 1919: 1920: @findex ARG_POINTER_REGNUM 1921: @item ARG_POINTER_REGNUM 1922: The register number of the arg pointer register, which is used to access 1923: the function's argument list. On some machines, this is the same as the 1924: frame pointer register. On some machines, the hardware determines which 1925: register this is. On other machines, you can choose any register you 1926: wish for this purpose. If this is not the same register as the frame 1927: pointer register, then you must mark it as a fixed register according to 1928: @code{FIXED_REGISTERS}, or arrange to be able to eliminate it 1929: (@pxref{Elimination}). 1930: 1931: @findex STATIC_CHAIN_REGNUM 1932: @findex STATIC_CHAIN_INCOMING_REGNUM 1933: @item STATIC_CHAIN_REGNUM 1934: @itemx STATIC_CHAIN_INCOMING_REGNUM 1.1.1.5 ! root 1935: Register numbers used for passing a function's static chain pointer. If ! 1936: register windows are used, the register number as seen by the called ! 1937: function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register ! 1938: number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If ! 1939: these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need ! 1940: not be defined.@refill 1.1 root 1941: 1942: The static chain register need not be a fixed register. 1943: 1944: If the static chain is passed in memory, these macros should not be 1945: defined; instead, the next two macros should be defined. 1946: 1947: @findex STATIC_CHAIN 1948: @findex STATIC_CHAIN_INCOMING 1949: @item STATIC_CHAIN 1950: @itemx STATIC_CHAIN_INCOMING 1951: If the static chain is passed in memory, these macros provide rtx giving 1952: @code{mem} expressions that denote where they are stored. 1953: @code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 1954: as seen by the calling and called functions, respectively. Often the former 1955: will be at an offset from the stack pointer and the latter at an offset from 1956: the frame pointer.@refill 1957: 1958: @findex stack_pointer_rtx 1959: @findex frame_pointer_rtx 1960: @findex arg_pointer_rtx 1961: The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 1962: @code{arg_pointer_rtx} will have been initialized prior to the use of these 1963: macros and should be used to refer to those items. 1964: 1965: If the static chain is passed in a register, the two previous macros should 1966: be defined instead. 1967: @end table 1968: 1969: @node Elimination 1970: @subsection Eliminating Frame Pointer and Arg Pointer 1971: 1972: @table @code 1973: @findex FRAME_POINTER_REQUIRED 1974: @item FRAME_POINTER_REQUIRED 1975: A C expression which is nonzero if a function must have and use a frame 1976: pointer. This expression is evaluated in the reload pass. If its value is 1977: nonzero the function will have a frame pointer. 1978: 1979: The expression can in principle examine the current function and decide 1980: according to the facts, but on most machines the constant 0 or the 1981: constant 1 suffices. Use 0 when the machine allows code to be generated 1982: with no frame pointer, and doing so saves some time or space. Use 1 1983: when there is no possible advantage to avoiding a frame pointer. 1984: 1985: In certain cases, the compiler does not know how to produce valid code 1986: without a frame pointer. The compiler recognizes those cases and 1987: automatically gives the function a frame pointer regardless of what 1988: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 1989: them.@refill 1990: 1991: In a function that does not require a frame pointer, the frame pointer 1992: register can be allocated for ordinary usage, unless you mark it as a 1993: fixed register. See @code{FIXED_REGISTERS} for more information. 1994: 1.1.1.5 ! root 1995: This macro is ignored and you do not need to define it if the function ! 1996: @code{ELIMINABLE_REGS} is defined. 1.1 root 1997: 1998: @findex INITIAL_FRAME_POINTER_OFFSET 1999: @findex get_frame_size 2000: @item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 2001: A C statement to store in the variable @var{depth-var} the difference 2002: between the frame pointer and the stack pointer values immediately after 2003: the function prologue. The value would be computed from information 2004: such as the result of @code{get_frame_size ()} and the tables of 2005: registers @code{regs_ever_live} and @code{call_used_regs}. 2006: 2007: If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 2008: need not be defined. Otherwise, it must be defined even if 2009: @code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 2010: case, you may set @var{depth-var} to anything. 2011: 2012: @findex ELIMINABLE_REGS 2013: @item ELIMINABLE_REGS 2014: If defined, this macro specifies a table of register pairs used to 2015: eliminate unneeded registers that point into the stack frame. If it is not 2016: defined, the only elimination attempted by the compiler is to replace 2017: references to the frame pointer with references to the stack pointer. 2018: 2019: The definition of this macro is a list of structure initializations, each 2020: of which specifies an original and replacement register. 2021: 2022: On some machines, the position of the argument pointer is not known until 2023: the compilation is completed. In such a case, a separate hard register 2024: must be used for the argument pointer. This register can be eliminated by 2025: replacing it with either the frame pointer or the argument pointer, 2026: depending on whether or not the frame pointer has been eliminated. 2027: 2028: In this case, you might specify: 2029: @example 2030: #define ELIMINABLE_REGS \ 2031: @{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 2032: @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 2033: @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 2034: @end example 2035: 2036: Note that the elimination of the argument pointer with the stack pointer is 2037: specified first since that is the preferred elimination. 2038: 2039: @findex CAN_ELIMINATE 2040: @item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 2041: A C expression that returns non-zero if the compiler is allowed to try 2042: to replace register number @var{from-reg} with register number 2043: @var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 2044: is defined, and will usually be the constant 1, since most of the cases 2045: preventing register elimination are things that the compiler already 2046: knows about. 2047: 2048: @findex INITIAL_ELIMINATION_OFFSET 2049: @item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 2050: This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 2051: specifies the initial difference between the specified pair of 2052: registers. This macro must be defined if @code{ELIMINABLE_REGS} is 2053: defined. 2054: 2055: @findex LONGJMP_RESTORE_FROM_STACK 2056: @item LONGJMP_RESTORE_FROM_STACK 2057: Define this macro if the @code{longjmp} function restores registers from 2058: the stack frames, rather than from those saved specifically by 2059: @code{setjmp}. Certain quantities must not be kept in registers across 2060: a call to @code{setjmp} on such machines. 2061: @end table 2062: 2063: @node Stack Arguments 2064: @subsection Passing Function Arguments on the Stack 2065: @cindex arguments on stack 2066: @cindex stack arguments 2067: 2068: The macros in this section control how arguments are passed 2069: on the stack. See the following section for other macros that 2070: control passing certain arguments in registers. 2071: 2072: @table @code 2073: @findex PROMOTE_PROTOTYPES 2074: @item PROMOTE_PROTOTYPES 2075: Define this macro if an argument declared as @code{char} or 2076: @code{short} in a prototype should actually be passed as an 2077: @code{int}. In addition to avoiding errors in certain cases of 2078: mismatch, it also makes for better code on certain machines. 2079: 2080: @findex PUSH_ROUNDING 2081: @item PUSH_ROUNDING (@var{npushed}) 2082: A C expression that is the number of bytes actually pushed onto the 2083: stack when an instruction attempts to push @var{npushed} bytes. 2084: 2085: If the target machine does not have a push instruction, do not define 2086: this macro. That directs GNU CC to use an alternate strategy: to 2087: allocate the entire argument block and then store the arguments into 2088: it. 2089: 2090: On some machines, the definition 2091: 2092: @example 2093: #define PUSH_ROUNDING(BYTES) (BYTES) 2094: @end example 2095: 2096: @noindent 2097: will suffice. But on other machines, instructions that appear 2098: to push one byte actually push two bytes in an attempt to maintain 2099: alignment. Then the definition should be 2100: 2101: @example 2102: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 2103: @end example 2104: 2105: @findex ACCUMULATE_OUTGOING_ARGS 2106: @findex current_function_outgoing_args_size 2107: @item ACCUMULATE_OUTGOING_ARGS 2108: If defined, the maximum amount of space required for outgoing arguments 2109: will be computed and placed into the variable 2110: @code{current_function_outgoing_args_size}. No space will be pushed 2111: onto the stack for each call; instead, the function prologue should 2112: increase the stack frame size by this amount. 2113: 1.1.1.5 ! root 2114: Defining both @code{PUSH_ROUNDING} and @code{ACCUMULATE_OUTGOING_ARGS} ! 2115: is not proper. 1.1 root 2116: 2117: @findex REG_PARM_STACK_SPACE 1.1.1.3 root 2118: @item REG_PARM_STACK_SPACE (@var{fndecl}) 1.1 root 2119: Define this macro if functions should assume that stack space has been 2120: allocated for arguments even when their values are passed in 2121: registers. 2122: 2123: The value of this macro is the size, in bytes, of the area reserved for 1.1.1.4 root 2124: arguments passed in registers for the function represented by @var{fndecl}. 1.1 root 2125: 1.1.1.5 ! root 2126: This space can be allocated by the caller, or be a part of the ! 2127: machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says ! 2128: which. ! 2129: @c above is overfull. not sure what to do. --mew 5feb93 did ! 2130: @c something, not sure if it looks good. --mew 10feb93 1.1 root 2131: 1.1.1.3 root 2132: @findex MAYBE_REG_PARM_STACK_SPACE 2133: @findex FINAL_REG_PARM_STACK_SPACE 2134: @item MAYBE_REG_PARM_STACK_SPACE 1.1.1.5 ! root 2135: @itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) 1.1.1.3 root 2136: Define these macros in addition to the one above if functions might 2137: allocate stack space for arguments even when their values are passed 2138: in registers. These should be used when the stack space allocated 2139: for arguments in registers is not a simple constant independent of the 2140: function declaration. 2141: 2142: The value of the first macro is the size, in bytes, of the area that 2143: we should initially assume would be reserved for arguments passed in registers. 2144: 2145: The value of the second macro is the actual size, in bytes, of the area 2146: that will be reserved for arguments passed in registers. This takes two 2147: arguments: an integer representing the number of bytes of fixed sized 2148: arguments on the stack, and a tree representing the number of bytes of 2149: variable sized arguments on the stack. 2150: 2151: When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be 2152: called for libcall functions, the current function, or for a function 2153: being called when it is known that such stack space must be allocated. 2154: In each case this value can be easily computed. 2155: 2156: When deciding whether a called function needs such stack space, and how 2157: much space to reserve, GNU CC uses these two macros instead of 2158: @code{REG_PARM_STACK_SPACE}. 2159: 1.1 root 2160: @findex OUTGOING_REG_PARM_STACK_SPACE 2161: @item OUTGOING_REG_PARM_STACK_SPACE 2162: Define this if it is the responsibility of the caller to allocate the area 2163: reserved for arguments passed in registers. 2164: 2165: If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 2166: whether the space for these arguments counts in the value of 2167: @code{current_function_outgoing_args_size}. 2168: 2169: @findex STACK_PARMS_IN_REG_PARM_AREA 2170: @item STACK_PARMS_IN_REG_PARM_AREA 1.1.1.5 ! root 2171: Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the ! 2172: stack parameters don't skip the area specified by it. ! 2173: @c i changed this, makes more sens and it should have taken care of the ! 2174: @c overfull.. not as specific, tho. --mew 5feb93 1.1 root 2175: 2176: Normally, when a parameter is not passed in registers, it is placed on the 2177: stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 2178: suppresses this behavior and causes the parameter to be passed on the 2179: stack in its natural location. 2180: 2181: @findex RETURN_POPS_ARGS 2182: @item RETURN_POPS_ARGS (@var{funtype}, @var{stack-size}) 2183: A C expression that should indicate the number of bytes of its own 2184: arguments that a function pops on returning, or 0 if the 2185: function pops no arguments and the caller must therefore pop them all 2186: after the function returns. 2187: 2188: @var{funtype} is a C variable whose value is a tree node that 2189: describes the function in question. Normally it is a node of type 2190: @code{FUNCTION_TYPE} that describes the data type of the function. 2191: From this it is possible to obtain the data types of the value and 2192: arguments (if known). 2193: 2194: When a call to a library function is being considered, @var{funtype} 2195: will contain an identifier node for the library function. Thus, if 2196: you need to distinguish among various library functions, you can do so 2197: by their names. Note that ``library function'' in this context means 2198: a function used to perform arithmetic, whose name is known specially 2199: in the compiler and was not mentioned in the C code being compiled. 2200: 2201: @var{stack-size} is the number of bytes of arguments passed on the 2202: stack. If a variable number of bytes is passed, it is zero, and 2203: argument popping will always be the responsibility of the calling function. 2204: 2205: On the Vax, all functions always pop their arguments, so the definition 2206: of this macro is @var{stack-size}. On the 68000, using the standard 2207: calling convention, no functions pop their arguments, so the value of 2208: the macro is always 0 in this case. But an alternative calling 2209: convention is available in which functions that take a fixed number of 2210: arguments pop them but other functions (such as @code{printf}) pop 2211: nothing (the caller pops all). When this convention is in use, 2212: @var{funtype} is examined to determine whether a function takes a fixed 2213: number of arguments. 2214: @end table 2215: 2216: @node Register Arguments 2217: @subsection Passing Arguments in Registers 2218: @cindex arguments in registers 2219: @cindex registers arguments 2220: 2221: This section describes the macros which let you control how various 2222: types of arguments are passed in registers or how they are arranged in 2223: the stack. 2224: 2225: @table @code 2226: @findex FUNCTION_ARG 2227: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 2228: A C expression that controls whether a function argument is passed 2229: in a register, and which register. 2230: 2231: The arguments are @var{cum}, which summarizes all the previous 2232: arguments; @var{mode}, the machine mode of the argument; @var{type}, 2233: the data type of the argument as a tree node or 0 if that is not known 2234: (which happens for C support library functions); and @var{named}, 2235: which is 1 for an ordinary argument and 0 for nameless arguments that 2236: correspond to @samp{@dots{}} in the called function's prototype. 2237: 2238: The value of the expression should either be a @code{reg} RTX for the 2239: hard register in which to pass the argument, or zero to pass the 2240: argument on the stack. 2241: 2242: For machines like the Vax and 68000, where normally all arguments are 2243: pushed, zero suffices as a definition. 2244: 2245: @cindex @file{stdarg.h} and register arguments 2246: The usual way to make the ANSI library @file{stdarg.h} work on a machine 2247: where some arguments are usually passed in registers, is to cause 2248: nameless arguments to be passed on the stack instead. This is done 2249: by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 2250: 2251: @cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 2252: @cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 2253: You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} 2254: in the definition of this macro to determine if this argument is of a 2255: type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 2256: is not defined and @code{FUNCTION_ARG} returns non-zero for such an 2257: argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 2258: defined, the argument will be computed in the stack and then loaded into 2259: a register. 2260: 2261: @findex FUNCTION_INCOMING_ARG 2262: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 2263: Define this macro if the target machine has ``register windows'', so 2264: that the register in which a function sees an arguments is not 2265: necessarily the same as the one in which the caller passed the 2266: argument. 2267: 2268: For such machines, @code{FUNCTION_ARG} computes the register in which 2269: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 2270: be defined in a similar fashion to tell the function being called 2271: where the arguments will arrive. 2272: 2273: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 2274: serves both purposes.@refill 2275: 2276: @findex FUNCTION_ARG_PARTIAL_NREGS 2277: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) 2278: A C expression for the number of words, at the beginning of an 2279: argument, must be put in registers. The value must be zero for 2280: arguments that are passed entirely in registers or that are entirely 2281: pushed on the stack. 2282: 2283: On some machines, certain arguments must be passed partially in 2284: registers and partially in memory. On these machines, typically the 2285: first @var{n} words of arguments are passed in registers, and the rest 2286: on the stack. If a multi-word argument (a @code{double} or a 2287: structure) crosses that boundary, its first few words must be passed 2288: in registers and the rest must be pushed. This macro tells the 2289: compiler when this occurs, and how many of the words should go in 2290: registers. 2291: 2292: @code{FUNCTION_ARG} for these arguments should return the first 2293: register to be used by the caller for this argument; likewise 2294: @code{FUNCTION_INCOMING_ARG}, for the called function. 2295: 2296: @findex FUNCTION_ARG_PASS_BY_REFERENCE 2297: @item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 2298: A C expression that indicates when an argument must be passed by reference. 2299: If nonzero for an argument, a copy of that argument is made in memory and a 2300: pointer to the argument is passed instead of the argument itself. 2301: The pointer is passed in whatever way is appropriate for passing a pointer 2302: to that type. 2303: 2304: On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable 2305: definition of this macro might be 1.1.1.5 ! root 2306: @smallexample ! 2307: #define FUNCTION_ARG_PASS_BY_REFERENCE\ ! 2308: (CUM, MODE, TYPE, NAMED) \ 1.1 root 2309: MUST_PASS_IN_STACK (MODE, TYPE) 1.1.1.5 ! root 2310: @end smallexample ! 2311: @c this is *still* too long. --mew 5feb93 ! 2312: ! 2313: @findex FUNCTION_ARG_CALLEE_COPIES ! 2314: @item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) ! 2315: If defined, a C expression that indicates when it is the called function's ! 2316: responsibility to make a copy of arguments passed by invisible reference. ! 2317: Normally, the caller makes a copy and passes the address of the copy to the ! 2318: routine being called. When FUNCTION_ARG_CALLEE_COPIES is defined and is ! 2319: nonzero, the caller does not make a copy. Instead, it passes a pointer to the ! 2320: ``live'' value. The called function must not modify this value. If it can be ! 2321: determined that the value won't be modified, it need not make a copy; ! 2322: otherwise a copy must be made. 1.1 root 2323: 2324: @findex CUMULATIVE_ARGS 2325: @item CUMULATIVE_ARGS 2326: A C type for declaring a variable that is used as the first argument of 2327: @code{FUNCTION_ARG} and other related values. For some target machines, 2328: the type @code{int} suffices and can hold the number of bytes of 2329: argument so far. 2330: 2331: There is no need to record in @code{CUMULATIVE_ARGS} anything about the 2332: arguments that have been passed on the stack. The compiler has other 2333: variables to keep track of that. For target machines on which all 2334: arguments are passed on the stack, there is no need to store anything in 2335: @code{CUMULATIVE_ARGS}; however, the data structure must exist and 2336: should not be empty, so use @code{int}. 2337: 2338: @findex INIT_CUMULATIVE_ARGS 2339: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}) 2340: A C statement (sans semicolon) for initializing the variable @var{cum} 2341: for the state at the beginning of the argument list. The variable has 2342: type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node 2343: for the data type of the function which will receive the args, or 0 2344: if the args are to a compiler support library function. 2345: 2346: When processing a call to a compiler support library function, 2347: @var{libname} identifies which one. It is a @code{symbol_ref} rtx which 2348: contains the name of the function, as a string. @var{libname} is 0 when 2349: an ordinary C function call is being processed. Thus, each time this 2350: macro is called, either @var{libname} or @var{fntype} is nonzero, but 2351: never both of them at once. 2352: 2353: @findex INIT_CUMULATIVE_INCOMING_ARGS 2354: @item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 2355: Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 2356: finding the arguments for the function being compiled. If this macro is 2357: undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 2358: 1.1.1.5 ! root 2359: The value passed for @var{libname} is always 0, since library routines ! 2360: with special calling conventions are never compiled with GNU CC. The ! 2361: argument @var{libname} exists for symmetry with ! 2362: @code{INIT_CUMULATIVE_ARGS}. ! 2363: @c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. ! 2364: @c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 1.1 root 2365: 2366: @findex FUNCTION_ARG_ADVANCE 2367: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 2368: A C statement (sans semicolon) to update the summarizer variable 2369: @var{cum} to advance past an argument in the argument list. The 2370: values @var{mode}, @var{type} and @var{named} describe that argument. 2371: Once this is done, the variable @var{cum} is suitable for analyzing 2372: the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill 2373: 2374: This macro need not do anything if the argument in question was passed 2375: on the stack. The compiler knows how to track the amount of stack space 2376: used for arguments without any special help. 2377: 2378: @findex FUNCTION_ARG_PADDING 2379: @item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 2380: If defined, a C expression which determines whether, and in which direction, 2381: to pad out an argument with extra space. The value should be of type 2382: @code{enum direction}: either @code{upward} to pad above the argument, 2383: @code{downward} to pad below, or @code{none} to inhibit padding. 2384: 1.1.1.5 ! root 2385: The @emph{amount} of padding is always just enough to reach the next ! 2386: multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control ! 2387: it. 1.1 root 2388: 2389: This macro has a default definition which is right for most systems. 2390: For little-endian machines, the default is to pad upward. For 2391: big-endian machines, the default is to pad downward for an argument of 2392: constant size shorter than an @code{int}, and upward otherwise. 2393: 2394: @findex FUNCTION_ARG_BOUNDARY 2395: @item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 2396: If defined, a C expression that gives the alignment boundary, in bits, 2397: of an argument with the specified mode and type. If it is not defined, 2398: @code{PARM_BOUNDARY} is used for all arguments. 2399: 2400: @findex FUNCTION_ARG_REGNO_P 2401: @item FUNCTION_ARG_REGNO_P (@var{regno}) 2402: A C expression that is nonzero if @var{regno} is the number of a hard 2403: register in which function arguments are sometimes passed. This does 2404: @emph{not} include implicit arguments such as the static chain and 2405: the structure-value address. On many machines, no registers can be 2406: used for this purpose since all function arguments are pushed on the 2407: stack. 2408: @end table 2409: 2410: @node Scalar Return 2411: @subsection How Scalar Function Values Are Returned 2412: @cindex return values in registers 2413: @cindex values, returned by functions 2414: @cindex scalars, returned as values 2415: 2416: This section discusses the macros that control returning scalars as 2417: values---values that can fit in registers. 2418: 2419: @table @code 2420: @findex TRADITIONAL_RETURN_FLOAT 2421: @item TRADITIONAL_RETURN_FLOAT 2422: Define this macro if @samp{-traditional} should not cause functions 2423: declared to return @code{float} to convert the value to @code{double}. 2424: 2425: @findex FUNCTION_VALUE 2426: @item FUNCTION_VALUE (@var{valtype}, @var{func}) 2427: A C expression to create an RTX representing the place where a 2428: function returns a value of data type @var{valtype}. @var{valtype} is 2429: a tree node representing a data type. Write @code{TYPE_MODE 2430: (@var{valtype})} to get the machine mode used to represent that type. 2431: On many machines, only the mode is relevant. (Actually, on most 2432: machines, scalar values are returned in the same place regardless of 2433: mode).@refill 2434: 1.1.1.4 root 2435: If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same 2436: promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a 2437: scalar type. 2438: 1.1 root 2439: If the precise function being called is known, @var{func} is a tree 2440: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 2441: pointer. This makes it possible to use a different value-returning 2442: convention for specific functions when all their calls are 2443: known.@refill 2444: 2445: @code{FUNCTION_VALUE} is not used for return vales with aggregate data 2446: types, because these are returned in another way. See 2447: @code{STRUCT_VALUE_REGNUM} and related macros, below. 2448: 2449: @findex FUNCTION_OUTGOING_VALUE 2450: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 2451: Define this macro if the target machine has ``register windows'' 2452: so that the register in which a function returns its value is not 2453: the same as the one in which the caller sees the value. 2454: 1.1.1.5 ! root 2455: For such machines, @code{FUNCTION_VALUE} computes the register in which ! 2456: the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be ! 2457: defined in a similar fashion to tell the function where to put the ! 2458: value.@refill 1.1 root 2459: 2460: If @code{FUNCTION_OUTGOING_VALUE} is not defined, 2461: @code{FUNCTION_VALUE} serves both purposes.@refill 2462: 2463: @code{FUNCTION_OUTGOING_VALUE} is not used for return vales with 2464: aggregate data types, because these are returned in another way. See 2465: @code{STRUCT_VALUE_REGNUM} and related macros, below. 2466: 2467: @findex LIBCALL_VALUE 2468: @item LIBCALL_VALUE (@var{mode}) 2469: A C expression to create an RTX representing the place where a library 2470: function returns a value of mode @var{mode}. If the precise function 2471: being called is known, @var{func} is a tree node 2472: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 2473: pointer. This makes it possible to use a different value-returning 2474: convention for specific functions when all their calls are 2475: known.@refill 2476: 2477: Note that ``library function'' in this context means a compiler 2478: support routine, used to perform arithmetic, whose name is known 2479: specially by the compiler and was not mentioned in the C code being 2480: compiled. 2481: 2482: The definition of @code{LIBRARY_VALUE} need not be concerned aggregate 2483: data types, because none of the library functions returns such types. 2484: 2485: @findex FUNCTION_VALUE_REGNO_P 2486: @item FUNCTION_VALUE_REGNO_P (@var{regno}) 2487: A C expression that is nonzero if @var{regno} is the number of a hard 2488: register in which the values of called function may come back. 2489: 2490: A register whose use for returning values is limited to serving as the 2491: second of a pair (for a value of type @code{double}, say) need not be 2492: recognized by this macro. So for most machines, this definition 2493: suffices: 2494: 2495: @example 2496: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 2497: @end example 2498: 2499: If the machine has register windows, so that the caller and the called 2500: function use different registers for the return value, this macro 2501: should recognize only the caller's register numbers. 1.1.1.5 ! root 2502: ! 2503: @findex APPLY_RESULT_SIZE ! 2504: @item APPLY_RESULT_SIZE ! 2505: Define this macro if @samp{untyped_call} and @samp{untyped_return} ! 2506: need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for ! 2507: saving and restoring an arbitrary return value. 1.1 root 2508: @end table 2509: 2510: @node Aggregate Return 1.1.1.2 root 2511: @subsection How Large Values Are Returned 1.1 root 2512: @cindex aggregates as return values 2513: @cindex large return values 2514: @cindex returning aggregate values 2515: @cindex structure value address 2516: 2517: When a function value's mode is @code{BLKmode} (and in some other 2518: cases), the value is not returned according to @code{FUNCTION_VALUE} 2519: (@pxref{Scalar Return}). Instead, the caller passes the address of a 2520: block of memory in which the value should be stored. This address 2521: is called the @dfn{structure value address}. 2522: 2523: This section describes how to control returning structure values in 2524: memory. 2525: 2526: @table @code 2527: @findex RETURN_IN_MEMORY 2528: @item RETURN_IN_MEMORY (@var{type}) 2529: A C expression which can inhibit the returning of certain function 2530: values in registers, based on the type of value. A nonzero value says 2531: to return the function value in memory, just as large structures are 2532: always returned. Here @var{type} will be a C expression of type 2533: @code{tree}, representing the data type of the value. 2534: 1.1.1.5 ! root 2535: Note that values of mode @code{BLKmode} must be explicitly handled ! 2536: by this macro. Also, the option @samp{-fpcc-struct-return} 1.1 root 2537: takes effect regardless of this macro. On most systems, it is 2538: possible to leave the macro undefined; this causes a default 1.1.1.5 ! root 2539: definition to be used, whose value is the constant 1 for @code{BLKmode} ! 2540: values, and 0 otherwise. ! 2541: ! 2542: Do not use this macro to indicate that structures and unions should always ! 2543: be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} ! 2544: to indicate this. ! 2545: ! 2546: @findex DEFAULT_PCC_STRUCT_RETURN ! 2547: @item DEFAULT_PCC_STRUCT_RETURN ! 2548: Define this macro to be 1 if all structure and union return values must be ! 2549: in memory. Since this results in slower code, this should be defined ! 2550: only if needed for compatibility with other compilers or with an ABI. ! 2551: If you define this macro to be 0, then the conventions used for structure ! 2552: and union return values are decided by the @code{RETURN_IN_MEMORY} macro. ! 2553: ! 2554: If not defined, this defaults to the value 1. 1.1 root 2555: 2556: @findex STRUCT_VALUE_REGNUM 2557: @item STRUCT_VALUE_REGNUM 2558: If the structure value address is passed in a register, then 2559: @code{STRUCT_VALUE_REGNUM} should be the number of that register. 2560: 2561: @findex STRUCT_VALUE 2562: @item STRUCT_VALUE 2563: If the structure value address is not passed in a register, define 2564: @code{STRUCT_VALUE} as an expression returning an RTX for the place 2565: where the address is passed. If it returns 0, the address is passed as 2566: an ``invisible'' first argument. 2567: 2568: @findex STRUCT_VALUE_INCOMING_REGNUM 2569: @item STRUCT_VALUE_INCOMING_REGNUM 2570: On some architectures the place where the structure value address 2571: is found by the called function is not the same place that the 2572: caller put it. This can be due to register windows, or it could 2573: be because the function prologue moves it to a different place. 2574: 2575: If the incoming location of the structure value address is in a 2576: register, define this macro as the register number. 2577: 2578: @findex STRUCT_VALUE_INCOMING 2579: @item STRUCT_VALUE_INCOMING 1.1.1.5 ! root 2580: If the incoming location is not a register, then you should define 1.1 root 2581: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the 2582: called function should find the value. If it should find the value on 2583: the stack, define this to create a @code{mem} which refers to the frame 2584: pointer. A definition of 0 means that the address is passed as an 2585: ``invisible'' first argument. 2586: 2587: @findex PCC_STATIC_STRUCT_RETURN 2588: @item PCC_STATIC_STRUCT_RETURN 2589: Define this macro if the usual system convention on the target machine 2590: for returning structures and unions is for the called function to return 2591: the address of a static variable containing the value. GNU CC does not 2592: normally use this convention, even if it is the usual one, but does use 1.1.1.4 root 2593: it if @samp{-fpcc-struct-return} is specified. 1.1 root 2594: 2595: Do not define this if the usual system convention is for the caller to 2596: pass an address to the subroutine. 2597: @end table 2598: 2599: @node Caller Saves 2600: @subsection Caller-Saves Register Allocation 2601: 2602: If you enable it, GNU CC can save registers around function calls. This 2603: makes it possible to use call-clobbered registers to hold variables that 2604: must live across calls. 2605: 2606: @table @code 2607: @findex DEFAULT_CALLER_SAVES 2608: @item DEFAULT_CALLER_SAVES 2609: Define this macro if function calls on the target machine do not preserve 2610: any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 2611: for all registers. This macro enables @samp{-fcaller-saves} by default. 2612: Eventually that option will be enabled by default on all machines and both 2613: the option and this macro will be eliminated. 2614: 2615: @findex CALLER_SAVE_PROFITABLE 2616: @item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 2617: A C expression to determine whether it is worthwhile to consider placing 2618: a pseudo-register in a call-clobbered hard register and saving and 2619: restoring it around each function call. The expression should be 1 when 2620: this is worth doing, and 0 otherwise. 2621: 2622: If you don't define this macro, a default is used which is good on most 2623: machines: @code{4 * @var{calls} < @var{refs}}. 2624: @end table 2625: 2626: @node Function Entry 2627: @subsection Function Entry and Exit 2628: @cindex function entry and exit 2629: @cindex prologue 2630: @cindex epilogue 2631: 2632: This section describes the macros that output function entry 2633: (@dfn{prologue}) and exit (@dfn{epilogue}) code. 2634: 2635: @table @code 2636: @findex FUNCTION_PROLOGUE 2637: @item FUNCTION_PROLOGUE (@var{file}, @var{size}) 2638: A C compound statement that outputs the assembler code for entry to a 2639: function. The prologue is responsible for setting up the stack frame, 2640: initializing the frame pointer register, saving registers that must be 2641: saved, and allocating @var{size} additional bytes of storage for the 2642: local variables. @var{size} is an integer. @var{file} is a stdio 2643: stream to which the assembler code should be output. 2644: 2645: The label for the beginning of the function need not be output by this 2646: macro. That has already been done when the macro is run. 2647: 2648: @findex regs_ever_live 2649: To determine which registers to save, the macro can refer to the array 2650: @code{regs_ever_live}: element @var{r} is nonzero if hard register 2651: @var{r} is used anywhere within the function. This implies the function 2652: prologue should save register @var{r}, provided it is not one of the 2653: call-used registers. (@code{FUNCTION_EPILOGUE} must likewise use 2654: @code{regs_ever_live}.) 2655: 2656: On machines that have ``register windows'', the function entry code does 2657: not save on the stack the registers that are in the windows, even if 2658: they are supposed to be preserved by function calls; instead it takes 2659: appropriate steps to ``push'' the register stack, if any non-call-used 2660: registers are used in the function. 2661: 2662: @findex frame_pointer_needed 2663: On machines where functions may or may not have frame-pointers, the 2664: function entry code must vary accordingly; it must set up the frame 2665: pointer if one is wanted, and not otherwise. To determine whether a 2666: frame pointer is in wanted, the macro can refer to the variable 2667: @code{frame_pointer_needed}. The variable's value will be 1 at run 2668: time in a function that needs a frame pointer. @xref{Elimination}. 2669: 2670: The function entry code is responsible for allocating any stack space 2671: required for the function. This stack space consists of the regions 2672: listed below. In most cases, these regions are allocated in the 2673: order listed, with the last listed region closest to the top of the 2674: stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 2675: the highest address if it is not defined). You can use a different order 2676: for a machine if doing so is more convenient or required for 2677: compatibility reasons. Except in cases where required by standard 2678: or by a debugger, there is no reason why the stack layout used by GCC 2679: need agree with that used by other compilers for a machine. 2680: 2681: @itemize @bullet 2682: @item 2683: @findex current_function_pretend_args_size 2684: A region of @code{current_function_pretend_args_size} bytes of 2685: uninitialized space just underneath the first argument arriving on the 2686: stack. (This may not be at the very start of the allocated stack region 2687: if the calling sequence has pushed anything else since pushing the stack 2688: arguments. But usually, on such machines, nothing else has been pushed 2689: yet, because the function prologue itself does all the pushing.) This 2690: region is used on machines where an argument may be passed partly in 2691: registers and partly in memory, and, in some cases to support the 2692: features in @file{varargs.h} and @file{stdargs.h}. 2693: 2694: @item 2695: An area of memory used to save certain registers used by the function. 2696: The size of this area, which may also include space for such things as 2697: the return address and pointers to previous stack frames, is 2698: machine-specific and usually depends on which registers have been used 2699: in the function. Machines with register windows often do not require 2700: a save area. 2701: 2702: @item 2703: A region of at least @var{size} bytes, possibly rounded up to an allocation 2704: boundary, to contain the local variables of the function. On some machines, 2705: this region and the save area may occur in the opposite order, with the 2706: save area closer to the top of the stack. 2707: 2708: @item 2709: @cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 1.1.1.5 ! root 2710: Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of ! 2711: @code{current_function_outgoing_args_size} bytes to be used for outgoing ! 2712: argument lists of the function. @xref{Stack Arguments}. 1.1 root 2713: @end itemize 2714: 1.1.1.5 ! root 2715: Normally, it is necessary for the macros @code{FUNCTION_PROLOGUE} and 1.1 root 2716: @code{FUNCTION_EPILOGUE} to treat leaf functions specially. The C 2717: variable @code{leaf_function} is nonzero for such a function. 2718: 2719: @findex EXIT_IGNORE_STACK 2720: @item EXIT_IGNORE_STACK 2721: Define this macro as a C expression that is nonzero if the return 2722: instruction or the function epilogue ignores the value of the stack 2723: pointer; in other words, if it is safe to delete an instruction to 2724: adjust the stack pointer before a return from the function. 2725: 2726: Note that this macro's value is relevant only for functions for which 2727: frame pointers are maintained. It is never safe to delete a final 2728: stack adjustment in a function that has no frame pointer, and the 2729: compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 2730: 2731: @findex FUNCTION_EPILOGUE 2732: @item FUNCTION_EPILOGUE (@var{file}, @var{size}) 2733: A C compound statement that outputs the assembler code for exit from a 2734: function. The epilogue is responsible for restoring the saved 2735: registers and stack pointer to their values when the function was 2736: called, and returning control to the caller. This macro takes the 2737: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the 2738: registers to restore are determined from @code{regs_ever_live} and 2739: @code{CALL_USED_REGISTERS} in the same way. 2740: 2741: On some machines, there is a single instruction that does all the work 2742: of returning from the function. On these machines, give that 2743: instruction the name @samp{return} and do not define the macro 2744: @code{FUNCTION_EPILOGUE} at all. 2745: 2746: Do not define a pattern named @samp{return} if you want the 2747: @code{FUNCTION_EPILOGUE} to be used. If you want the target switches 2748: to control whether return instructions or epilogues are used, define a 2749: @samp{return} pattern with a validity condition that tests the target 2750: switches appropriately. If the @samp{return} pattern's validity 2751: condition is false, epilogues will be used. 2752: 2753: On machines where functions may or may not have frame-pointers, the 1.1.1.4 root 2754: function exit code must vary accordingly. Sometimes the code for these 2755: two cases is completely different. To determine whether a frame pointer 2756: is wanted, the macro can refer to the variable 2757: @code{frame_pointer_needed}. The variable's value will be 1 at run time 2758: in a function that needs a frame pointer. 1.1 root 2759: 1.1.1.5 ! root 2760: Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must ! 2761: treat leaf functions specially. The C variable @code{leaf_function} is ! 2762: nonzero for such a function. @xref{Leaf Functions}. 1.1 root 2763: 2764: On some machines, some functions pop their arguments on exit while 2765: others leave that for the caller to do. For example, the 68020 when 2766: given @samp{-mrtd} pops arguments in functions that take a fixed 2767: number of arguments. 2768: 2769: @findex current_function_pops_args 2770: Your definition of the macro @code{RETURN_POPS_ARGS} decides which 2771: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to 1.1.1.5 ! root 2772: know what was decided. The variable that is called ! 2773: @code{current_function_pops_args} is the number of bytes of its ! 2774: arguments that a function should pop. @xref{Scalar Return}. ! 2775: @c what is the "its arguments" in the above sentence referring to, pray ! 2776: @c tell? --mew 5feb93 1.1 root 2777: 2778: @findex DELAY_SLOTS_FOR_EPILOGUE 2779: @item DELAY_SLOTS_FOR_EPILOGUE 2780: Define this macro if the function epilogue contains delay slots to which 2781: instructions from the rest of the function can be ``moved''. The 2782: definition should be a C expression whose value is an integer 2783: representing the number of delay slots there. 2784: 2785: @findex ELIGIBLE_FOR_EPILOGUE_DELAY 2786: @item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 2787: A C expression that returns 1 if @var{insn} can be placed in delay 2788: slot number @var{n} of the epilogue. 2789: 2790: The argument @var{n} is an integer which identifies the delay slot now 2791: being considered (since different slots may have different rules of 2792: eligibility). It is never negative and is always less than the number 2793: of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 2794: If you reject a particular insn for a given delay slot, in principle, it 2795: may be reconsidered for a subsequent delay slot. Also, other insns may 2796: (at least in principle) be considered for the so far unfilled delay 2797: slot. 2798: 2799: @findex current_function_epilogue_delay_list 2800: @findex final_scan_insn 2801: The insns accepted to fill the epilogue delay slots are put in an RTL 2802: list made with @code{insn_list} objects, stored in the variable 2803: @code{current_function_epilogue_delay_list}. The insn for the first 2804: delay slot comes first in the list. Your definition of the macro 2805: @code{FUNCTION_EPILOGUE} should fill the delay slots by outputting the 2806: insns in this list, usually by calling @code{final_scan_insn}. 2807: 2808: You need not define this macro if you did not define 2809: @code{DELAY_SLOTS_FOR_EPILOGUE}. 2810: @end table 2811: 2812: @node Profiling 2813: @subsection Generating Code for Profiling 2814: @cindex profiling, code generation 2815: 1.1.1.5 ! root 2816: These macros will help you generate code for profiling. ! 2817: 1.1 root 2818: @table @code 2819: @findex FUNCTION_PROFILER 2820: @item FUNCTION_PROFILER (@var{file}, @var{labelno}) 2821: A C statement or compound statement to output to @var{file} some 2822: assembler code to call the profiling subroutine @code{mcount}. 2823: Before calling, the assembler code must load the address of a 2824: counter variable into a register where @code{mcount} expects to 2825: find the address. The name of this variable is @samp{LP} followed 2826: by the number @var{labelno}, so you would generate the name using 2827: @samp{LP%d} in a @code{fprintf}. 2828: 2829: @findex mcount 2830: The details of how the address should be passed to @code{mcount} are 2831: determined by your operating system environment, not by GNU CC. To 2832: figure them out, compile a small program for profiling using the 2833: system's installed C compiler and look at the assembler code that 2834: results. 2835: 2836: @findex PROFILE_BEFORE_PROLOGUE 2837: @item PROFILE_BEFORE_PROLOGUE 2838: Define this macro if the code for function profiling should come before 2839: the function prologue. Normally, the profiling code comes after. 2840: 2841: @findex FUNCTION_BLOCK_PROFILER 2842: @findex __bb_init_func 2843: @item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno}) 2844: A C statement or compound statement to output to @var{file} some 2845: assembler code to initialize basic-block profiling for the current 2846: object module. This code should call the subroutine 2847: @code{__bb_init_func} once per object module, passing it as its sole 2848: argument the address of a block allocated in the object module. 2849: 2850: The name of the block is a local symbol made with this statement: 2851: 2852: @example 2853: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0); 2854: @end example 2855: 2856: Of course, since you are writing the definition of 2857: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you 2858: can take a short cut in the definition of this macro and use the name 2859: that you know will result. 2860: 2861: The first word of this block is a flag which will be nonzero if the 2862: object module has already been initialized. So test this word first, 2863: and do not call @code{__bb_init_func} if the flag is nonzero. 2864: 2865: @findex BLOCK_PROFILER 2866: @item BLOCK_PROFILER (@var{file}, @var{blockno}) 2867: A C statement or compound statement to increment the count associated 2868: with the basic block number @var{blockno}. Basic blocks are numbered 2869: separately from zero within each compilation. The count associated 2870: with block number @var{blockno} is at index @var{blockno} in a vector 2871: of words; the name of this array is a local symbol made with this 2872: statement: 2873: 2874: @example 2875: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2); 2876: @end example 2877: 1.1.1.5 ! root 2878: @c This paragraph is the same as one a few paragraphs up. ! 2879: @c That is not an error. 1.1 root 2880: Of course, since you are writing the definition of 2881: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you 2882: can take a short cut in the definition of this macro and use the name 2883: that you know will result. 2884: @end table 2885: 1.1.1.2 root 2886: @node Varargs 1.1 root 2887: @section Implementing the Varargs Macros 2888: @cindex varargs implementation 2889: 2890: GNU CC comes with an implementation of @file{varargs.h} and 2891: @file{stdarg.h} that work without change on machines that pass arguments 2892: on the stack. Other machines require their own implementations of 2893: varargs, and the two machine independent header files must have 2894: conditionals to include it. 2895: 2896: ANSI @file{stdarg.h} differs from traditional @file{varargs.h} mainly in 2897: the calling convention for @code{va_start}. The traditional 2898: implementation takes just one argument, which is the variable in which 1.1.1.3 root 2899: to store the argument pointer. The ANSI implementation of 2900: @code{va_start} takes an additional second argument. The user is 2901: supposed to write the last named argument of the function here. 2902: 2903: However, @code{va_start} should not use this argument. The way to find 1.1 root 2904: the end of the named arguments is with the built-in functions described 2905: below. 2906: 2907: @table @code 2908: @findex __builtin_saveregs 2909: @item __builtin_saveregs () 2910: Use this built-in function to save the argument registers in memory so 2911: that the varargs mechanism can access them. Both ANSI and traditional 2912: versions of @code{va_start} must use @code{__builtin_saveregs}, unless 2913: you use @code{SETUP_INCOMING_VARARGS} (see below) instead. 2914: 2915: On some machines, @code{__builtin_saveregs} is open-coded under the 2916: control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, 2917: it calls a routine written in assembler language, found in 2918: @file{libgcc2.c}. 2919: 1.1.1.5 ! root 2920: Code generated for the call to @code{__builtin_saveregs} appears at the ! 2921: beginning of the function, as opposed to where the call to ! 2922: @code{__builtin_saveregs} is written, regardless of what the code is. ! 2923: This is because the registers must be saved before the function starts ! 2924: to use them for its own purposes. ! 2925: @c i rewrote the first sentence above to fix an overfull hbox. --mew ! 2926: @c 10feb93 1.1 root 2927: 2928: @findex __builtin_args_info 2929: @item __builtin_args_info (@var{category}) 2930: Use this built-in function to find the first anonymous arguments in 2931: registers. 2932: 2933: In general, a machine may have several categories of registers used for 2934: arguments, each for a particular category of data types. (For example, 2935: on some machines, floating-point registers are used for floating-point 2936: arguments while other arguments are passed in the general registers.) 2937: To make non-varargs functions use the proper calling convention, you 2938: have defined the @code{CUMULATIVE_ARGS} data type to record how many 2939: registers in each category have been used so far 2940: 2941: @code{__builtin_args_info} accesses the same data structure of type 2942: @code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 2943: with it, with @var{category} specifying which word to access. Thus, the 2944: value indicates the first unused register in a given category. 2945: 2946: Normally, you would use @code{__builtin_args_info} in the implementation 2947: of @code{va_start}, accessing each category just once and storing the 2948: value in the @code{va_list} object. This is because @code{va_list} will 2949: have to update the values, and there is no way to alter the 2950: values accessed by @code{__builtin_args_info}. 2951: 2952: @findex __builtin_next_arg 2953: @item __builtin_next_arg () 2954: This is the equivalent of @code{__builtin_args_info}, for stack 2955: arguments. It returns the address of the first anonymous stack 2956: argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 2957: returns the address of the location above the first anonymous stack 2958: argument. Use it in @code{va_start} to initialize the pointer for 2959: fetching arguments from the stack. 2960: 2961: @findex __builtin_classify_type 2962: @item __builtin_classify_type (@var{object}) 2963: Since each machine has its own conventions for which data types are 2964: passed in which kind of register, your implementation of @code{va_arg} 2965: has to embody these conventions. The easiest way to categorize the 2966: specified data type is to use @code{__builtin_classify_type} together 2967: with @code{sizeof} and @code{__alignof__}. 2968: 2969: @code{__builtin_classify_type} ignores the value of @var{object}, 2970: considering only its data type. It returns an integer describing what 2971: kind of type that is---integer, floating, pointer, structure, and so on. 2972: 2973: The file @file{typeclass.h} defines an enumeration that you can use to 2974: interpret the values of @code{__builtin_classify_type}. 2975: @end table 2976: 2977: These machine description macros help implement varargs: 2978: 2979: @table @code 2980: @findex EXPAND_BUILTIN_SAVEREGS 2981: @item EXPAND_BUILTIN_SAVEREGS (@var{args}) 2982: If defined, is a C expression that produces the machine-specific code 2983: for a call to @code{__builtin_saveregs}. This code will be moved to the 2984: very beginning of the function, before any parameter access are made. 2985: The return value of this function should be an RTX that contains the 2986: value to use as the return of @code{__builtin_saveregs}. 2987: 2988: The argument @var{args} is a @code{tree_list} containing the arguments 2989: that were passed to @code{__builtin_saveregs}. 2990: 2991: If this macro is not defined, the compiler will output an ordinary 2992: call to the library function @samp{__builtin_saveregs}. 2993: 1.1.1.5 ! root 2994: @c !!! a bug in texinfo; how to make the entry on the @item line allow ! 2995: @c more than one line of text... help... --mew 10feb93 1.1 root 2996: @findex SETUP_INCOMING_VARARGS 1.1.1.5 ! root 2997: @item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, ! 2998: @var{pretend_args_size}, @var{second_time}) 1.1 root 2999: This macro offers an alternative to using @code{__builtin_saveregs} and 3000: defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the 3001: anonymous register arguments into the stack so that all the arguments 3002: appear to have been passed consecutively on the stack. Once this is 3003: done, you can use the standard implementation of varargs that works for 3004: machines that pass all their arguments on the stack. 3005: 3006: The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data 3007: structure, containing the values that obtain after processing of the 3008: named arguments. The arguments @var{mode} and @var{type} describe the 3009: last named argument---its machine mode and its data type as a tree node. 3010: 3011: The macro implementation should do two things: first, push onto the 3012: stack all the argument registers @emph{not} used for the named 3013: arguments, and second, store the size of the data thus pushed into the 3014: @code{int}-valued variable whose name is supplied as the argument 3015: @var{pretend_args_size}. The value that you store here will serve as 3016: additional offset for setting up the stack frame. 3017: 3018: Because you must generate code to push the anonymous arguments at 3019: compile time without knowing their data types, 3020: @code{SETUP_INCOMING_VARARGS} is only useful on machines that have just 3021: a single category of argument register and use it uniformly for all data 3022: types. 3023: 3024: If the argument @var{second_time} is nonzero, it means that the 3025: arguments of the function are being analyzed for the second time. This 3026: happens for an inline function, which is not actually compiled until the 3027: end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should 3028: not generate any instructions in this case. 3029: @end table 3030: 1.1.1.2 root 3031: @node Trampolines 1.1 root 3032: @section Trampolines for Nested Functions 3033: @cindex trampolines for nested functions 3034: @cindex nested functions, trampolines for 3035: 3036: A @dfn{trampoline} is a small piece of code that is created at run time 3037: when the address of a nested function is taken. It normally resides on 3038: the stack, in the stack frame of the containing function. These macros 3039: tell GNU CC how to generate code to allocate and initialize a 3040: trampoline. 3041: 3042: The instructions in the trampoline must do two things: load a constant 3043: address into the static chain register, and jump to the real address of 3044: the nested function. On CISC machines such as the m68k, this requires 3045: two instructions, a move immediate and a jump. Then the two addresses 3046: exist in the trampoline as word-long immediate operands. On RISC 3047: machines, it is often necessary to load each address into a register in 3048: two parts. Then pieces of each address form separate immediate 3049: operands. 3050: 3051: The code generated to initialize the trampoline must store the variable 3052: parts---the static chain value and the function address---into the 3053: immediate operands of the instructions. On a CISC machine, this is 3054: simply a matter of copying each address to a memory reference at the 3055: proper offset from the start of the trampoline. On a RISC machine, it 3056: may be necessary to take out pieces of the address and store them 3057: separately. 3058: 3059: @table @code 3060: @findex TRAMPOLINE_TEMPLATE 3061: @item TRAMPOLINE_TEMPLATE (@var{file}) 3062: A C statement to output, on the stream @var{file}, assembler code for a 3063: block of data that contains the constant parts of a trampoline. This 3064: code should not include a label---the label is taken care of 3065: automatically. 3066: 1.1.1.4 root 3067: @findex TRAMPOLINE_SECTION 3068: @item TRAMPOLINE_SECTION 3069: The name of a subroutine to switch to the section in which the 3070: trampoline template is to be placed (@pxref{Sections}). The default is 3071: a value of @samp{readonly_data_section}, which places the trampoline in 3072: the section containing read-only data. 3073: 1.1 root 3074: @findex TRAMPOLINE_SIZE 3075: @item TRAMPOLINE_SIZE 3076: A C expression for the size in bytes of the trampoline, as an integer. 3077: 3078: @findex TRAMPOLINE_ALIGNMENT 3079: @item TRAMPOLINE_ALIGNMENT 3080: Alignment required for trampolines, in bits. 3081: 3082: If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 3083: is used for aligning trampolines. 3084: 3085: @findex INITIALIZE_TRAMPOLINE 3086: @item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 3087: A C statement to initialize the variable parts of a trampoline. 3088: @var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 3089: an RTX for the address of the nested function; @var{static_chain} is an 3090: RTX for the static chain value that should be passed to the function 3091: when it is called. 3092: 3093: @findex ALLOCATE_TRAMPOLINE 3094: @item ALLOCATE_TRAMPOLINE (@var{fp}) 3095: A C expression to allocate run-time space for a trampoline. The 3096: expression value should be an RTX representing a memory reference to the 3097: space for the trampoline. 3098: 3099: @cindex @code{FUNCTION_EPILOGUE} and trampolines 3100: @cindex @code{FUNCTION_PROLOGUE} and trampolines 3101: If this macro is not defined, by default the trampoline is allocated as 3102: a stack slot. This default is right for most machines. The exceptions 3103: are machines where it is impossible to execute instructions in the stack 3104: area. On such machines, you may have to implement a separate stack, 3105: using this macro in conjunction with @code{FUNCTION_PROLOGUE} and 3106: @code{FUNCTION_EPILOGUE}. 3107: 3108: @var{fp} points to a data structure, a @code{struct function}, which 3109: describes the compilation status of the immediate containing function of 3110: the function which the trampoline is for. Normally (when 3111: @code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the 3112: trampoline is in the stack frame of this containing function. Other 3113: allocation strategies probably must do something analogous with this 3114: information. 3115: @end table 3116: 3117: Implementing trampolines is difficult on many machines because they have 3118: separate instruction and data caches. Writing into a stack location 3119: fails to clear the memory in the instruction cache, so when the program 3120: jumps to that location, it executes the old contents. 3121: 3122: Here are two possible solutions. One is to clear the relevant parts of 3123: the instruction cache whenever a trampoline is set up. The other is to 3124: make all trampolines identical, by having them jump to a standard 3125: subroutine. The former technique makes trampoline execution faster; the 3126: latter makes initialization faster. 3127: 3128: To clear the instruction cache when a trampoline is initialized, define 3129: the following macros which describe the shape of the cache. 3130: 3131: @table @code 3132: @findex INSN_CACHE_SIZE 3133: @item INSN_CACHE_SIZE 3134: The total size in bytes of the cache. 3135: 3136: @findex INSN_CACHE_LINE_WIDTH 3137: @item INSN_CACHE_LINE_WIDTH 3138: The length in bytes of each cache line. The cache is divided into cache 3139: lines which are disjoint slots, each holding a contiguous chunk of data 3140: fetched from memory. Each time data is brought into the cache, an 3141: entire line is read at once. The data loaded into a cache line is 3142: always aligned on a boundary equal to the line size. 3143: 3144: @findex INSN_CACHE_DEPTH 3145: @item INSN_CACHE_DEPTH 3146: The number of alternative cache lines that can hold any particular memory 3147: location. 3148: @end table 3149: 3150: To use a standard subroutine, define the following macro. In addition, 3151: you must make sure that the instructions in a trampoline fill an entire 3152: cache line with identical instructions, or else ensure that the 3153: beginning of the trampoline code is always aligned at the same point in 3154: its cache line. Look in @file{m68k.h} as a guide. 3155: 3156: @table @code 3157: @findex TRANSFER_FROM_TRAMPOLINE 3158: @item TRANSFER_FROM_TRAMPOLINE 3159: Define this macro if trampolines need a special subroutine to do their 3160: work. The macro should expand to a series of @code{asm} statements 3161: which will be compiled with GNU CC. They go in a library function named 3162: @code{__transfer_from_trampoline}. 3163: 3164: If you need to avoid executing the ordinary prologue code of a compiled 3165: C function when you jump to the subroutine, you can do so by placing a 3166: special label of your own in the assembler code. Use one @code{asm} 3167: statement to generate an assembler label, and another to make the label 3168: global. Then trampolines can use that label to jump directly to your 3169: special assembler code. 3170: @end table 3171: 1.1.1.2 root 3172: @node Library Calls 1.1 root 3173: @section Implicit Calls to Library Routines 3174: @cindex library subroutine names 3175: @cindex @file{libgcc.a} 3176: 3177: @table @code 3178: @findex MULSI3_LIBCALL 3179: @item MULSI3_LIBCALL 3180: A C string constant giving the name of the function to call for 3181: multiplication of one signed full-word by another. If you do not 3182: define this macro, the default name is used, which is @code{__mulsi3}, 3183: a function defined in @file{libgcc.a}. 3184: 3185: @findex DIVSI3_LIBCALL 3186: @item DIVSI3_LIBCALL 3187: A C string constant giving the name of the function to call for 3188: division of one signed full-word by another. If you do not define 3189: this macro, the default name is used, which is @code{__divsi3}, a 3190: function defined in @file{libgcc.a}. 3191: 3192: @findex UDIVSI3_LIBCALL 3193: @item UDIVSI3_LIBCALL 3194: A C string constant giving the name of the function to call for 3195: division of one unsigned full-word by another. If you do not define 3196: this macro, the default name is used, which is @code{__udivsi3}, a 3197: function defined in @file{libgcc.a}. 3198: 3199: @findex MODSI3_LIBCALL 3200: @item MODSI3_LIBCALL 3201: A C string constant giving the name of the function to call for the 3202: remainder in division of one signed full-word by another. If you do 3203: not define this macro, the default name is used, which is 3204: @code{__modsi3}, a function defined in @file{libgcc.a}. 3205: 3206: @findex UMODSI3_LIBCALL 3207: @item UMODSI3_LIBCALL 3208: A C string constant giving the name of the function to call for the 3209: remainder in division of one unsigned full-word by another. If you do 3210: not define this macro, the default name is used, which is 3211: @code{__umodsi3}, a function defined in @file{libgcc.a}. 3212: 3213: @findex MULDI3_LIBCALL 3214: @item MULDI3_LIBCALL 3215: A C string constant giving the name of the function to call for 3216: multiplication of one signed double-word by another. If you do not 3217: define this macro, the default name is used, which is @code{__muldi3}, 3218: a function defined in @file{libgcc.a}. 3219: 3220: @findex DIVDI3_LIBCALL 3221: @item DIVDI3_LIBCALL 3222: A C string constant giving the name of the function to call for 3223: division of one signed double-word by another. If you do not define 3224: this macro, the default name is used, which is @code{__divdi3}, a 3225: function defined in @file{libgcc.a}. 3226: 3227: @findex UDIVDI3_LIBCALL 3228: @item UDIVDI3_LIBCALL 3229: A C string constant giving the name of the function to call for 3230: division of one unsigned full-word by another. If you do not define 3231: this macro, the default name is used, which is @code{__udivdi3}, a 3232: function defined in @file{libgcc.a}. 3233: 3234: @findex MODDI3_LIBCALL 3235: @item MODDI3_LIBCALL 3236: A C string constant giving the name of the function to call for the 3237: remainder in division of one signed double-word by another. If you do 3238: not define this macro, the default name is used, which is 3239: @code{__moddi3}, a function defined in @file{libgcc.a}. 3240: 3241: @findex UMODDI3_LIBCALL 3242: @item UMODDI3_LIBCALL 3243: A C string constant giving the name of the function to call for the 3244: remainder in division of one unsigned full-word by another. If you do 3245: not define this macro, the default name is used, which is 3246: @code{__umoddi3}, a function defined in @file{libgcc.a}. 3247: 1.1.1.4 root 3248: @findex TARGET_EDOM 3249: @cindex @code{EDOM}, implicit usage 3250: @item TARGET_EDOM 3251: The value of @code{EDOM} on the target machine, as a C integer constant 3252: expression. If you don't define this macro, GNU CC does not attempt to 3253: deposit the value of @code{EDOM} into @code{errno} directly. Look in 3254: @file{/usr/include/errno.h} to find the value of @code{EDOM} on your 3255: system. 3256: 3257: If you do not define @code{TARGET_EDOM}, then compiled code reports 3258: domain errors by calling the library function and letting it report the 3259: error. If mathematical functions on your system use @code{matherr} when 3260: there is an error, then you should leave @code{TARGET_EDOM} undefined so 3261: that @code{matherr} is used normally. 3262: 3263: @findex GEN_ERRNO_RTX 3264: @cindex @code{errno}, implicit usage 3265: @item GEN_ERRNO_RTX 3266: Define this macro as a C expression to create an rtl expression that 3267: refers to the global ``variable'' @code{errno}. (On certain systems, 3268: @code{errno} may not actually be a variable.) If you don't define this 3269: macro, a reasonable default is used. 3270: 1.1 root 3271: @findex TARGET_MEM_FUNCTIONS 3272: @cindex @code{bcopy}, implicit usage 3273: @cindex @code{memcpy}, implicit usage 3274: @cindex @code{bzero}, implicit usage 3275: @cindex @code{memset}, implicit usage 3276: @item TARGET_MEM_FUNCTIONS 3277: Define this macro if GNU CC should generate calls to the System V 3278: (and ANSI C) library functions @code{memcpy} and @code{memset} 3279: rather than the BSD functions @code{bcopy} and @code{bzero}. 3280: 3281: @findex LIBGCC_NEEDS_DOUBLE 3282: @item LIBGCC_NEEDS_DOUBLE 3283: Define this macro if only @code{float} arguments cannot be passed to 3284: library routines (so they must be converted to @code{double}). This 3285: macro affects both how library calls are generated and how the library 3286: routines in @file{libgcc1.c} accept their arguments. It is useful on 3287: machines where floating and fixed point arguments are passed 3288: differently, such as the i860. 3289: 3290: @findex FLOAT_ARG_TYPE 3291: @item FLOAT_ARG_TYPE 3292: Define this macro to override the type used by the library routines to 3293: pick up arguments of type @code{float}. (By default, they use a union 3294: of @code{float} and @code{int}.) 3295: 3296: The obvious choice would be @code{float}---but that won't work with 3297: traditional C compilers that expect all arguments declared as @code{float} 3298: to arrive as @code{double}. To avoid this conversion, the library routines 3299: ask for the value as some other type and then treat it as a @code{float}. 3300: 3301: On some systems, no other type will work for this. For these systems, 3302: you must use @code{LIBGCC_NEEDS_DOUBLE} instead, to force conversion of 3303: the values @code{double} before they are passed. 3304: 3305: @findex FLOATIFY 3306: @item FLOATIFY (@var{passed-value}) 3307: Define this macro to override the way library routines redesignate a 3308: @code{float} argument as a @code{float} instead of the type it was 3309: passed as. The default is an expression which takes the @code{float} 3310: field of the union. 3311: 3312: @findex FLOAT_VALUE_TYPE 3313: @item FLOAT_VALUE_TYPE 3314: Define this macro to override the type used by the library routines to 3315: return values that ought to have type @code{float}. (By default, they 3316: use @code{int}.) 3317: 3318: The obvious choice would be @code{float}---but that won't work with 3319: traditional C compilers gratuitously convert values declared as 3320: @code{float} into @code{double}. 3321: 3322: @findex INTIFY 3323: @item INTIFY (@var{float-value}) 3324: Define this macro to override the way the value of a 3325: @code{float}-returning library routine should be packaged in order to 3326: return it. These functions are actually declared to return type 3327: @code{FLOAT_VALUE_TYPE} (normally @code{int}). 3328: 3329: These values can't be returned as type @code{float} because traditional 3330: C compilers would gratuitously convert the value to a @code{double}. 3331: 3332: A local variable named @code{intify} is always available when the macro 3333: @code{INTIFY} is used. It is a union of a @code{float} field named 3334: @code{f} and a field named @code{i} whose type is 3335: @code{FLOAT_VALUE_TYPE} or @code{int}. 3336: 3337: If you don't define this macro, the default definition works by copying 3338: the value through that union. 3339: 1.1.1.3 root 3340: @findex nongcc_SI_type 3341: @item nongcc_SI_type 1.1 root 3342: Define this macro as the name of the data type corresponding to 3343: @code{SImode} in the system's own C compiler. 3344: 1.1.1.5 ! root 3345: You need not define this macro if that type is @code{long int}, as it usually ! 3346: is. ! 3347: ! 3348: @findex nongcc_word_type ! 3349: @item nongcc_word_type ! 3350: Define this macro as the name of the data type corresponding to the ! 3351: word_mode in the system's own C compiler. ! 3352: ! 3353: You need not define this macro if that type is @code{long int}, as it usually 1.1 root 3354: is. 3355: 3356: @findex perform_@dots{} 3357: @item perform_@dots{} 3358: Define these macros to supply explicit C statements to carry out various 3359: arithmetic operations on types @code{float} and @code{double} in the 3360: library routines in @file{libgcc1.c}. See that file for a full list 3361: of these macros and their arguments. 3362: 3363: On most machines, you don't need to define any of these macros, because 3364: the C compiler that comes with the system takes care of doing them. 3365: 3366: @findex NEXT_OBJC_RUNTIME 3367: @item NEXT_OBJC_RUNTIME 3368: Define this macro to generate code for Objective C message sending using 3369: the calling convention of the NeXT system. This calling convention 3370: involves passing the object, the selector and the method arguments all 3371: at once to the method-lookup library function. 3372: 3373: The default calling convention passes just the object and the selector 3374: to the lookup function, which returns a pointer to the method. 3375: @end table 3376: 1.1.1.2 root 3377: @node Addressing Modes 1.1 root 3378: @section Addressing Modes 3379: @cindex addressing modes 3380: 3381: @table @code 3382: @findex HAVE_POST_INCREMENT 3383: @item HAVE_POST_INCREMENT 3384: Define this macro if the machine supports post-increment addressing. 3385: 3386: @findex HAVE_PRE_INCREMENT 3387: @findex HAVE_POST_DECREMENT 3388: @findex HAVE_PRE_DECREMENT 3389: @item HAVE_PRE_INCREMENT 3390: @itemx HAVE_POST_DECREMENT 3391: @itemx HAVE_PRE_DECREMENT 3392: Similar for other kinds of addressing. 3393: 3394: @findex CONSTANT_ADDRESS_P 3395: @item CONSTANT_ADDRESS_P (@var{x}) 3396: A C expression that is 1 if the RTX @var{x} is a constant which 3397: is a valid address. On most machines, this can be defined as 3398: @code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 3399: in which constant addresses are supported. 3400: 3401: @findex CONSTANT_P 3402: @code{CONSTANT_P} accepts integer-values expressions whose values are 3403: not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and 3404: @code{high} expressions and @code{const} arithmetic expressions, in 3405: addition to @code{const_int} and @code{const_double} expressions. 3406: 3407: @findex MAX_REGS_PER_ADDRESS 3408: @item MAX_REGS_PER_ADDRESS 3409: A number, the maximum number of registers that can appear in a valid 3410: memory address. Note that it is up to you to specify a value equal to 3411: the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 3412: accept. 3413: 3414: @findex GO_IF_LEGITIMATE_ADDRESS 3415: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 3416: A C compound statement with a conditional @code{goto @var{label};} 3417: executed if @var{x} (an RTX) is a legitimate memory address on the 3418: target machine for a memory operand of mode @var{mode}. 3419: 3420: It usually pays to define several simpler macros to serve as 3421: subroutines for this one. Otherwise it may be too complicated to 3422: understand. 3423: 3424: This macro must exist in two variants: a strict variant and a 3425: non-strict one. The strict variant is used in the reload pass. It 3426: must be defined so that any pseudo-register that has not been 3427: allocated a hard register is considered a memory reference. In 3428: contexts where some kind of register is required, a pseudo-register 3429: with no hard register must be rejected. 3430: 3431: The non-strict variant is used in other passes. It must be defined to 3432: accept all pseudo-registers in every context where some kind of 3433: register is required. 3434: 3435: @findex REG_OK_STRICT 3436: Compiler source files that want to use the strict variant of this 3437: macro define the macro @code{REG_OK_STRICT}. You should use an 3438: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant 3439: in that case and the non-strict variant otherwise. 3440: 1.1.1.5 ! root 3441: Subroutines to check for acceptable registers for various purposes (one ! 3442: for base registers, one for index registers, and so on) are typically ! 3443: among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. ! 3444: Then only these subroutine macros need have two variants; the higher ! 3445: levels of macros may be the same whether strict or not.@refill 1.1 root 3446: 3447: Normally, constant addresses which are the sum of a @code{symbol_ref} 3448: and an integer are stored inside a @code{const} RTX to mark them as 3449: constant. Therefore, there is no need to recognize such sums 3450: specifically as legitimate addresses. Normally you would simply 3451: recognize any @code{const} as legitimate. 3452: 3453: Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 3454: sums that are not marked with @code{const}. It assumes that a naked 3455: @code{plus} indicates indexing. If so, then you @emph{must} reject such 3456: naked constant sums as illegitimate addresses, so that none of them will 3457: be given to @code{PRINT_OPERAND_ADDRESS}. 3458: 3459: @cindex @code{ENCODE_SECTION_INFO} and address validation 3460: On some machines, whether a symbolic address is legitimate depends on 3461: the section that the address refers to. On these machines, define the 3462: macro @code{ENCODE_SECTION_INFO} to store the information into the 3463: @code{symbol_ref}, and then check for it here. When you see a 3464: @code{const}, you will have to look inside it to find the 3465: @code{symbol_ref} in order to determine the section. @xref{Assembler 3466: Format}. 3467: 3468: @findex saveable_obstack 3469: The best way to modify the name string is by adding text to the 3470: beginning, with suitable punctuation to prevent any ambiguity. Allocate 3471: the new name in @code{saveable_obstack}. You will have to modify 3472: @code{ASM_OUTPUT_LABELREF} to remove and decode the added text and 1.1.1.4 root 3473: output the name accordingly, and define @code{STRIP_NAME_ENCODING} to 3474: access the original name string. 1.1 root 3475: 3476: You can check the information stored here into the @code{symbol_ref} in 1.1.1.5 ! root 3477: the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and 1.1 root 3478: @code{PRINT_OPERAND_ADDRESS}. 3479: 3480: @findex REG_OK_FOR_BASE_P 3481: @item REG_OK_FOR_BASE_P (@var{x}) 3482: A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 3483: RTX) is valid for use as a base register. For hard registers, it 3484: should always accept those which the hardware permits and reject the 3485: others. Whether the macro accepts or rejects pseudo registers must be 3486: controlled by @code{REG_OK_STRICT} as described above. This usually 3487: requires two variant definitions, of which @code{REG_OK_STRICT} 3488: controls the one actually used. 3489: 3490: @findex REG_OK_FOR_INDEX_P 3491: @item REG_OK_FOR_INDEX_P (@var{x}) 3492: A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 3493: RTX) is valid for use as an index register. 3494: 3495: The difference between an index register and a base register is that 3496: the index register may be scaled. If an address involves the sum of 3497: two registers, neither one of them scaled, then either one may be 3498: labeled the ``base'' and the other the ``index''; but whichever 3499: labeling is used must fit the machine's constraints of which registers 3500: may serve in each capacity. The compiler will try both labelings, 3501: looking for one that is valid, and will reload one or both registers 3502: only if neither labeling works. 3503: 3504: @findex LEGITIMIZE_ADDRESS 3505: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 3506: A C compound statement that attempts to replace @var{x} with a valid 3507: memory address for an operand of mode @var{mode}. @var{win} will be a 3508: C statement label elsewhere in the code; the macro definition may use 3509: 3510: @example 3511: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 3512: @end example 3513: 3514: @noindent 3515: to avoid further processing if the address has become legitimate. 3516: 3517: @findex break_out_memory_refs 3518: @var{x} will always be the result of a call to @code{break_out_memory_refs}, 3519: and @var{oldx} will be the operand that was given to that function to produce 3520: @var{x}. 3521: 3522: The code generated by this macro should not alter the substructure of 3523: @var{x}. If it transforms @var{x} into a more legitimate form, it 3524: should assign @var{x} (which will always be a C variable) a new value. 3525: 3526: It is not necessary for this macro to come up with a legitimate 3527: address. The compiler has standard ways of doing so in all cases. In 3528: fact, it is safe for this macro to do nothing. But often a 3529: machine-dependent strategy can generate better code. 3530: 3531: @findex GO_IF_MODE_DEPENDENT_ADDRESS 3532: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 3533: A C statement or compound statement with a conditional @code{goto 3534: @var{label};} executed if memory address @var{x} (an RTX) can have 3535: different meanings depending on the machine mode of the memory 1.1.1.4 root 3536: reference it is used for or if the address is valid for some modes 3537: but not others. 1.1 root 3538: 3539: Autoincrement and autodecrement addresses typically have mode-dependent 3540: effects because the amount of the increment or decrement is the size 3541: of the operand being addressed. Some machines have other mode-dependent 3542: addresses. Many RISC machines have no mode-dependent addresses. 3543: 3544: You may assume that @var{addr} is a valid address for the machine. 3545: 3546: @findex LEGITIMATE_CONSTANT_P 3547: @item LEGITIMATE_CONSTANT_P (@var{x}) 3548: A C expression that is nonzero if @var{x} is a legitimate constant for 3549: an immediate operand on the target machine. You can assume that 3550: @var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 3551: @samp{1} is a suitable definition for this macro on machines where 3552: anything @code{CONSTANT_P} is valid.@refill 3553: @end table 3554: 1.1.1.2 root 3555: @node Condition Code 1.1 root 3556: @section Condition Code Status 3557: @cindex condition code status 3558: 3559: @findex cc_status 3560: The file @file{conditions.h} defines a variable @code{cc_status} to 3561: describe how the condition code was computed (in case the interpretation of 3562: the condition code depends on the instruction that it was set by). This 3563: variable contains the RTL expressions on which the condition code is 3564: currently based, and several standard flags. 3565: 3566: Sometimes additional machine-specific flags must be defined in the machine 3567: description header file. It can also add additional machine-specific 3568: information by defining @code{CC_STATUS_MDEP}. 3569: 3570: @table @code 3571: @findex CC_STATUS_MDEP 3572: @item CC_STATUS_MDEP 3573: C code for a data type which is used for declaring the @code{mdep} 3574: component of @code{cc_status}. It defaults to @code{int}. 3575: 3576: This macro is not used on machines that do not use @code{cc0}. 3577: 3578: @findex CC_STATUS_MDEP_INIT 3579: @item CC_STATUS_MDEP_INIT 3580: A C expression to initialize the @code{mdep} field to ``empty''. 3581: The default definition does nothing, since most machines don't use 3582: the field anyway. If you want to use the field, you should probably 3583: define this macro to initialize it. 3584: 3585: This macro is not used on machines that do not use @code{cc0}. 3586: 3587: @findex NOTICE_UPDATE_CC 3588: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 3589: A C compound statement to set the components of @code{cc_status} 3590: appropriately for an insn @var{insn} whose body is @var{exp}. It is 3591: this macro's responsibility to recognize insns that set the condition 3592: code as a byproduct of other activity as well as those that explicitly 3593: set @code{(cc0)}. 3594: 3595: This macro is not used on machines that do not use @code{cc0}. 3596: 3597: If there are insns that do not set the condition code but do alter 3598: other machine registers, this macro must check to see whether they 3599: invalidate the expressions that the condition code is recorded as 3600: reflecting. For example, on the 68000, insns that store in address 3601: registers do not set the condition code, which means that usually 3602: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 3603: insns. But suppose that the previous insn set the condition code 3604: based on location @samp{a4@@(102)} and the current insn stores a new 3605: value in @samp{a4}. Although the condition code is not changed by 3606: this, it will no longer be true that it reflects the contents of 3607: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 3608: @code{cc_status} in this case to say that nothing is known about the 3609: condition code value. 3610: 3611: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 3612: with the results of peephole optimization: insns whose patterns are 3613: @code{parallel} RTXs containing various @code{reg}, @code{mem} or 3614: constants which are just the operands. The RTL structure of these 3615: insns is not sufficient to indicate what the insns actually do. What 3616: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run 3617: @code{CC_STATUS_INIT}. 3618: 3619: A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 3620: that looks at an attribute (@pxref{Insn Attributes}) named, for example, 3621: @samp{cc}. This avoids having detailed information about patterns in 3622: two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 3623: 3624: @findex EXTRA_CC_MODES 3625: @item EXTRA_CC_MODES 3626: A list of names to be used for additional modes for condition code 3627: values in registers (@pxref{Jump Patterns}). These names are added 3628: to @code{enum machine_mode} and all have class @code{MODE_CC}. By 3629: convention, they should start with @samp{CC} and end with @samp{mode}. 3630: 3631: You should only define this macro if your machine does not use @code{cc0} 3632: and only if additional modes are required. 3633: 3634: @findex EXTRA_CC_NAMES 3635: @item EXTRA_CC_NAMES 3636: A list of C strings giving the names for the modes listed in 3637: @code{EXTRA_CC_MODES}. For example, the Sparc defines this macro and 3638: @code{EXTRA_CC_MODES} as 3639: 1.1.1.5 ! root 3640: @smallexample 1.1 root 3641: #define EXTRA_CC_MODES CC_NOOVmode, CCFPmode 3642: #define EXTRA_CC_NAMES "CC_NOOV", "CCFP" 1.1.1.5 ! root 3643: @end smallexample 1.1 root 3644: 3645: This macro is not required if @code{EXTRA_CC_MODES} is not defined. 3646: 3647: @findex SELECT_CC_MODE 1.1.1.4 root 3648: @item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 3649: Returns a mode from class @code{MODE_CC} to be used when comparison 3650: operation code @var{op} is applied to rtx @var{x} and @var{y}. For 3651: example, on the Sparc, @code{SELECT_CC_MODE} is defined as (see 3652: @pxref{Jump Patterns} for a description of the reason for this 3653: definition) 1.1 root 3654: 1.1.1.5 ! root 3655: @smallexample 1.1.1.4 root 3656: #define SELECT_CC_MODE(OP,X,Y) \ 1.1.1.5 ! root 3657: (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ ! 3658: ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ ! 3659: : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ ! 3660: || GET_CODE (X) == NEG) \ 1.1.1.4 root 3661: ? CC_NOOVmode : CCmode)) 1.1.1.5 ! root 3662: @end smallexample 1.1 root 3663: 3664: This macro is not required if @code{EXTRA_CC_MODES} is not defined. 3665: @end table 3666: 1.1.1.2 root 3667: @node Costs 1.1 root 3668: @section Describing Relative Costs of Operations 3669: @cindex costs of instructions 3670: @cindex relative costs 3671: @cindex speed of instructions 3672: 3673: These macros let you describe the relative speed of various operations 3674: on the target machine. 3675: 3676: @table @code 3677: @findex CONST_COSTS 1.1.1.3 root 3678: @item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) 1.1 root 3679: A part of a C @code{switch} statement that describes the relative costs 3680: of constant RTL expressions. It must contain @code{case} labels for 3681: expression codes @code{const_int}, @code{const}, @code{symbol_ref}, 3682: @code{label_ref} and @code{const_double}. Each case must ultimately 3683: reach a @code{return} statement to return the relative cost of the use 3684: of that kind of constant value in an expression. The cost may depend on 3685: the precise value of the constant, which is available for examination in 1.1.1.3 root 3686: @var{x}, and the rtx code of the expression in which it is contained, 3687: found in @var{outer_code}. 1.1 root 3688: 3689: @var{code} is the expression code---redundant, since it can be 3690: obtained with @code{GET_CODE (@var{x})}. 3691: 3692: @findex RTX_COSTS 3693: @findex COSTS_N_INSNS 1.1.1.3 root 3694: @item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 1.1 root 3695: Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. 3696: This can be used, for example, to indicate how costly a multiply 3697: instruction is. In writing this macro, you can use the construct 3698: @code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 1.1.1.3 root 3699: instructions. @var{outer_code} is the code of the expression in which 3700: @var{x} is contained. 1.1 root 3701: 3702: This macro is optional; do not define it if the default cost assumptions 3703: are adequate for the target machine. 3704: 3705: @findex ADDRESS_COST 3706: @item ADDRESS_COST (@var{address}) 3707: An expression giving the cost of an addressing mode that contains 3708: @var{address}. If not defined, the cost is computed from 3709: the @var{address} expression and the @code{CONST_COSTS} values. 3710: 3711: For most CISC machines, the default cost is a good approximation of the 3712: true cost of the addressing mode. However, on RISC machines, all 3713: instructions normally have the same length and execution time. Hence 3714: all addresses will have equal costs. 3715: 3716: In cases where more than one form of an address is known, the form with 3717: the lowest cost will be used. If multiple forms have the same, lowest, 3718: cost, the one that is the most complex will be used. 3719: 3720: For example, suppose an address that is equal to the sum of a register 3721: and a constant is used twice in the same basic block. When this macro 3722: is not defined, the address will be computed in a register and memory 3723: references will be indirect through that register. On machines where 3724: the cost of the addressing mode containing the sum is no higher than 3725: that of a simple indirect reference, this will produce an additional 3726: instruction and possibly require an additional register. Proper 3727: specification of this macro eliminates this overhead for such machines. 3728: 3729: Similar use of this macro is made in strength reduction of loops. 3730: 3731: @var{address} need not be valid as an address. In such a case, the cost 3732: is not relevant and can be any value; invalid addresses need not be 3733: assigned a different cost. 3734: 3735: On machines where an address involving more than one register is as 3736: cheap as an address computation involving only one register, defining 3737: @code{ADDRESS_COST} to reflect this can cause two registers to be live 3738: over a region of code where only one would have been if 3739: @code{ADDRESS_COST} were not defined in that manner. This effect should 3740: be considered in the definition of this macro. Equivalent costs should 3741: probably only be given to addresses with different numbers of registers 3742: on machines with lots of registers. 3743: 3744: This macro will normally either not be defined or be defined as a 3745: constant. 3746: 3747: @findex REGISTER_MOVE_COST 3748: @item REGISTER_MOVE_COST (@var{from}, @var{to}) 3749: A C expression for the cost of moving data from a register in class 3750: @var{from} to one in class @var{to}. The classes are expressed using 1.1.1.5 ! root 3751: the enumeration values such as @code{GENERAL_REGS}. A value of 4 is the 1.1 root 3752: default; other values are interpreted relative to that. 3753: 3754: It is not required that the cost always equal 2 when @var{from} is the 3755: same as @var{to}; on some machines it is expensive to move between 3756: registers if they are not general registers. 3757: 3758: If reload sees an insn consisting of a single @code{set} between two 3759: hard registers, and if @code{REGISTER_MOVE_COST} applied to their 3760: classes returns a value of 2, reload does not check to ensure that the 3761: constraints of the insn are met. Setting a cost of other than 2 will 3762: allow reload to verify that the constraints are met. You should do this 3763: if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 3764: 3765: @findex MEMORY_MOVE_COST 3766: @item MEMORY_MOVE_COST (@var{m}) 3767: A C expression for the cost of moving data of mode @var{m} between a 3768: register and memory. A value of 2 is the default; this cost is relative 3769: to those in @code{REGISTER_MOVE_COST}. 3770: 3771: If moving between registers and memory is more expensive than between 3772: two registers, you should define this macro to express the relative cost. 3773: 3774: @findex BRANCH_COST 3775: @item BRANCH_COST 3776: A C expression for the cost of a branch instruction. A value of 1 is 3777: the default; other values are interpreted relative to that. 3778: @end table 3779: 3780: Here are additional macros which do not specify precise relative costs, 3781: but only that certain actions are more expensive than GNU CC would 3782: ordinarily expect. 3783: 3784: @table @code 3785: @findex SLOW_BYTE_ACCESS 3786: @item SLOW_BYTE_ACCESS 3787: Define this macro as a C expression which is nonzero if accessing less 3788: than a word of memory (i.e. a @code{char} or a @code{short}) is no 3789: faster than accessing a word of memory, i.e., if such access 3790: require more than one instruction or if there is no difference in cost 3791: between byte and (aligned) word loads. 3792: 3793: When this macro is not defined, the compiler will access a field by 3794: finding the smallest containing object; when it is defined, a fullword 3795: load will be used if alignment permits. Unless bytes accesses are 3796: faster than word accesses, using word accesses is preferable since it 3797: may eliminate subsequent memory access if subsequent accesses occur to 3798: other fields in the same word of the structure, but to different bytes. 3799: 3800: @findex SLOW_ZERO_EXTEND 3801: @item SLOW_ZERO_EXTEND 3802: Define this macro if zero-extension (of a @code{char} or @code{short} 3803: to an @code{int}) can be done faster if the destination is a register 3804: that is known to be zero. 3805: 3806: If you define this macro, you must have instruction patterns that 3807: recognize RTL structures like this: 3808: 1.1.1.5 ! root 3809: @smallexample 1.1 root 3810: (set (strict_low_part (subreg:QI (reg:SI @dots{}) 0)) @dots{}) 1.1.1.5 ! root 3811: @end smallexample 1.1 root 3812: 3813: @noindent 3814: and likewise for @code{HImode}. 3815: 3816: @findex SLOW_UNALIGNED_ACCESS 3817: @item SLOW_UNALIGNED_ACCESS 1.1.1.2 root 3818: Define this macro to be the value 1 if unaligned accesses have a cost 3819: many times greater than aligned accesses, for example if they are 3820: emulated in a trap handler. 1.1 root 3821: 1.1.1.2 root 3822: When this macro is non-zero, the compiler will act as if 3823: @code{STRICT_ALIGNMENT} were non-zero when generating code for block 1.1 root 3824: moves. This can cause significantly more instructions to be produced. 1.1.1.2 root 3825: Therefore, do not set this macro non-zero if unaligned accesses only add a 1.1 root 3826: cycle or two to the time for a memory access. 3827: 1.1.1.2 root 3828: If the value of this macro is always zero, it need not be defined. 3829: 1.1 root 3830: @findex DONT_REDUCE_ADDR 3831: @item DONT_REDUCE_ADDR 3832: Define this macro to inhibit strength reduction of memory addresses. 3833: (On some machines, such strength reduction seems to do harm rather 3834: than good.) 3835: 3836: @findex MOVE_RATIO 3837: @item MOVE_RATIO 3838: The number of scalar move insns which should be generated instead of a 3839: string move insn or a library call. Increasing the value will always 3840: make code faster, but eventually incurs high cost in increased code size. 3841: 3842: If you don't define this, a reasonable default is used. 3843: 3844: @findex NO_FUNCTION_CSE 3845: @item NO_FUNCTION_CSE 3846: Define this macro if it is as good or better to call a constant 3847: function address than to call an address kept in a register. 3848: 3849: @findex NO_RECURSIVE_FUNCTION_CSE 3850: @item NO_RECURSIVE_FUNCTION_CSE 3851: Define this macro if it is as good or better for a function to call 3852: itself with an explicit address than to call an address kept in a 3853: register. 1.1.1.4 root 3854: 3855: @findex ADJUST_COST 3856: @item ADJUST_COST (@var{insn}, @var{link}, @var{dep_insn}, @var{cost}) 3857: A C statement (sans semicolon) to update the integer variable @var{cost} 3858: based on the relationship between @var{insn} that is dependent on 3859: @var{dep_insn} through the dependence @var{link}. The default is to 3860: make no adjustment to @var{cost}. This can be used for example to 3861: specify to the scheduler that an output- or anti-dependence does not 3862: incur the same cost as a data-dependence. 1.1 root 3863: @end table 3864: 1.1.1.2 root 3865: @node Sections 1.1 root 3866: @section Dividing the Output into Sections (Texts, Data, @dots{}) 1.1.1.5 ! root 3867: @c the above section title is WAY too long. maybe cut the part between ! 3868: @c the (...)? --mew 10feb93 1.1 root 3869: 3870: An object file is divided into sections containing different types of 3871: data. In the most common case, there are three sections: the @dfn{text 3872: section}, which holds instructions and read-only data; the @dfn{data 3873: section}, which holds initialized writable data; and the @dfn{bss 3874: section}, which holds uninitialized data. Some systems have other kinds 3875: of sections. 3876: 3877: The compiler must tell the assembler when to switch sections. These 3878: macros control what commands to output to tell the assembler this. You 3879: can also define additional sections. 3880: 3881: @table @code 3882: @findex TEXT_SECTION_ASM_OP 3883: @item TEXT_SECTION_ASM_OP 1.1.1.4 root 3884: A C expression whose value is a string containing the assembler 3885: operation that should precede instructions and read-only data. Normally 3886: @code{".text"} is right. 1.1 root 3887: 3888: @findex DATA_SECTION_ASM_OP 3889: @item DATA_SECTION_ASM_OP 1.1.1.4 root 3890: A C expression whose value is a string containing the assembler 3891: operation to identify the following data as writable initialized data. 3892: Normally @code{".data"} is right. 1.1 root 3893: 3894: @findex SHARED_SECTION_ASM_OP 3895: @item SHARED_SECTION_ASM_OP 1.1.1.4 root 3896: if defined, a C expression whose value is a string containing the 3897: assembler operation to identify the following data as shared data. If 3898: not defined, @code{DATA_SECTION_ASM_OP} will be used. 1.1 root 3899: 3900: @findex INIT_SECTION_ASM_OP 3901: @item INIT_SECTION_ASM_OP 1.1.1.4 root 3902: if defined, a C expression whose value is a string containing the 3903: assembler operation to identify the following data as initialization 3904: code. If not defined, GNU CC will assume such a section does not 3905: exist. 1.1 root 3906: 3907: @findex EXTRA_SECTIONS 3908: @findex in_text 3909: @findex in_data 3910: @item EXTRA_SECTIONS 3911: A list of names for sections other than the standard two, which are 3912: @code{in_text} and @code{in_data}. You need not define this macro 3913: on a system with no other sections (that GCC needs to use). 3914: 3915: @findex EXTRA_SECTION_FUNCTIONS 3916: @findex text_section 3917: @findex data_section 3918: @item EXTRA_SECTION_FUNCTIONS 3919: One or more functions to be defined in @file{varasm.c}. These 3920: functions should do jobs analogous to those of @code{text_section} and 3921: @code{data_section}, for your additional sections. Do not define this 3922: macro if you do not define @code{EXTRA_SECTIONS}. 3923: 3924: @findex READONLY_DATA_SECTION 3925: @item READONLY_DATA_SECTION 3926: On most machines, read-only variables, constants, and jump tables are 3927: placed in the text section. If this is not the case on your machine, 3928: this macro should be defined to be the name of a function (either 3929: @code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that 3930: switches to the section to be used for read-only items. 3931: 3932: If these items should be placed in the text section, this macro should 3933: not be defined. 3934: 3935: @findex SELECT_SECTION 3936: @item SELECT_SECTION (@var{exp}, @var{reloc}) 3937: A C statement or statements to switch to the appropriate section for 3938: output of @var{exp}. You can assume that @var{exp} is either a 3939: @code{VAR_DECL} node or a constant of some sort. @var{reloc} 3940: indicates whether the initial value of @var{exp} requires link-time 3941: relocations. Select the section by calling @code{text_section} or one 3942: of the alternatives for other sections. 3943: 3944: Do not define this macro if you put all read-only variables and 3945: constants in the read-only data section (usually the text section). 3946: 3947: @findex SELECT_RTX_SECTION 3948: @item SELECT_RTX_SECTION (@var{mode}, @var{rtx}) 3949: A C statement or statements to switch to the appropriate section for 3950: output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} 3951: is some kind of constant in RTL. The argument @var{mode} is redundant 3952: except in the case of a @code{const_int} rtx. Select the section by 3953: calling @code{text_section} or one of the alternatives for other 3954: sections. 3955: 3956: Do not define this macro if you put all constants in the read-only 3957: data section. 3958: 3959: @findex JUMP_TABLES_IN_TEXT_SECTION 3960: @item JUMP_TABLES_IN_TEXT_SECTION 3961: Define this macro if jump tables (for @code{tablejump} insns) should be 3962: output in the text section, along with the assembler instructions. 3963: Otherwise, the readonly data section is used. 3964: 3965: This macro is irrelevant if there is no separate readonly data section. 3966: 3967: @findex ENCODE_SECTION_INFO 3968: @item ENCODE_SECTION_INFO (@var{decl}) 3969: Define this macro if references to a symbol must be treated differently 3970: depending on something about the variable or function named by the 3971: symbol (such as what section it is in). 3972: 3973: The macro definition, if any, is executed immediately after the rtl for 3974: @var{decl} has been created and stored in @code{DECL_RTL (@var{decl})}. 3975: The value of the rtl will be a @code{mem} whose address is a 3976: @code{symbol_ref}. 3977: 3978: @cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO} 3979: The usual thing for this macro to do is to record a flag in the 3980: @code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a 3981: modified name string in the @code{symbol_ref} (if one bit is not enough 3982: information). 1.1.1.4 root 3983: 3984: @findex STRIP_NAME_ENCODING 3985: @item STRIP_NAME_ENCODING (@var{var}, @var{sym_name}) 3986: Decode @var{sym_name} and store the real name part in @var{var}, sans 3987: the characters that encode section info. Define this macro if 3988: @code{ENCODE_SECTION_INFO} alters the symbol's name string. 1.1 root 3989: @end table 3990: 1.1.1.2 root 3991: @node PIC 1.1 root 3992: @section Position Independent Code 3993: @cindex position independent code 3994: @cindex PIC 3995: 3996: This section describes macros that help implement generation of position 3997: independent code. Simply defining these macros is not enough to 3998: generate valid PIC; you must also add support to the macros 1.1.1.5 ! root 3999: @code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as ! 4000: well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 1.1 root 4001: @samp{movsi} to do something appropriate when the source operand 4002: contains a symbolic address. You may also need to alter the handling of 4003: switch statements so that they use relative addresses. 1.1.1.5 ! root 4004: @c i rearranged the order of the macros above to try to force one of ! 4005: @c them to the next line, to eliminate an overfull hbox. --mew 10feb93 1.1 root 4006: 4007: @table @code 4008: @findex PIC_OFFSET_TABLE_REGNUM 4009: @item PIC_OFFSET_TABLE_REGNUM 4010: The register number of the register used to address a table of static 4011: data addresses in memory. In some cases this register is defined by a 4012: processor's ``application binary interface'' (ABI). When this macro 4013: is defined, RTL is generated for this register once, as with the stack 4014: pointer and frame pointer registers. If this macro is not defined, it 4015: is up to the machine-dependent files to allocate such a register (if 4016: necessary). 4017: 4018: @findex FINALIZE_PIC 4019: @item FINALIZE_PIC 4020: By generating position-independent code, when two different programs (A 4021: and B) share a common library (libC.a), the text of the library can be 4022: shared whether or not the library is linked at the same address for both 4023: programs. In some of these environments, position-independent code 4024: requires not only the use of different addressing modes, but also 4025: special code to enable the use of these addressing modes. 4026: 4027: The @code{FINALIZE_PIC} macro serves as a hook to emit these special 4028: codes once the function is being compiled into assembly code, but not 4029: before. (It is not done before, because in the case of compiling an 4030: inline function, it would lead to multiple PIC prologues being 4031: included in functions which used inline functions and were compiled to 4032: assembly language.) 4033: 1.1.1.4 root 4034: @findex LEGITIMATE_PIC_OPERAND_P 4035: @item LEGITIMATE_PIC_OPERAND_P (@var{x}) 4036: A C expression that is nonzero if @var{x} is a legitimate immediate 4037: operand on the target machine when generating position independent code. 4038: You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 4039: check this. You can also assume @var{flag_pic} is true, so you need not 4040: check it either. You need not define this macro if all constants 4041: (including @code{SYMBOL_REF}) can be immediate operands when generating 4042: position independent code. 1.1 root 4043: @end table 4044: 1.1.1.2 root 4045: @node Assembler Format 1.1 root 4046: @section Defining the Output Assembler Language 4047: 4048: This section describes macros whose principal purpose is to describe how 4049: to write instructions in assembler language--rather than what the 4050: instructions do. 4051: 4052: @menu 4053: * File Framework:: Structural information for the assembler file. 4054: * Data Output:: Output of constants (numbers, strings, addresses). 4055: * Uninitialized Data:: Output of uninitialized variables. 4056: * Label Output:: Output and generation of labels. 1.1.1.4 root 4057: * Initialization:: General principles of initialization 4058: and termination routines. 4059: * Macros for Initialization:: 4060: Specific macros that control the handling of 4061: initialization and termination routines. 1.1 root 4062: * Instruction Output:: Output of actual instructions. 4063: * Dispatch Tables:: Output of jump tables. 4064: * Alignment Output:: Pseudo ops for alignment and skipping data. 4065: @end menu 4066: 1.1.1.2 root 4067: @node File Framework 1.1 root 4068: @subsection The Overall Framework of an Assembler File 4069: @cindex assembler format 4070: @cindex output of assembler code 4071: 4072: @table @code 4073: @findex ASM_FILE_START 4074: @item ASM_FILE_START (@var{stream}) 4075: A C expression which outputs to the stdio stream @var{stream} 4076: some appropriate text to go at the start of an assembler file. 4077: 4078: Normally this macro is defined to output a line containing 4079: @samp{#NO_APP}, which is a comment that has no effect on most 4080: assemblers but tells the GNU assembler that it can save time by not 4081: checking for certain assembler constructs. 4082: 4083: On systems that use SDB, it is necessary to output certain commands; 4084: see @file{attasm.h}. 4085: 4086: @findex ASM_FILE_END 4087: @item ASM_FILE_END (@var{stream}) 4088: A C expression which outputs to the stdio stream @var{stream} 4089: some appropriate text to go at the end of an assembler file. 4090: 4091: If this macro is not defined, the default is to output nothing 4092: special at the end of the file. Most systems don't require any 4093: definition. 4094: 4095: On systems that use SDB, it is necessary to output certain commands; 4096: see @file{attasm.h}. 4097: 4098: @findex ASM_IDENTIFY_GCC 4099: @item ASM_IDENTIFY_GCC (@var{file}) 4100: A C statement to output assembler commands which will identify 4101: the object file as having been compiled with GNU CC (or another 4102: GNU compiler). 4103: 4104: If you don't define this macro, the string @samp{gcc_compiled.:} 4105: is output. This string is calculated to define a symbol which, 4106: on BSD systems, will never be defined for any other reason. 4107: GDB checks for the presence of this symbol when reading the 4108: symbol table of an executable. 4109: 4110: On non-BSD systems, you must arrange communication with GDB in 4111: some other fashion. If GDB is not used on your system, you can 4112: define this macro with an empty body. 4113: 4114: @findex ASM_COMMENT_START 4115: @item ASM_COMMENT_START 4116: A C string constant describing how to begin a comment in the target 4117: assembler language. The compiler assumes that the comment will end at 4118: the end of the line. 4119: 4120: @findex ASM_APP_ON 4121: @item ASM_APP_ON 4122: A C string constant for text to be output before each @code{asm} 4123: statement or group of consecutive ones. Normally this is 4124: @code{"#APP"}, which is a comment that has no effect on most 4125: assemblers but tells the GNU assembler that it must check the lines 4126: that follow for all valid assembler constructs. 4127: 4128: @findex ASM_APP_OFF 4129: @item ASM_APP_OFF 4130: A C string constant for text to be output after each @code{asm} 4131: statement or group of consecutive ones. Normally this is 4132: @code{"#NO_APP"}, which tells the GNU assembler to resume making the 4133: time-saving assumptions that are valid for ordinary compiler output. 4134: 4135: @findex ASM_OUTPUT_SOURCE_FILENAME 4136: @item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 4137: A C statement to output COFF information or DWARF debugging information 4138: which indicates that filename @var{name} is the current source file to 4139: the stdio stream @var{stream}. 4140: 4141: This macro need not be defined if the standard form of output 4142: for the file format in use is appropriate. 4143: 4144: @findex ASM_OUTPUT_SOURCE_LINE 4145: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 4146: A C statement to output DBX or SDB debugging information before code 4147: for line number @var{line} of the current source file to the 4148: stdio stream @var{stream}. 4149: 4150: This macro need not be defined if the standard form of debugging 4151: information for the debugger in use is appropriate. 4152: 4153: @findex ASM_OUTPUT_IDENT 4154: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 4155: A C statement to output something to the assembler file to handle a 4156: @samp{#ident} directive containing the text @var{string}. If this 4157: macro is not defined, nothing is output for a @samp{#ident} directive. 4158: 4159: @findex OBJC_PROLOGUE 4160: @item OBJC_PROLOGUE 4161: A C statement to output any assembler statements which are required to 4162: precede any Objective C object definitions or message sending. The 4163: statement is executed only when compiling an Objective C program. 4164: @end table 4165: 1.1.1.2 root 4166: @node Data Output 1.1 root 4167: @subsection Output of Data 4168: 4169: @table @code 4170: @findex ASM_OUTPUT_LONG_DOUBLE 4171: @findex ASM_OUTPUT_DOUBLE 4172: @findex ASM_OUTPUT_FLOAT 4173: @item ASM_OUTPUT_LONG_DOUBLE (@var{stream}, @var{value}) 1.1.1.5 ! root 4174: @itemx ASM_OUTPUT_DOUBLE (@var{stream}, @var{value}) ! 4175: @itemx ASM_OUTPUT_FLOAT (@var{stream}, @var{value}) 1.1 root 4176: A C statement to output to the stdio stream @var{stream} an assembler 4177: instruction to assemble a floating-point constant of @code{TFmode}, 4178: @code{DFmode} or @code{SFmode}, respectively, whose value is 4179: @var{value}. @var{value} will be a C expression of type 1.1.1.5 ! root 4180: @code{REAL_VALUE_TYPE}. Macros such as ! 4181: @code{REAL_VALUE_TO_TARGET_DOUBLE} are useful for writing these ! 4182: definitions. 1.1 root 4183: 4184: @findex ASM_OUTPUT_QUADRUPLE_INT 4185: @findex ASM_OUTPUT_DOUBLE_INT 4186: @findex ASM_OUTPUT_INT 4187: @findex ASM_OUTPUT_SHORT 4188: @findex ASM_OUTPUT_CHAR 4189: @findex output_addr_const 4190: @item ASM_OUTPUT_QUADRUPLE_INT (@var{stream}, @var{exp}) 1.1.1.5 ! root 4191: @itemx ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp}) ! 4192: @itemx ASM_OUTPUT_INT (@var{stream}, @var{exp}) 1.1 root 4193: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp}) 4194: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp}) 4195: A C statement to output to the stdio stream @var{stream} an assembler 4196: instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes, 4197: respectively, whose value is @var{value}. The argument @var{exp} will 4198: be an RTL expression which represents a constant value. Use 4199: @samp{output_addr_const (@var{stream}, @var{exp})} to output this value 4200: as an assembler expression.@refill 4201: 4202: For sizes larger than @code{UNITS_PER_WORD}, if the action of a macro 4203: would be identical to repeatedly calling the macro corresponding to 4204: a size of @code{UNITS_PER_WORD}, once for each word, you need not define 4205: the macro. 4206: 4207: @findex ASM_OUTPUT_BYTE 4208: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value}) 4209: A C statement to output to the stdio stream @var{stream} an assembler 4210: instruction to assemble a single byte containing the number @var{value}. 4211: 4212: @findex ASM_BYTE_OP 4213: @item ASM_BYTE_OP 4214: A C string constant giving the pseudo-op to use for a sequence of 4215: single-byte constants. If this macro is not defined, the default is 4216: @code{"byte"}. 4217: 4218: @findex ASM_OUTPUT_ASCII 4219: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 4220: A C statement to output to the stdio stream @var{stream} an assembler 4221: instruction to assemble a string constant containing the @var{len} 4222: bytes at @var{ptr}. @var{ptr} will be a C expression of type 4223: @code{char *} and @var{len} a C expression of type @code{int}. 4224: 4225: If the assembler has a @code{.ascii} pseudo-op as found in the 4226: Berkeley Unix assembler, do not define the macro 4227: @code{ASM_OUTPUT_ASCII}. 4228: 4229: @findex ASM_OUTPUT_POOL_PROLOGUE 4230: @item ASM_OUTPUT_POOL_PROLOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 4231: A C statement to output assembler commands to define the start of the 4232: constant pool for a function. @var{funname} is a string giving 4233: the name of the function. Should the return type of the function 4234: be required, it can be obtained via @var{fundecl}. @var{size} 4235: is the size, in bytes, of the constant pool that will be written 4236: immediately after this call. 4237: 4238: If no constant-pool prefix is required, the usual case, this macro need 4239: not be defined. 4240: 4241: @findex ASM_OUTPUT_SPECIAL_POOL_ENTRY 4242: @item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 4243: A C statement (with or without semicolon) to output a constant in the 4244: constant pool, if it needs special treatment. (This macro need not do 4245: anything for RTL expressions that can be output normally.) 4246: 4247: The argument @var{file} is the standard I/O stream to output the 4248: assembler code on. @var{x} is the RTL expression for the constant to 4249: output, and @var{mode} is the machine mode (in case @var{x} is a 4250: @samp{const_int}). @var{align} is the required alignment for the value 4251: @var{x}; you should output an assembler directive to force this much 4252: alignment. 4253: 4254: The argument @var{labelno} is a number to use in an internal label for 4255: the address of this pool entry. The definition of this macro is 4256: responsible for outputting the label definition at the proper place. 4257: Here is how to do this: 4258: 4259: @example 4260: ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); 4261: @end example 4262: 4263: When you output a pool entry specially, you should end with a 4264: @code{goto} to the label @var{jumpto}. This will prevent the same pool 4265: entry from being output a second time in the usual manner. 4266: 4267: You need not define this macro if it would do nothing. 4268: 4269: @findex ASM_OPEN_PAREN 4270: @findex ASM_CLOSE_PAREN 4271: @item ASM_OPEN_PAREN 4272: @itemx ASM_CLOSE_PAREN 4273: These macros are defined as C string constant, describing the syntax 4274: in the assembler for grouping arithmetic expressions. The following 4275: definitions are correct for most assemblers: 4276: 4277: @example 4278: #define ASM_OPEN_PAREN "(" 4279: #define ASM_CLOSE_PAREN ")" 4280: @end example 4281: @end table 4282: 1.1.1.5 ! root 4283: These macros are provided by @file{real.h} for writing the definitions ! 4284: of @code{ASM_OUTPUT_DOUBLE} and the like: ! 4285: ! 4286: @table @code ! 4287: @item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) ! 4288: @itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) ! 4289: @itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) ! 4290: @findex REAL_VALUE_TO_TARGET_SINGLE ! 4291: @findex REAL_VALUE_TO_TARGET_DOUBLE ! 4292: @findex REAL_VALUE_TO_TARGET_LONG_DOUBLE ! 4293: These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's ! 4294: floating point representation, and store its bit pattern in the array of ! 4295: @code{long int} whose address is @var{l}. The number of elements in the ! 4296: output array is determined by the size of the desired target floating ! 4297: point data type: 32 bits of it go in each @code{long int} array ! 4298: element. Each array element holds 32 bits of the result, even if ! 4299: @code{long int} is wider than 32 bits on the host machine. ! 4300: ! 4301: The array element values are designed so that you can print them out ! 4302: using @code{fprintf} in the order they should appear in the target ! 4303: machine's memory. ! 4304: ! 4305: @item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string}) ! 4306: @findex REAL_VALUE_TO_DECIMAL ! 4307: This macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a ! 4308: decimal number and stores it as a string into @var{string}. ! 4309: You must pass, as @var{string}, the address of a long enough block ! 4310: of space to hold the result. ! 4311: ! 4312: The argument @var{format} is a @code{printf}-specification that serves ! 4313: as a suggestion for how to format the output string. ! 4314: @end table ! 4315: 1.1.1.2 root 4316: @node Uninitialized Data 1.1 root 4317: @subsection Output of Uninitialized Variables 4318: 4319: Each of the macros in this section is used to do the whole job of 4320: outputting a single uninitialized variable. 4321: 4322: @table @code 4323: @findex ASM_OUTPUT_COMMON 4324: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 4325: A C statement (sans semicolon) to output to the stdio stream 4326: @var{stream} the assembler definition of a common-label named 4327: @var{name} whose size is @var{size} bytes. The variable @var{rounded} 4328: is the size rounded up to whatever alignment the caller wants. 4329: 4330: Use the expression @code{assemble_name (@var{stream}, @var{name})} to 4331: output the name itself; before and after that, output the additional 4332: assembler syntax for defining the name, and a newline. 4333: 4334: This macro controls how the assembler definitions of uninitialized 4335: global variables are output. 4336: 4337: @findex ASM_OUTPUT_ALIGNED_COMMON 4338: @item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 4339: Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 4340: separate, explicit argument. If you define this macro, it is used in 4341: place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 4342: handling the required alignment of the variable. 4343: 4344: @findex ASM_OUTPUT_SHARED_COMMON 4345: @item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 4346: If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it 4347: is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} 4348: will be used. 4349: 4350: @findex ASM_OUTPUT_LOCAL 4351: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 4352: A C statement (sans semicolon) to output to the stdio stream 4353: @var{stream} the assembler definition of a local-common-label named 4354: @var{name} whose size is @var{size} bytes. The variable @var{rounded} 4355: is the size rounded up to whatever alignment the caller wants. 4356: 4357: Use the expression @code{assemble_name (@var{stream}, @var{name})} to 4358: output the name itself; before and after that, output the additional 4359: assembler syntax for defining the name, and a newline. 4360: 4361: This macro controls how the assembler definitions of uninitialized 4362: static variables are output. 4363: 4364: @findex ASM_OUTPUT_ALIGNED_LOCAL 4365: @item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 4366: Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 4367: separate, explicit argument. If you define this macro, it is used in 4368: place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 4369: handling the required alignment of the variable. 4370: 4371: @findex ASM_OUTPUT_SHARED_LOCAL 4372: @item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 4373: If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it 4374: is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} 4375: will be used. 4376: @end table 4377: 1.1.1.2 root 4378: @node Label Output 1.1 root 4379: @subsection Output and Generation of Labels 4380: 4381: @table @code 4382: @findex ASM_OUTPUT_LABEL 4383: @findex assemble_name 4384: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 4385: A C statement (sans semicolon) to output to the stdio stream 4386: @var{stream} the assembler definition of a label named @var{name}. 4387: Use the expression @code{assemble_name (@var{stream}, @var{name})} to 4388: output the name itself; before and after that, output the additional 4389: assembler syntax for defining the name, and a newline. 4390: 4391: @findex ASM_DECLARE_FUNCTION_NAME 4392: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 4393: A C statement (sans semicolon) to output to the stdio stream 4394: @var{stream} any text necessary for declaring the name @var{name} of a 4395: function which is being defined. This macro is responsible for 4396: outputting the label definition (perhaps using 4397: @code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 4398: @code{FUNCTION_DECL} tree node representing the function. 4399: 4400: If this macro is not defined, then the function name is defined in the 4401: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 4402: 4403: @findex ASM_DECLARE_FUNCTION_SIZE 4404: @item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 4405: A C statement (sans semicolon) to output to the stdio stream 4406: @var{stream} any text necessary for declaring the size of a function 4407: which is being defined. The argument @var{name} is the name of the 4408: function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 4409: representing the function. 4410: 4411: If this macro is not defined, then the function size is not defined. 4412: 4413: @findex ASM_DECLARE_OBJECT_NAME 4414: @item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 4415: A C statement (sans semicolon) to output to the stdio stream 4416: @var{stream} any text necessary for declaring the name @var{name} of an 4417: initialized variable which is being defined. This macro must output the 4418: label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 4419: @var{decl} is the @code{VAR_DECL} tree node representing the variable. 4420: 4421: If this macro is not defined, then the variable name is defined in the 4422: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 4423: 4424: @findex ASM_GLOBALIZE_LABEL 4425: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) 4426: A C statement (sans semicolon) to output to the stdio stream 4427: @var{stream} some commands that will make the label @var{name} global; 4428: that is, available for reference from other files. Use the expression 4429: @code{assemble_name (@var{stream}, @var{name})} to output the name 4430: itself; before and after that, output the additional assembler syntax 4431: for making that name global, and a newline. 4432: 4433: @findex ASM_OUTPUT_EXTERNAL 4434: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 4435: A C statement (sans semicolon) to output to the stdio stream 4436: @var{stream} any text necessary for declaring the name of an external 4437: symbol named @var{name} which is referenced in this compilation but 4438: not defined. The value of @var{decl} is the tree node for the 4439: declaration. 4440: 4441: This macro need not be defined if it does not need to output anything. 4442: The GNU assembler and most Unix assemblers don't require anything. 4443: 4444: @findex ASM_OUTPUT_EXTERNAL_LIBCALL 4445: @item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 4446: A C statement (sans semicolon) to output on @var{stream} an assembler 4447: pseudo-op to declare a library function name external. The name of the 4448: library function is given by @var{symref}, which has type @code{rtx} and 4449: is a @code{symbol_ref}. 4450: 4451: This macro need not be defined if it does not need to output anything. 4452: The GNU assembler and most Unix assemblers don't require anything. 4453: 4454: @findex ASM_OUTPUT_LABELREF 4455: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 4456: A C statement (sans semicolon) to output to the stdio stream 4457: @var{stream} a reference in assembler syntax to a label named 4458: @var{name}. This should add @samp{_} to the front of the name, if that 4459: is customary on your operating system, as it is in most Berkeley Unix 4460: systems. This macro is used in @code{assemble_name}. 4461: 4462: @findex ASM_OUTPUT_LABELREF_AS_INT 4463: @item ASM_OUTPUT_LABELREF_AS_INT (@var{file}, @var{label}) 4464: Define this macro for systems that use the program @code{collect2}. 4465: The definition should be a C statement to output a word containing 4466: a reference to the label @var{label}. 4467: 4468: @findex ASM_OUTPUT_INTERNAL_LABEL 4469: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 4470: A C statement to output to the stdio stream @var{stream} a label whose 4471: name is made from the string @var{prefix} and the number @var{num}. 1.1.1.2 root 4472: 4473: It is absolutely essential that these labels be distinct from the labels 4474: used for user-level functions and variables. Otherwise, certain programs 4475: will have name conflicts with internal labels. 4476: 4477: It is desirable to exclude internal labels from the symbol table of the 4478: object file. Most assemblers have a naming convention for labels that 4479: should be excluded; on many systems, the letter @samp{L} at the 4480: beginning of a label has this effect. You should find out what 4481: convention your system uses, and follow it. 4482: 4483: The usual definition of this macro is as follows: 1.1 root 4484: 4485: @example 4486: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 4487: @end example 4488: 1.1.1.2 root 4489: @findex ASM_GENERATE_INTERNAL_LABEL 4490: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 4491: A C statement to store into the string @var{string} a label whose name 4492: is made from the string @var{prefix} and the number @var{num}. 4493: 1.1.1.5 ! root 4494: This string, when output subsequently by @code{assemble_name}, should ! 4495: produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce ! 4496: with the same @var{prefix} and @var{num}. 1.1.1.2 root 4497: 4498: If the string begins with @samp{*}, then @code{assemble_name} will 4499: output the rest of the string unchanged. It is often convenient for 4500: @code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 4501: string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 4502: to output the string, and may change it. (Of course, 4503: @code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 4504: you should know what it does on your machine.) 4505: 1.1 root 4506: @findex ASM_FORMAT_PRIVATE_NAME 4507: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 4508: A C expression to assign to @var{outvar} (which is a variable of type 4509: @code{char *}) a newly allocated string made from the string 4510: @var{name} and the number @var{number}, with some suitable punctuation 4511: added. Use @code{alloca} to get space for the string. 4512: 1.1.1.5 ! root 4513: The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to ! 4514: produce an assembler label for an internal static variable whose name is ! 4515: @var{name}. Therefore, the string must be such as to result in valid ! 4516: assembler code. The argument @var{number} is different each time this ! 4517: macro is executed; it prevents conflicts between similarly-named ! 4518: internal static variables in different scopes. 1.1 root 4519: 4520: Ideally this string should not be a valid C identifier, to prevent any 4521: conflict with the user's own symbols. Most assemblers allow periods 4522: or percent signs in assembler symbols; putting at least one of these 4523: between the name and the number will suffice. 4524: 4525: @findex OBJC_GEN_METHOD_LABEL 4526: @item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 4527: Define this macro to override the default assembler names used for 4528: Objective C methods. 4529: 4530: The default name is a unique method number followed by the name of the 4531: class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 4532: the category is also included in the assembler name (e.g.@: 4533: @samp{_1_Foo_Bar}). 4534: 4535: These names are safe on most systems, but make debugging difficult since 4536: the method's selector is not present in the name. Therefore, particular 4537: systems define other ways of computing names. 4538: 1.1.1.2 root 4539: @var{buf} is an expression of type @code{char *} which gives you a 4540: buffer in which to store the name; its length is as long as 4541: @var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 4542: 50 characters extra. 4543: 4544: The argument @var{is_inst} specifies whether the method is an instance 4545: method or a class method; @var{class_name} is the name of the class; 4546: @var{cat_name} is the name of the category (or NULL if the method is not 4547: in a category); and @var{sel_name} is the name of the selector. 1.1 root 4548: 4549: On systems where the assembler can handle quoted names, you can use this 4550: macro to provide more human-readable names. 4551: @end table 4552: 1.1.1.4 root 4553: @node Initialization 4554: @subsection How Initialization Functions Are Handled 1.1 root 4555: @cindex initialization routines 4556: @cindex termination routines 4557: @cindex constructors, output of 4558: @cindex destructors, output of 4559: 4560: The compiled code for certain languages includes @dfn{constructors} 4561: (also called @dfn{initialization routines})---functions to initialize 4562: data in the program when the program is started. These functions need 4563: to be called before the program is ``started''---that is to say, before 4564: @code{main} is called. 4565: 4566: Compiling some languages generates @dfn{destructors} (also called 4567: @dfn{termination routines}) that should be called when the program 4568: terminates. 4569: 4570: To make the initialization and termination functions work, the compiler 4571: must output something in the assembler code to cause those functions to 4572: be called at the appropriate time. When you port the compiler to a new 1.1.1.4 root 4573: system, you need to specify how to do this. 1.1 root 4574: 1.1.1.4 root 4575: There are two major ways that GCC currently supports the execution of 4576: initialization and termination functions. Each way has two variants. 4577: Much of the structure is common to all four variations. 4578: 4579: @findex __CTOR_LIST__ 4580: @findex __DTOR_LIST__ 4581: The linker must build two lists of these functions---a list of 4582: initialization functions, called @code{__CTOR_LIST__}, and a list of 4583: termination functions, called @code{__DTOR_LIST__}. 4584: 4585: Each list always begins with an ignored function pointer (which may hold 4586: 0, @minus{}1, or a count of the function pointers after it, depending on 4587: the environment). This is followed by a series of zero or more function 4588: pointers to constructors (or destructors), followed by a function 4589: pointer containing zero. 4590: 4591: Depending on the operating system and its executable file format, either 4592: @file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 4593: time and exit time. Constructors are called in forward order of the 4594: list; destructors in reverse order. 4595: 4596: The best way to handle static constructors works only for object file 4597: formats which provide arbitrarily-named sections. A section is set 4598: aside for a list of constructors, and another for a list of destructors. 4599: Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 4600: object file that defines an initialization function also puts a word in 4601: the constructor section to point to that function. The linker 4602: accumulates all these words into one contiguous @samp{.ctors} section. 4603: Termination functions are handled similarly. 4604: 4605: To use this method, you need appropriate definitions of the macros 4606: @code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR}. Usually 4607: you can get them by including @file{svr4.h}. 4608: 4609: When arbitrary sections are available, there are two variants, depending 4610: upon how the code in @file{crtstuff.c} is called. On systems that 4611: support an @dfn{init} section which is executed at program startup, 4612: parts of @file{crtstuff.c} are compiled into that section. The 4613: program is linked by the @code{gcc} driver like this: 4614: 4615: @example 4616: ld -o @var{output_file} crtbegin.o @dots{} crtend.o -lgcc 4617: @end example 4618: 4619: The head of a function (@code{__do_global_ctors}) appears in the init 4620: section of @file{crtbegin.o}; the remainder of the function appears in 4621: the init section of @file{crtend.o}. The linker will pull these two 4622: parts of the section together, making a whole function. If any of the 4623: user's object files linked into the middle of it contribute code, then that 4624: code will be executed as part of the body of @code{__do_global_ctors}. 4625: 4626: To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 4627: macro properly. 4628: 4629: If no init section is available, do not define 4630: @code{INIT_SECTION_ASM_OP}. Then @code{__do_global_ctors} is built into 4631: the text section like all other functions, and resides in 4632: @file{libgcc.a}. When GCC compiles any function called @code{main}, it 4633: inserts a procedure call to @code{__main} as the first executable code 4634: after the function prologue. The @code{__main} function, also defined 4635: in @file{libgcc2.c}, simply calls @file{__do_global_ctors}. 4636: 4637: In file formats that don't support arbitrary sections, there are again 4638: two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 4639: and an `a.out' format must be used. In this case, 4640: @code{ASM_OUTPUT_CONSTRUCTOR} is defined to produce a @code{.stabs} 4641: entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 4642: and with the address of the void function containing the initialization 4643: code as its value. The GNU linker recognizes this as a request to add 4644: the value to a ``set''; the values are accumulated, and are eventually 4645: placed in the executable as a vector in the format described above, with 4646: a leading (ignored) count and a trailing zero element. 4647: @code{ASM_OUTPUT_DESTRUCTOR} is handled similarly. Since no init 4648: section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 4649: the compilation of @code{main} to call @code{__main} as above, starting 4650: the initialization process. 4651: 4652: The last variant uses neither arbitrary sections nor the GNU linker. 4653: This is preferable when you want to do dynamic linking and when using 4654: file formats which the GNU linker does not support, such as `ECOFF'. In 4655: this case, @code{ASM_OUTPUT_CONSTRUCTOR} does not produce an 4656: @code{N_SETT} symbol; initialization and termination functions are 4657: recognized simply by their names. This requires an extra program in the 4658: linkage step, called @code{collect2}. This program pretends to be the 4659: linker, for use with GNU CC; it does its job by running the ordinary 4660: linker, but also arranges to include the vectors of initialization and 4661: termination functions. These functions are called via @code{__main} as 4662: described above. 4663: 4664: Choosing among these configuration options has been simplified by a set 4665: of operating-system-dependent files in the @file{config} subdirectory. 4666: These files define all of the relevant parameters. Usually it is 4667: sufficient to include one into your specific machine-dependent 4668: configuration file. These files are: 4669: 4670: @table @file 4671: @item aoutos.h 4672: For operating systems using the `a.out' format. 4673: 4674: @item next.h 4675: For operating systems using the `MachO' format. 4676: 4677: @item svr3.h 4678: For System V Release 3 and similar systems using `COFF' format. 4679: 4680: @item svr4.h 4681: For System V Release 4 and similar systems using `ELF' format. 4682: 4683: @item vms.h 4684: For the VMS operating system. 4685: @end table 4686: 4687: @ifinfo 4688: The following section describes the specific macros that control and 4689: customize the handling of initialization and termination functions. 4690: @end ifinfo 4691: 4692: @node Macros for Initialization 4693: @subsection Macros Controlling Initialization Routines 4694: 4695: Here are the macros that control how the compiler handles initialization 4696: and termination functions: 1.1 root 4697: 4698: @table @code 1.1.1.4 root 4699: @findex INIT_SECTION_ASM_OP 4700: @item INIT_SECTION_ASM_OP 4701: If defined, a C string constant for the assembler operation to identify 4702: the following data as initialization code. If not defined, GNU CC will 4703: assume such a section does not exist. When you are using special 4704: sections for initialization and termination functions, this macro also 4705: controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to run the 4706: initialization functions. 4707: 1.1 root 4708: @item ASM_OUTPUT_CONSTRUCTOR (@var{stream}, @var{name}) 4709: @findex ASM_OUTPUT_CONSTRUCTOR 4710: Define this macro as a C statement to output on the stream @var{stream} 4711: the assembler code to arrange to call the function named @var{name} at 4712: initialization time. 4713: 4714: Assume that @var{name} is the name of a C function generated 4715: automatically by the compiler. This function takes no arguments. Use 4716: the function @code{assemble_name} to output the name @var{name}; this 4717: performs any system-specific syntactic transformations such as adding an 4718: underscore. 4719: 4720: If you don't define this macro, nothing special is output to arrange to 4721: call the function. This is correct when the function will be called in 1.1.1.4 root 4722: some other manner---for example, by means of the @code{collect2} program, 1.1 root 4723: which looks through the symbol table to find these functions by their 1.1.1.5 ! root 4724: names. 1.1 root 4725: 4726: @item ASM_OUTPUT_DESTRUCTOR (@var{stream}, @var{name}) 4727: @findex ASM_OUTPUT_DESTRUCTOR 4728: This is like @code{ASM_OUTPUT_CONSTRUCTOR} but used for termination 4729: functions rather than initialization functions. 4730: @end table 4731: 1.1.1.3 root 4732: If your system uses @code{collect2} as the means of processing 4733: constructors, then that program normally uses @code{nm} to scan an 4734: object file for constructor functions to be called. On certain kinds of 4735: systems, you can define these macros to make @code{collect2} work faster 4736: (and, in some cases, make it work at all): 4737: 4738: @table @code 4739: @findex OBJECT_FORMAT_COFF 4740: @item OBJECT_FORMAT_COFF 4741: Define this macro if the system uses COFF (Common Object File Format) 4742: object files, so that @code{collect2} can assume this format and scan 4743: object files directly for dynamic constructor/destructor functions. 4744: 4745: @findex OBJECT_FORMAT_ROSE 4746: @item OBJECT_FORMAT_ROSE 4747: Define this macro if the system uses ROSE format object files, so that 4748: @code{collect2} can assume this format and scan object files directly 4749: for dynamic constructor/destructor functions. 4750: @end table 4751: 4752: These macros are effective only in a native compiler; @code{collect2} as 4753: part of a cross compiler always uses @code{nm}. 4754: 4755: @table @code 4756: @findex REAL_NM_FILE_NAME 4757: @item REAL_NM_FILE_NAME 4758: Define this macro as a C string constant containing the file name to use 4759: to execute @code{nm}. The default is to search the path normally for 4760: @code{nm}. 4761: @end table 4762: 1.1.1.2 root 4763: @node Instruction Output 1.1 root 4764: @subsection Output of Assembler Instructions 4765: 4766: @table @code 4767: @findex REGISTER_NAMES 4768: @item REGISTER_NAMES 4769: A C initializer containing the assembler's names for the machine 4770: registers, each one as a C string constant. This is what translates 4771: register numbers in the compiler into assembler language. 4772: 4773: @findex ADDITIONAL_REGISTER_NAMES 4774: @item ADDITIONAL_REGISTER_NAMES 4775: If defined, a C initializer for an array of structures containing a name 4776: and a register number. This macro defines additional names for hard 4777: registers, thus allowing the @code{asm} option in declarations to refer 4778: to registers using alternate names. 4779: 4780: @findex ASM_OUTPUT_OPCODE 4781: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 4782: Define this macro if you are using an unusual assembler that 4783: requires different names for the machine instructions. 4784: 4785: The definition is a C statement or statements which output an 4786: assembler instruction opcode to the stdio stream @var{stream}. The 4787: macro-operand @var{ptr} is a variable of type @code{char *} which 4788: points to the opcode name in its ``internal'' form---the form that is 4789: written in the machine description. The definition should output the 4790: opcode name to @var{stream}, performing any translation you desire, and 4791: increment the variable @var{ptr} to point at the end of the opcode 4792: so that it will not be output twice. 4793: 4794: In fact, your macro definition may process less than the entire opcode 4795: name, or more than the opcode name; but if you want to process text 4796: that includes @samp{%}-sequences to substitute operands, you must take 4797: care of the substitution yourself. Just be sure to increment 4798: @var{ptr} over whatever text should not be output normally. 4799: 4800: @findex recog_operand 4801: If you need to look at the operand values, they can be found as the 4802: elements of @code{recog_operand}. 4803: 4804: If the macro definition does nothing, the instruction is output 4805: in the usual way. 4806: 4807: @findex FINAL_PRESCAN_INSN 4808: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 4809: If defined, a C statement to be executed just prior to the output of 4810: assembler code for @var{insn}, to modify the extracted operands so 4811: they will be output differently. 4812: 4813: Here the argument @var{opvec} is the vector containing the operands 4814: extracted from @var{insn}, and @var{noperands} is the number of 4815: elements of the vector which contain meaningful data for this insn. 4816: The contents of this vector are what will be used to convert the insn 4817: template into assembler code, so you can change the assembler output 4818: by changing the contents of the vector. 4819: 4820: This macro is useful when various assembler syntaxes share a single 4821: file of instruction patterns; by defining this macro differently, you 4822: can cause a large class of instructions to be output differently (such 4823: as with rearranged operands). Naturally, variations in assembler 4824: syntax affecting individual insn patterns ought to be handled by 4825: writing conditional output routines in those patterns. 4826: 4827: If this macro is not defined, it is equivalent to a null statement. 4828: 4829: @findex PRINT_OPERAND 4830: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 4831: A C compound statement to output to stdio stream @var{stream} the 4832: assembler syntax for an instruction operand @var{x}. @var{x} is an 4833: RTL expression. 4834: 4835: @var{code} is a value that can be used to specify one of several ways 4836: of printing the operand. It is used when identical operands must be 4837: printed differently depending on the context. @var{code} comes from 4838: the @samp{%} specification that was used to request printing of the 4839: operand. If the specification was just @samp{%@var{digit}} then 4840: @var{code} is 0; if the specification was @samp{%@var{ltr} 4841: @var{digit}} then @var{code} is the ASCII code for @var{ltr}. 4842: 4843: @findex reg_names 4844: If @var{x} is a register, this macro should print the register's name. 4845: The names can be found in an array @code{reg_names} whose type is 4846: @code{char *[]}. @code{reg_names} is initialized from 4847: @code{REGISTER_NAMES}. 4848: 4849: When the machine description has a specification @samp{%@var{punct}} 4850: (a @samp{%} followed by a punctuation character), this macro is called 4851: with a null pointer for @var{x} and the punctuation character for 4852: @var{code}. 4853: 4854: @findex PRINT_OPERAND_PUNCT_VALID_P 4855: @item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 4856: A C expression which evaluates to true if @var{code} is a valid 4857: punctuation character for use in the @code{PRINT_OPERAND} macro. If 4858: @code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 4859: punctuation characters (except for the standard one, @samp{%}) are used 4860: in this way. 4861: 4862: @findex PRINT_OPERAND_ADDRESS 4863: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 4864: A C compound statement to output to stdio stream @var{stream} the 4865: assembler syntax for an instruction operand that is a memory reference 4866: whose address is @var{x}. @var{x} is an RTL expression. 4867: 4868: @cindex @code{ENCODE_SECTION_INFO} usage 4869: On some machines, the syntax for a symbolic address depends on the 4870: section that the address refers to. On these machines, define the macro 4871: @code{ENCODE_SECTION_INFO} to store the information into the 4872: @code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 4873: 4874: @findex DBR_OUTPUT_SEQEND 4875: @findex dbr_sequence_length 4876: @item DBR_OUTPUT_SEQEND(@var{file}) 4877: A C statement, to be executed after all slot-filler instructions have 4878: been output. If necessary, call @code{dbr_sequence_length} to 4879: determine the number of slots filled in a sequence (zero if not 4880: currently outputting a sequence), to decide how many no-ops to output, 4881: or whatever. 4882: 4883: Don't define this macro if it has nothing to do, but it is helpful in 4884: reading assembly output if the extent of the delay sequence is made 4885: explicit (e.g. with white space). 4886: 4887: @findex final_sequence 4888: Note that output routines for instructions with delay slots must be 4889: prepared to deal with not being output as part of a sequence (i.e. 4890: when the scheduling pass is not run, or when no slot fillers could be 4891: found.) The variable @code{final_sequence} is null when not 4892: processing a sequence, otherwise it contains the @code{sequence} rtx 4893: being output. 4894: 4895: @findex REGISTER_PREFIX 4896: @findex LOCAL_LABEL_PREFIX 4897: @findex USER_LABEL_PREFIX 4898: @findex IMMEDIATE_PREFIX 4899: @findex asm_fprintf 4900: @item REGISTER_PREFIX 4901: @itemx LOCAL_LABEL_PREFIX 4902: @itemx USER_LABEL_PREFIX 4903: @itemx IMMEDIATE_PREFIX 4904: If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 4905: @samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 4906: @file{final.c}). These are useful when a single @file{md} file must 4907: support multiple assembler formats. In that case, the various @file{tm.h} 4908: files can define these macros differently. 4909: 4910: @findex ASM_OUTPUT_REG_PUSH 4911: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 4912: A C expression to output to @var{stream} some assembler code 4913: which will push hard register number @var{regno} onto the stack. 4914: The code need not be optimal, since this macro is used only when 4915: profiling. 4916: 4917: @findex ASM_OUTPUT_REG_POP 4918: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 4919: A C expression to output to @var{stream} some assembler code 4920: which will pop hard register number @var{regno} off of the stack. 4921: The code need not be optimal, since this macro is used only when 4922: profiling. 4923: @end table 4924: 1.1.1.2 root 4925: @node Dispatch Tables 1.1 root 4926: @subsection Output of Dispatch Tables 4927: 4928: @table @code 4929: @cindex dispatch table 4930: @findex ASM_OUTPUT_ADDR_DIFF_ELT 4931: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel}) 4932: This macro should be provided on machines where the addresses 4933: in a dispatch table are relative to the table's own address. 4934: 4935: The definition should be a C statement to output to the stdio stream 4936: @var{stream} an assembler pseudo-instruction to generate a difference 4937: between two labels. @var{value} and @var{rel} are the numbers of two 4938: internal labels. The definitions of these labels are output using 4939: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 4940: way here. For example, 4941: 4942: @example 4943: fprintf (@var{stream}, "\t.word L%d-L%d\n", 4944: @var{value}, @var{rel}) 4945: @end example 4946: 4947: @findex ASM_OUTPUT_ADDR_VEC_ELT 4948: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 4949: This macro should be provided on machines where the addresses 4950: in a dispatch table are absolute. 4951: 4952: The definition should be a C statement to output to the stdio stream 4953: @var{stream} an assembler pseudo-instruction to generate a reference to 4954: a label. @var{value} is the number of an internal label whose 4955: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 4956: For example, 4957: 4958: @example 4959: fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 4960: @end example 4961: 4962: @findex ASM_OUTPUT_CASE_LABEL 4963: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 4964: Define this if the label before a jump-table needs to be output 4965: specially. The first three arguments are the same as for 4966: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 4967: jump-table which follows (a @code{jump_insn} containing an 4968: @code{addr_vec} or @code{addr_diff_vec}). 4969: 4970: This feature is used on system V to output a @code{swbeg} statement 4971: for the table. 4972: 4973: If this macro is not defined, these labels are output with 4974: @code{ASM_OUTPUT_INTERNAL_LABEL}. 4975: 4976: @findex ASM_OUTPUT_CASE_END 4977: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 4978: Define this if something special must be output at the end of a 4979: jump-table. The definition should be a C statement to be executed 4980: after the assembler code for the table is written. It should write 4981: the appropriate code to stdio stream @var{stream}. The argument 4982: @var{table} is the jump-table insn, and @var{num} is the label-number 4983: of the preceding label. 4984: 4985: If this macro is not defined, nothing special is output at the end of 4986: the jump-table. 4987: @end table 4988: 1.1.1.2 root 4989: @node Alignment Output 1.1 root 4990: @subsection Assembler Commands for Alignment 4991: 4992: @table @code 4993: @findex ASM_OUTPUT_ALIGN_CODE 4994: @item ASM_OUTPUT_ALIGN_CODE (@var{file}) 4995: A C expression to output text to align the location counter in the way 4996: that is desirable at a point in the code that is reached only by 4997: jumping. 4998: 4999: This macro need not be defined if you don't want any special alignment 5000: to be done at such a time. Most machine descriptions do not currently 5001: define the macro. 5002: 5003: @findex ASM_OUTPUT_LOOP_ALIGN 5004: @item ASM_OUTPUT_LOOP_ALIGN (@var{file}) 5005: A C expression to output text to align the location counter in the way 5006: that is desirable at the beginning of a loop. 5007: 5008: This macro need not be defined if you don't want any special alignment 5009: to be done at such a time. Most machine descriptions do not currently 5010: define the macro. 5011: 5012: @findex ASM_OUTPUT_SKIP 5013: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 5014: A C statement to output to the stdio stream @var{stream} an assembler 5015: instruction to advance the location counter by @var{nbytes} bytes. 5016: Those bytes should be zero when loaded. @var{nbytes} will be a C 5017: expression of type @code{int}. 5018: 5019: @findex ASM_NO_SKIP_IN_TEXT 5020: @item ASM_NO_SKIP_IN_TEXT 5021: Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 5022: text section because it fails put zeros in the bytes that are skipped. 5023: This is true on many Unix systems, where the pseudo--op to skip bytes 5024: produces no-op instructions rather than zeros when used in the text 5025: section. 5026: 5027: @findex ASM_OUTPUT_ALIGN 5028: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 5029: A C statement to output to the stdio stream @var{stream} an assembler 5030: command to advance the location counter to a multiple of 2 to the 5031: @var{power} bytes. @var{power} will be a C expression of type @code{int}. 5032: @end table 5033: 1.1.1.2 root 5034: @node Debugging Info 1.1 root 5035: @section Controlling Debugging Information Format 1.1.1.5 ! root 5036: @c this should have some text in here.... --mew 10feb93 1.1 root 5037: 1.1.1.3 root 5038: @menu 5039: * All Debuggers:: Macros that affect all debugging formats uniformly. 5040: * DBX Options:: Macros enabling specific options in DBX format. 5041: * DBX Hooks:: Hook macros for varying DBX format. 5042: * File Names and DBX:: Macros controlling output of file names in DBX format. 5043: * SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 5044: @end menu 5045: 5046: @node All Debuggers 5047: @subsection Macros Affecting All Debugging Formats 5048: 1.1 root 5049: @table @code 5050: @findex DBX_REGISTER_NUMBER 5051: @item DBX_REGISTER_NUMBER (@var{regno}) 5052: A C expression that returns the DBX register number for the compiler 5053: register number @var{regno}. In simple cases, the value of this 5054: expression may be @var{regno} itself. But sometimes there are some 5055: registers that the compiler knows about and DBX does not, or vice 5056: versa. In such cases, some register may need to have one number in 5057: the compiler and another for DBX. 5058: 5059: If two registers have consecutive numbers inside GNU CC, and they can be 5060: used as a pair to hold a multiword value, then they @emph{must} have 5061: consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 5062: Otherwise, debuggers will be unable to access such a pair, because they 5063: expect register pairs to be consecutive in their own numbering scheme. 5064: 5065: If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 5066: does not preserve register pairs, then what you must do instead is 5067: redefine the actual register numbering scheme. 5068: 1.1.1.3 root 5069: @findex DEBUGGER_AUTO_OFFSET 5070: @item DEBUGGER_AUTO_OFFSET (@var{x}) 5071: A C expression that returns the integer offset value for an automatic 5072: variable having address @var{x} (an RTL expression). The default 5073: computation assumes that @var{x} is based on the frame-pointer and 5074: gives the offset from the frame-pointer. This is required for targets 5075: that produce debugging output for DBX or COFF-style debugging output 5076: for SDB and allow the frame-pointer to be eliminated when the 5077: @samp{-g} options is used. 5078: 5079: @findex DEBUGGER_ARG_OFFSET 5080: @item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 5081: A C expression that returns the integer offset value for an argument 5082: having address @var{x} (an RTL expression). The nominal offset is 5083: @var{offset}. 5084: @end table 5085: 5086: @node DBX Options 5087: @subsection Specific Options for DBX Output 5088: 5089: @table @code 1.1 root 5090: @findex DBX_DEBUGGING_INFO 5091: @item DBX_DEBUGGING_INFO 5092: Define this macro if GNU CC should produce debugging output for DBX 5093: in response to the @samp{-g} option. 5094: 1.1.1.2 root 5095: @findex XCOFF_DEBUGGING_INFO 5096: @item XCOFF_DEBUGGING_INFO 5097: Define this macro if GNU CC should produce XCOFF format debugging output 1.1.1.3 root 5098: in response to the @samp{-g} option. This is a variant of DBX format. 1.1.1.2 root 5099: 1.1 root 5100: @findex DEFAULT_GDB_EXTENSIONS 5101: @item DEFAULT_GDB_EXTENSIONS 5102: Define this macro to control whether GNU CC should by default generate 5103: GDB's extended version of DBX debugging information (assuming DBX-format 5104: debugging information is enabled at all). If you don't define the 1.1.1.3 root 5105: macro, the default is 1: always generate the extended information 5106: if there is any occasion to. 1.1 root 5107: 5108: @findex DEBUG_SYMS_TEXT 5109: @item DEBUG_SYMS_TEXT 5110: Define this macro if all @code{.stabs} commands should be output while 5111: in the text section. 5112: 5113: @findex ASM_STABS_OP 5114: @item ASM_STABS_OP 5115: A C string constant naming the assembler pseudo op to use instead of 5116: @code{.stabs} to define an ordinary debugging symbol. If you don't 5117: define this macro, @code{.stabs} is used. This macro applies only to 5118: DBX debugging information format. 5119: 5120: @findex ASM_STABD_OP 5121: @item ASM_STABD_OP 5122: A C string constant naming the assembler pseudo op to use instead of 5123: @code{.stabd} to define a debugging symbol whose value is the current 5124: location. If you don't define this macro, @code{.stabd} is used. 5125: This macro applies only to DBX debugging information format. 5126: 5127: @findex ASM_STABN_OP 5128: @item ASM_STABN_OP 5129: A C string constant naming the assembler pseudo op to use instead of 5130: @code{.stabn} to define a debugging symbol with no name. If you don't 5131: define this macro, @code{.stabn} is used. This macro applies only to 5132: DBX debugging information format. 5133: 5134: @findex DBX_NO_XREFS 5135: @item DBX_NO_XREFS 5136: Define this macro if DBX on your system does not support the construct 5137: @samp{xs@var{tagname}}. On some systems, this construct is used to 5138: describe a forward reference to a structure named @var{tagname}. 5139: On other systems, this construct is not supported at all. 5140: 5141: @findex DBX_CONTIN_LENGTH 5142: @item DBX_CONTIN_LENGTH 5143: A symbol name in DBX-format debugging information is normally 5144: continued (split into two separate @code{.stabs} directives) when it 5145: exceeds a certain length (by default, 80 characters). On some 5146: operating systems, DBX requires this splitting; on others, splitting 5147: must not be done. You can inhibit splitting by defining this macro 5148: with the value zero. You can override the default splitting-length by 5149: defining this macro as an expression for the length you desire. 5150: 5151: @findex DBX_CONTIN_CHAR 5152: @item DBX_CONTIN_CHAR 5153: Normally continuation is indicated by adding a @samp{\} character to 5154: the end of a @code{.stabs} string when a continuation follows. To use 5155: a different character instead, define this macro as a character 5156: constant for the character you want to use. Do not define this macro 5157: if backslash is correct for your system. 5158: 5159: @findex DBX_STATIC_STAB_DATA_SECTION 5160: @item DBX_STATIC_STAB_DATA_SECTION 5161: Define this macro if it is necessary to go to the data section before 5162: outputting the @samp{.stabs} pseudo-op for a non-global static 5163: variable. 5164: 1.1.1.3 root 5165: @findex DBX_TYPE_DECL_STABS_CODE 5166: @item DBX_TYPE_DECL_STABS_CODE 5167: The value to use in the ``code'' field of the @code{.stabs} directive 5168: for a typedef. The default is @code{N_LSYM}. 5169: 5170: @findex DBX_STATIC_CONST_VAR_CODE 5171: @item DBX_STATIC_CONST_VAR_CODE 5172: The value to use in the ``code'' field of the @code{.stabs} directive 5173: for a static variable located in the text section. DBX format does not 5174: provide any ``right'' way to do this. The default is @code{N_FUN}. 5175: 5176: @findex DBX_REGPARM_STABS_CODE 5177: @item DBX_REGPARM_STABS_CODE 5178: The value to use in the ``code'' field of the @code{.stabs} directive 5179: for a parameter passed in registers. DBX format does not provide any 5180: ``right'' way to do this. The default is @code{N_RSYM}. 5181: 5182: @findex DBX_REGPARM_STABS_LETTER 5183: @item DBX_REGPARM_STABS_LETTER 5184: The letter to use in DBX symbol data to identify a symbol as a parameter 5185: passed in registers. DBX format does not customarily provide any way to 5186: do this. The default is @code{'P'}. 5187: 5188: @findex DBX_MEMPARM_STABS_LETTER 5189: @item DBX_MEMPARM_STABS_LETTER 5190: The letter to use in DBX symbol data to identify a symbol as a stack 5191: parameter. The default is @code{'p'}. 1.1 root 5192: 5193: @findex DBX_FUNCTION_FIRST 5194: @item DBX_FUNCTION_FIRST 5195: Define this macro if the DBX information for a function and its 5196: arguments should precede the assembler code for the function. Normally, 5197: in DBX format, the debugging information entirely follows the assembler 5198: code. 5199: 1.1.1.3 root 5200: @findex DBX_LBRAC_FIRST 5201: @item DBX_LBRAC_FIRST 5202: Define this macro if the @code{N_LBRAC} symbol for a block should 5203: precede the debugging information for variables and functions defined in 5204: that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 5205: first. 5206: @end table 5207: 5208: @node DBX Hooks 5209: @subsection Open-Ended Hooks for DBX Format 5210: 5211: @table @code 5212: @findex DBX_OUTPUT_LBRAC 5213: @item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 5214: Define this macro to say how to output to @var{stream} the debugging 5215: information for the start of a scope level for variable names. The 5216: argument @var{name} is the name of an assembler symbol (for use with 5217: @code{assemble_name}) whose value is the address where the scope begins. 5218: 5219: @findex DBX_OUTPUT_RBRAC 5220: @item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 5221: Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 5222: 5223: @findex DBX_OUTPUT_ENUM 5224: @item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 5225: Define this macro if the target machine requires special handling to 5226: output an enumeration type. The definition should be a C statement 5227: (sans semicolon) to output the appropriate information to @var{stream} 5228: for the type @var{type}. 5229: 1.1 root 5230: @findex DBX_OUTPUT_FUNCTION_END 5231: @item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 5232: Define this macro if the target machine requires special output at the 5233: end of the debugging information for a function. The definition should 5234: be a C statement (sans semicolon) to output the appropriate information 5235: to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 5236: the function. 5237: 5238: @findex DBX_OUTPUT_STANDARD_TYPES 5239: @item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 5240: Define this macro if you need to control the order of output of the 5241: standard data types at the beginning of compilation. The argument 5242: @var{syms} is a @code{tree} which is a chain of all the predefined 5243: global symbols, including names of data types. 5244: 5245: Normally, DBX output starts with definitions of the types for integers 5246: and characters, followed by all the other predefined types of the 5247: particular language in no particular order. 5248: 5249: On some machines, it is necessary to output different particular types 5250: first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 5251: those symbols in the necessary order. Any predefined types that you 5252: don't explicitly output will be output afterward in no particular order. 5253: 5254: Be careful not to define this macro so that it works only for C. There 5255: are no global variables to access most of the built-in types, because 5256: another language may have another set of types. The way to output a 5257: particular type is to look through @var{syms} to see if you can find it. 5258: Here is an example: 5259: 1.1.1.5 ! root 5260: @smallexample 1.1 root 5261: @{ 5262: tree decl; 5263: for (decl = syms; decl; decl = TREE_CHAIN (decl)) 1.1.1.5 ! root 5264: if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), ! 5265: "long int")) 1.1 root 5266: dbxout_symbol (decl); 5267: @dots{} 5268: @} 1.1.1.5 ! root 5269: @end smallexample 1.1 root 5270: 5271: @noindent 5272: This does nothing if the expected type does not exist. 5273: 1.1.1.5 ! root 5274: See the function @code{init_decl_processing} in @file{c-decl.c} to find ! 5275: the names to use for all the built-in C types. 1.1 root 5276: 1.1.1.3 root 5277: Here is another way of finding a particular type: 5278: 1.1.1.5 ! root 5279: @c this is still overfull. --mew 10feb93 ! 5280: @smallexample 1.1.1.3 root 5281: @{ 5282: tree decl; 5283: for (decl = syms; decl; decl = TREE_CHAIN (decl)) 5284: if (TREE_CODE (decl) == TYPE_DECL 1.1.1.5 ! root 5285: && (TREE_CODE (TREE_TYPE (decl)) ! 5286: == INTEGER_CST) 1.1.1.3 root 5287: && TYPE_PRECISION (TREE_TYPE (decl)) == 16 5288: && TYPE_UNSIGNED (TREE_TYPE (decl))) 5289: /* @r{This must be @code{unsigned short}.} */ 5290: dbxout_symbol (decl); 5291: @dots{} 5292: @} 1.1.1.5 ! root 5293: @end smallexample 1.1.1.3 root 5294: @end table 5295: 5296: @node File Names and DBX 5297: @subsection File Names in DBX Format 5298: 5299: @table @code 5300: @findex DBX_WORKING_DIRECTORY 5301: @item DBX_WORKING_DIRECTORY 5302: Define this if DBX wants to have the current directory recorded in each 5303: object file. 5304: 5305: Note that the working directory is always recorded if GDB extensions are 5306: enabled. 5307: 1.1 root 5308: @findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 5309: @item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 5310: A C statement to output DBX debugging information to the stdio stream 5311: @var{stream} which indicates that file @var{name} is the main source 5312: file---the file specified as the input file for compilation. 5313: This macro is called only once, at the beginning of compilation. 5314: 5315: This macro need not be defined if the standard form of output 5316: for DBX debugging information is appropriate. 5317: 5318: @findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 5319: @item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 5320: A C statement to output DBX debugging information to the stdio stream 5321: @var{stream} which indicates that the current directory during 5322: compilation is named @var{name}. 5323: 5324: This macro need not be defined if the standard form of output 5325: for DBX debugging information is appropriate. 5326: 5327: @findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 5328: @item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 5329: A C statement to output DBX debugging information at the end of 5330: compilation of the main source file @var{name}. 5331: 5332: If you don't define this macro, nothing special is output at the end 5333: of compilation, which is correct for most machines. 5334: 5335: @findex DBX_OUTPUT_SOURCE_FILENAME 5336: @item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 5337: A C statement to output DBX debugging information to the stdio stream 5338: @var{stream} which indicates that file @var{name} is the current source 5339: file. This output is generated each time input shifts to a different 5340: source file as a result of @samp{#include}, the end of an included file, 5341: or a @samp{#line} command. 5342: 5343: This macro need not be defined if the standard form of output 5344: for DBX debugging information is appropriate. 5345: @end table 5346: 1.1.1.3 root 5347: @node SDB and DWARF 5348: @subsection Macros for SDB and DWARF Output 5349: 5350: @table @code 5351: @findex SDB_DEBUGGING_INFO 5352: @item SDB_DEBUGGING_INFO 5353: Define this macro if GNU CC should produce COFF-style debugging output 5354: for SDB in response to the @samp{-g} option. 5355: 5356: @findex DWARF_DEBUGGING_INFO 5357: @item DWARF_DEBUGGING_INFO 5358: Define this macro if GNU CC should produce dwarf format debugging output 5359: in response to the @samp{-g} option. 5360: 5361: @findex PUT_SDB_@dots{} 5362: @item PUT_SDB_@dots{} 5363: Define these macros to override the assembler syntax for the special 5364: SDB assembler directives. See @file{sdbout.c} for a list of these 5365: macros and their arguments. If the standard syntax is used, you need 5366: not define them yourself. 5367: 5368: @findex SDB_DELIM 5369: @item SDB_DELIM 5370: Some assemblers do not support a semicolon as a delimiter, even between 5371: SDB assembler directives. In that case, define this macro to be the 5372: delimiter to use (usually @samp{\n}). It is not necessary to define 5373: a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 5374: required. 5375: 5376: @findex SDB_GENERATE_FAKE 5377: @item SDB_GENERATE_FAKE 5378: Define this macro to override the usual method of constructing a dummy 5379: name for anonymous structure and union types. See @file{sdbout.c} for 5380: more information. 5381: 5382: @findex SDB_ALLOW_UNKNOWN_REFERENCES 5383: @item SDB_ALLOW_UNKNOWN_REFERENCES 5384: Define this macro to allow references to unknown structure, 5385: union, or enumeration tags to be emitted. Standard COFF does not 5386: allow handling of unknown references, MIPS ECOFF has support for 5387: it. 5388: 5389: @findex SDB_ALLOW_FORWARD_REFERENCES 5390: @item SDB_ALLOW_FORWARD_REFERENCES 5391: Define this macro to allow references to structure, union, or 5392: enumeration tags that have not yet been seen to be handled. Some 5393: assemblers choke if forward tags are used, while some require it. 5394: @end table 5395: 1.1.1.2 root 5396: @node Cross-compilation 1.1.1.5 ! root 5397: @section Cross Compilation and Floating Point 1.1 root 5398: @cindex cross compilation and floating point 1.1.1.5 ! root 5399: @cindex floating point and cross compilation 1.1 root 5400: 5401: While all modern machines use 2's complement representation for integers, 5402: there are a variety of representations for floating point numbers. This 5403: means that in a cross-compiler the representation of floating point numbers 5404: in the compiled program may be different from that used in the machine 5405: doing the compilation. 5406: 5407: @findex atof 5408: Because different representation systems may offer different amounts of 5409: range and precision, the cross compiler cannot safely use the host 5410: machine's floating point arithmetic. Therefore, floating point constants 5411: must be represented in the target machine's format. This means that the 5412: cross compiler cannot use @code{atof} to parse a floating point constant; 5413: it must have its own special routine to use instead. Also, constant 5414: folding must emulate the target machine's arithmetic (or must not be done 5415: at all). 5416: 5417: The macros in the following table should be defined only if you are cross 5418: compiling between different floating point formats. 5419: 1.1.1.5 ! root 5420: Otherwise, don't define them. Then default definitions will be set up which 1.1 root 5421: use @code{double} as the data type, @code{==} to test for equality, etc. 5422: 5423: You don't need to worry about how many times you use an operand of any 5424: of these macros. The compiler never uses operands which have side effects. 5425: 5426: @table @code 5427: @findex REAL_VALUE_TYPE 5428: @item REAL_VALUE_TYPE 5429: A macro for the C data type to be used to hold a floating point value 5430: in the target machine's format. Typically this would be a 5431: @code{struct} containing an array of @code{int}. 5432: 5433: @findex REAL_VALUES_EQUAL 5434: @item REAL_VALUES_EQUAL (@var{x}, @var{y}) 5435: A macro for a C expression which compares for equality the two values, 5436: @var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}. 5437: 5438: @findex REAL_VALUES_LESS 5439: @item REAL_VALUES_LESS (@var{x}, @var{y}) 5440: A macro for a C expression which tests whether @var{x} is less than 5441: @var{y}, both values being of type @code{REAL_VALUE_TYPE} and 5442: interpreted as floating point numbers in the target machine's 5443: representation. 5444: 5445: @findex REAL_VALUE_LDEXP 5446: @findex ldexp 5447: @item REAL_VALUE_LDEXP (@var{x}, @var{scale}) 5448: A macro for a C expression which performs the standard library 5449: function @code{ldexp}, but using the target machine's floating point 5450: representation. Both @var{x} and the value of the expression have 5451: type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an 5452: integer. 5453: 5454: @findex REAL_VALUE_FIX 5455: @item REAL_VALUE_FIX (@var{x}) 5456: A macro whose definition is a C expression to convert the target-machine 5457: floating point value @var{x} to a signed integer. @var{x} has type 5458: @code{REAL_VALUE_TYPE}. 5459: 5460: @findex REAL_VALUE_UNSIGNED_FIX 5461: @item REAL_VALUE_UNSIGNED_FIX (@var{x}) 5462: A macro whose definition is a C expression to convert the target-machine 5463: floating point value @var{x} to an unsigned integer. @var{x} has type 5464: @code{REAL_VALUE_TYPE}. 5465: 1.1.1.5 ! root 5466: @findex REAL_VALUE_RNDZINT ! 5467: @item REAL_VALUE_RNDZINT (@var{x}) ! 5468: A macro whose definition is a C expression to round the target-machine ! 5469: floating point value @var{x} towards zero to an integer value (but still ! 5470: as a floating point number). @var{x} has type @code{REAL_VALUE_TYPE}, ! 5471: and so does the value. ! 5472: ! 5473: @findex REAL_VALUE_UNSIGNED_RNDZINT ! 5474: @item REAL_VALUE_UNSIGNED_RNDZINT (@var{x}) ! 5475: A macro whose definition is a C expression to round the target-machine ! 5476: floating point value @var{x} towards zero to an unsigned integer value ! 5477: (but still represented as a floating point number). @var{x} has type ! 5478: @code{REAL_VALUE_TYPE}, and so does the value. 1.1 root 5479: 5480: @findex REAL_VALUE_ATOF 1.1.1.5 ! root 5481: @item REAL_VALUE_ATOF (@var{string}, @var{mode}) ! 5482: A macro for a C expression which converts @var{string}, an expression of ! 5483: type @code{char *}, into a floating point number in the target machine's ! 5484: representation for mode @var{mode}. The value has type ! 5485: @code{REAL_VALUE_TYPE}. 1.1 root 5486: 5487: @findex REAL_INFINITY 5488: @item REAL_INFINITY 5489: Define this macro if infinity is a possible floating point value, and 5490: therefore division by 0 is legitimate. 5491: 5492: @findex REAL_VALUE_ISINF 5493: @findex isinf 5494: @item REAL_VALUE_ISINF (@var{x}) 5495: A macro for a C expression which determines whether @var{x}, a floating 5496: point value, is infinity. The value has type @code{int}. 5497: By default, this is defined to call @code{isinf}. 5498: 5499: @findex REAL_VALUE_ISNAN 5500: @findex isnan 5501: @item REAL_VALUE_ISNAN (@var{x}) 5502: A macro for a C expression which determines whether @var{x}, a floating 5503: point value, is a ``nan'' (not-a-number). The value has type 5504: @code{int}. By default, this is defined to call @code{isnan}. 5505: @end table 5506: 5507: @cindex constant folding and floating point 5508: Define the following additional macros if you want to make floating 5509: point constant folding work while cross compiling. If you don't 5510: define them, cross compilation is still possible, but constant folding 5511: will not happen for floating point values. 5512: 5513: @table @code 5514: @findex REAL_ARITHMETIC 5515: @item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y}) 5516: A macro for a C statement which calculates an arithmetic operation of 5517: the two floating point values @var{x} and @var{y}, both of type 5518: @code{REAL_VALUE_TYPE} in the target machine's representation, to 5519: produce a result of the same type and representation which is stored 5520: in @var{output} (which will be a variable). 5521: 5522: The operation to be performed is specified by @var{code}, a tree code 5523: which will always be one of the following: @code{PLUS_EXPR}, 5524: @code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR}, 5525: @code{MAX_EXPR}, @code{MIN_EXPR}.@refill 5526: 5527: @cindex overflow while constant folding 5528: The expansion of this macro is responsible for checking for overflow. 5529: If overflow happens, the macro expansion should execute the statement 5530: @code{return 0;}, which indicates the inability to perform the 5531: arithmetic operation requested. 5532: 5533: @findex REAL_VALUE_NEGATE 5534: @item REAL_VALUE_NEGATE (@var{x}) 5535: A macro for a C expression which returns the negative of the floating 5536: point value @var{x}. Both @var{x} and the value of the expression 5537: have type @code{REAL_VALUE_TYPE} and are in the target machine's 5538: floating point representation. 5539: 5540: There is no way for this macro to report overflow, since overflow 5541: can't happen in the negation operation. 5542: 5543: @findex REAL_VALUE_TRUNCATE 1.1.1.4 root 5544: @item REAL_VALUE_TRUNCATE (@var{mode}, @var{x}) 5545: A macro for a C expression which converts the floating point value 5546: @var{x} to mode @var{mode}. 1.1 root 5547: 1.1.1.5 ! root 5548: Both @var{x} and the value of the expression are in the target machine's ! 5549: floating point representation and have type @code{REAL_VALUE_TYPE}. ! 5550: However, the value should have an appropriate bit pattern to be output ! 5551: properly as a floating constant whose precision accords with mode ! 5552: @var{mode}. 1.1 root 5553: 5554: There is no way for this macro to report overflow. 5555: 5556: @findex REAL_VALUE_TO_INT 5557: @item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x}) 5558: A macro for a C expression which converts a floating point value 5559: @var{x} into a double-precision integer which is then stored into 5560: @var{low} and @var{high}, two variables of type @var{int}. 5561: 5562: @item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}) 5563: @findex REAL_VALUE_FROM_INT 5564: A macro for a C expression which converts a double-precision integer 5565: found in @var{low} and @var{high}, two variables of type @var{int}, 5566: into a floating point value which is then stored into @var{x}. 5567: @end table 5568: 1.1.1.2 root 5569: @node Misc 1.1 root 5570: @section Miscellaneous Parameters 5571: @cindex parameters, miscellaneous 5572: 5573: @table @code 5574: @item PREDICATE_CODES 5575: @findex PREDICATE_CODES 1.1.1.5 ! root 5576: Define this if you have defined special-purpose predicates in the file 1.1 root 5577: @file{@var{machine}.c}. This macro is called within an initializer of an 5578: array of structures. The first field in the structure is the name of a 1.1.1.2 root 5579: predicate and the second field is an array of rtl codes. For each 1.1 root 5580: predicate, list all rtl codes that can be in expressions matched by the 5581: predicate. The list should have a trailing comma. Here is an example 5582: of two entries in the list for a typical RISC machine: 5583: 1.1.1.5 ! root 5584: @smallexample 1.1 root 5585: #define PREDICATE_CODES \ 5586: @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 5587: @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 1.1.1.5 ! root 5588: @end smallexample 1.1 root 5589: 5590: Defining this macro does not affect the generated code (however, 5591: incorrect definitions that omit an rtl code that may be matched by the 5592: predicate can cause the compiler to malfunction). Instead, it allows 5593: the table built by @file{genrecog} to be more compact and efficient, 5594: thus speeding up the compiler. The most important predicates to include 5595: in the list specified by this macro are thoses used in the most insn 5596: patterns. 5597: 5598: @findex CASE_VECTOR_MODE 5599: @item CASE_VECTOR_MODE 5600: An alias for a machine mode name. This is the machine mode that 5601: elements of a jump-table should have. 5602: 5603: @findex CASE_VECTOR_PC_RELATIVE 5604: @item CASE_VECTOR_PC_RELATIVE 5605: Define this macro if jump-tables should contain relative addresses. 5606: 5607: @findex CASE_DROPS_THROUGH 5608: @item CASE_DROPS_THROUGH 5609: Define this if control falls through a @code{case} insn when the index 5610: value is out of range. This means the specified default-label is 5611: actually ignored by the @code{case} insn proper. 5612: 1.1.1.4 root 5613: @findex CASE_VALUES_THRESHOLD 5614: @item CASE_VALUES_THRESHOLD 5615: Define this to be the smallest number of different values for which it 5616: is best to use a jump-table instead of a tree of conditional branches. 5617: The default is four for machines with a @code{casesi} instruction and 5618: five otherwise. This is best for most machines. 5619: 1.1 root 5620: @findex BYTE_LOADS_ZERO_EXTEND 5621: @item BYTE_LOADS_ZERO_EXTEND 5622: Define this macro if an instruction to load a value narrower than a 5623: word from memory into a register also zero-extends the value to the whole 5624: register. 5625: 1.1.1.4 root 5626: @findex BYTE_LOADS_SIGN_EXTEND 5627: @item BYTE_LOADS_SIGN_EXTEND 5628: Define this macro if an instruction to load a value narrower than a 5629: word from memory into a register also sign-extends the value to the whole 5630: register. 5631: 1.1 root 5632: @findex IMPLICIT_FIX_EXPR 5633: @item IMPLICIT_FIX_EXPR 5634: An alias for a tree code that should be used by default for conversion 5635: of floating point values to fixed point. Normally, 5636: @code{FIX_ROUND_EXPR} is used.@refill 5637: 5638: @findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 5639: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC 5640: Define this macro if the same instructions that convert a floating 5641: point number to a signed fixed point number also convert validly to an 5642: unsigned one. 5643: 5644: @findex EASY_DIV_EXPR 5645: @item EASY_DIV_EXPR 5646: An alias for a tree code that is the easiest kind of division to 5647: compile code for in the general case. It may be 5648: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or 5649: @code{ROUND_DIV_EXPR}. These four division operators differ in how 5650: they round the result to an integer. @code{EASY_DIV_EXPR} is used 5651: when it is permissible to use any of those kinds of division and the 5652: choice should be made on the basis of efficiency.@refill 5653: 5654: @findex MOVE_MAX 5655: @item MOVE_MAX 5656: The maximum number of bytes that a single instruction can move quickly 5657: from memory to memory. 5658: 5659: @findex SHIFT_COUNT_TRUNCATED 5660: @item SHIFT_COUNT_TRUNCATED 5661: Defining this macro causes the compiler to omit a sign-extend, 5662: zero-extend, or bitwise `and' instruction that truncates the count of a 5663: shift operation to a width equal to the number of bits needed to 5664: represent the size of the object being shifted. On machines that have 1.1.1.4 root 5665: instructions that act on bitfields at variable positions, which may 5666: include `bit test' instructions, defining @code{SHIFT_COUNT_TRUNCATED} 5667: also enables deletion of truncations of the values that serve as 5668: arguments to bitfield instructions. 1.1 root 5669: 5670: If both types of instructions truncate the count (for shifts) and 5671: position (for bitfield operations), or if no variable-position bitfield 5672: instructions exist, you should define this macro. 5673: 1.1.1.2 root 5674: However, on some machines, such as the 80386 and the 680x0, truncation 5675: only applies to shift operations and not the (real or pretended) 5676: bitfield operations. Do not define @code{SHIFT_COUNT_TRUNCATED} on such 5677: machines. Instead, add patterns to the @file{md} file that include the 5678: implied truncation of the shift instructions. 1.1 root 5679: 5680: @findex TRULY_NOOP_TRUNCATION 5681: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 5682: A C expression which is nonzero if on this machine it is safe to 5683: ``convert'' an integer of @var{inprec} bits to one of @var{outprec} 5684: bits (where @var{outprec} is smaller than @var{inprec}) by merely 5685: operating on it as if it had only @var{outprec} bits. 5686: 5687: On many machines, this expression can be 1. 5688: 1.1.1.5 ! root 5689: @c rearranged this, removed the phrase "it is reported that". this was ! 5690: @c to fix an overfull hbox. --mew 10feb93 ! 5691: When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for ! 5692: modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. ! 5693: If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in ! 5694: such cases may improve things. 1.1 root 5695: 5696: @findex STORE_FLAG_VALUE 5697: @item STORE_FLAG_VALUE 5698: A C expression describing the value returned by a comparison operator 1.1.1.4 root 5699: with an integral mode and stored by a store-flag instruction 5700: (@samp{s@var{cond}}) when the condition is true. This description must 5701: apply to @emph{all} the @samp{s@var{cond}} patterns and all the 5702: comparison operators whose results have a @code{MODE_INT} mode. 1.1 root 5703: 5704: A value of 1 or -1 means that the instruction implementing the 5705: comparison operator returns exactly 1 or -1 when the comparison is true 5706: and 0 when the comparison is false. Otherwise, the value indicates 5707: which bits of the result are guaranteed to be 1 when the comparison is 5708: true. This value is interpreted in the mode of the comparison 5709: operation, which is given by the mode of the first operand in the 5710: @samp{s@var{cond}} pattern. Either the low bit or the sign bit of 5711: @code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 5712: the compiler. 5713: 5714: If @code{STORE_FLAG_VALUE} is neither 1 or -1, the compiler will 5715: generate code that depends only on the specified bits. It can also 5716: replace comparison operators with equivalent operations if they cause 5717: the required bits to be set, even if the remaining bits are undefined. 5718: For example, on a machine whose comparison operators return an 5719: @code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 5720: @samp{0x80000000}, saying that just the sign bit is relevant, the 5721: expression 5722: 1.1.1.5 ! root 5723: @smallexample 1.1 root 5724: (ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 1.1.1.5 ! root 5725: @end smallexample 1.1 root 5726: 5727: @noindent 5728: can be converted to 5729: 1.1.1.5 ! root 5730: @smallexample 1.1 root 5731: (ashift:SI @var{x} (const_int @var{n})) 1.1.1.5 ! root 5732: @end smallexample 1.1 root 5733: 5734: @noindent 5735: where @var{n} is the appropriate shift count to move the bit being 5736: tested into the sign bit. 5737: 5738: There is no way to describe a machine that always sets the low-order bit 5739: for a true value, but does not guarantee the value of any other bits, 5740: but we do not know of any machine that has such an instruction. If you 5741: are trying to port GNU CC to such a machine, include an instruction to 5742: perform a logical-and of the result with 1 in the pattern for the 1.1.1.5 ! root 5743: comparison operators and let us know ! 5744: @ifset USING ! 5745: (@pxref{Bug Reporting,,How to Report Bugs}). ! 5746: @end ifset ! 5747: @ifclear USING ! 5748: (@pxref{Bug Reporting,,How to Report Bugs,gcc.info,Using GCC}). ! 5749: @end ifclear 1.1 root 5750: 5751: Often, a machine will have multiple instructions that obtain a value 5752: from a comparison (or the condition codes). Here are rules to guide the 5753: choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 5754: to be used: 5755: 5756: @itemize @bullet 5757: @item 5758: Use the shortest sequence that yields a valid definition for 1.1.1.3 root 5759: @code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 1.1 root 5760: ``normalize'' the value (convert it to, e.g., 1 or 0) than for the 5761: comparison operators to do so because there may be opportunities to 5762: combine the normalization with other operations. 5763: 5764: @item 5765: For equal-length sequences, use a value of 1 or -1, with -1 being 5766: slightly preferred on machines with expensive jumps and 1 preferred on 5767: other machines. 5768: 5769: @item 5770: As a second choice, choose a value of @samp{0x80000001} if instructions 5771: exist that set both the sign and low-order bits but do not define the 5772: others. 5773: 5774: @item 5775: Otherwise, use a value of @samp{0x80000000}. 5776: @end itemize 5777: 1.1.1.5 ! root 5778: Many machines can produce both the value chosen for ! 5779: @code{STORE_FLAG_VALUE} and its negation in the same number of ! 5780: instructions. On those machines, you should also define a pattern for ! 5781: those cases, e.g., one matching ! 5782: ! 5783: @smallexample ! 5784: (set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) ! 5785: @end smallexample ! 5786: ! 5787: Some machines can also perform @code{and} or @code{plus} operations on ! 5788: condition code values with less instructions than the corresponding ! 5789: @samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those ! 5790: machines, define the appropriate patterns. Use the names @code{incscc} ! 5791: and @code{decscc}, respectively, for the the patterns which perform ! 5792: @code{plus} or @code{minus} operations on condition code values. See ! 5793: @file{rs6000.md} for some examples. The GNU Superoptizer can be used to ! 5794: find such instruction sequences on other machines. ! 5795: 1.1 root 5796: You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 5797: instructions. 5798: 1.1.1.4 root 5799: @findex FLOAT_STORE_FLAG_VALUE 5800: @item FLOAT_STORE_FLAG_VALUE 5801: A C expression that gives a non-zero floating point value that is 5802: returned when comparison operators with floating-point results are true. 5803: Define this macro on machine that have comparison operations that return 5804: floating-point values. If there are no such operations, do not define 5805: this macro. 5806: 1.1 root 5807: @findex Pmode 5808: @item Pmode 5809: An alias for the machine mode for pointers. Normally the definition 5810: can be 5811: 1.1.1.5 ! root 5812: @smallexample 1.1 root 5813: #define Pmode SImode 1.1.1.5 ! root 5814: @end smallexample 1.1 root 5815: 5816: @findex FUNCTION_MODE 5817: @item FUNCTION_MODE 5818: An alias for the machine mode used for memory references to functions 5819: being called, in @code{call} RTL expressions. On most machines this 5820: should be @code{QImode}. 5821: 5822: @findex INTEGRATE_THRESHOLD 5823: @item INTEGRATE_THRESHOLD (@var{decl}) 5824: A C expression for the maximum number of instructions above which the 5825: function @var{decl} should not be inlined. @var{decl} is a 5826: @code{FUNCTION_DECL} node. 5827: 5828: The default definition of this macro is 64 plus 8 times the number of 5829: arguments that the function accepts. Some people think a larger 5830: threshold should be used on RISC machines. 5831: 5832: @findex SCCS_DIRECTIVE 5833: @item SCCS_DIRECTIVE 5834: Define this if the preprocessor should ignore @code{#sccs} directives 5835: and print no error message. 5836: 5837: @findex HANDLE_PRAGMA 5838: @findex #pragma 5839: @findex pragma 5840: @item HANDLE_PRAGMA (@var{stream}) 5841: Define this macro if you want to implement any pragmas. If defined, it 5842: should be a C statement to be executed when @code{#pragma} is seen. The 5843: argument @var{stream} is the stdio input stream from which the source 5844: text can be read. 5845: 5846: It is generally a bad idea to implement new uses of @code{#pragma}. The 5847: only reason to define this macro is for compatibility with other 5848: compilers that do support @code{#pragma} for the sake of any user 5849: programs which already use it. 5850: 5851: @findex DOLLARS_IN_IDENTIFIERS 5852: @item DOLLARS_IN_IDENTIFIERS 5853: Define this macro to control use of the character @samp{$} in identifier 5854: names. The value should be 0, 1, or 2. 0 means @samp{$} is not allowed 5855: by default; 1 means it is allowed by default if @samp{-traditional} is 5856: used; 2 means it is allowed by default provided @samp{-ansi} is not used. 5857: 1 is the default; there is no need to define this macro in that case. 5858: 1.1.1.2 root 5859: @findex NO_DOLLAR_IN_LABEL 5860: @item NO_DOLLAR_IN_LABEL 5861: Define this macro if the assembler does not accept the character 5862: @samp{$} in label names. By default constructors and destructors in 5863: G++ have @samp{$} in the identifiers. If this macro is defined, 5864: @samp{.} is used instead. 5865: 1.1 root 5866: @findex DEFAULT_MAIN_RETURN 5867: @item DEFAULT_MAIN_RETURN 5868: Define this macro if the target system expects every program's @code{main} 5869: function to return a standard ``success'' value by default (if no other 5870: value is explicitly returned). 5871: 5872: The definition should be a C statement (sans semicolon) to generate the 5873: appropriate rtl instructions. It is used only when compiling the end of 5874: @code{main}. 5875: 5876: @item HAVE_ATEXIT 5877: @findex HAVE_ATEXIT 5878: Define this if the target system supports the function 5879: @code{atexit} from the ANSI C standard. If this is not defined, 5880: and @code{INIT_SECTION_ASM_OP} is not defined, a default 5881: @code{exit} function will be provided to support C++. 5882: 5883: @item EXIT_BODY 5884: @findex EXIT_BODY 5885: Define this if your @code{exit} function needs to do something 5886: besides calling an external function @code{_cleanup} before 5887: terminating with @code{_exit}. The @code{EXIT_BODY} macro is 5888: only needed if netiher @code{HAVE_ATEXIT} nor 5889: @code{INIT_SECTION_ASM_OP} are defined. 1.1.1.5 ! root 5890: ! 5891: @findex INSN_SETS_ARE_DELAYED ! 5892: @item INSN_SETS_ARE_DELAYED (@var{insn}) ! 5893: Define this macro as a C expression that is nonzero if it is safe for the ! 5894: delay slot scheduler to place instructions in the delay slot of @var{insn}, ! 5895: even if they appear to use a resource set or clobbered in @var{insn}. ! 5896: @var{insn} is always a @code{jump_insn} or an @code{insn}; GNU CC knows that ! 5897: every @code{call_insn} has this behavior. On machines where some @code{insn} ! 5898: or @code{jump_insn} is really a function call and hence has this behavior, ! 5899: you should define this macro. ! 5900: ! 5901: You need not define this macro if it would always return zero. ! 5902: ! 5903: @findex INSN_REFERENCES_ARE_DELAYED ! 5904: @item INSN_REFERENCES_ARE_DELAYED (@var{insn}) ! 5905: Define this macro as a C expression that is nonzero if it is safe for the ! 5906: delay slot scheduler to place instructions in the delay slot of @var{insn}, ! 5907: even if they appear to set or clobber a resource referenced in @var{insn}. ! 5908: @var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where ! 5909: some @code{insn} or @code{jump_insn} is really a function call and its operands ! 5910: are registers whose use is actually in the subroutine it calls, you should ! 5911: define this macro. Doing so allows the delay slot scheduler to move ! 5912: instructions which copy arguments into the argument registers into the delay ! 5913: slot of @var{insn}. ! 5914: ! 5915: You need not define this macro if it would always return zero. 1.1 root 5916: @end table
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.