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