![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-21 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to gcc.info-21 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.3 root 1: This is Info file gcc.info, produced by Makeinfo-1.55 from the input
1.1 root 2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
1.1.1.4 ! root 6: Published by the Free Software Foundation 59 Temple Place - Suite 330
! 7: Boston, MA 02111-1307 USA
1.1 root 8:
1.1.1.4 ! root 9: Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software
! 10: Foundation, Inc.
1.1 root 11:
12: Permission is granted to make and distribute verbatim copies of this
13: manual provided the copyright notice and this permission notice are
14: preserved on all copies.
15:
16: Permission is granted to copy and distribute modified versions of
17: this manual under the conditions for verbatim copying, provided also
1.1.1.3 root 18: that the sections entitled "GNU General Public License," "Funding for
19: Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20: included exactly as in the original, and provided that the entire
21: resulting derived work is distributed under the terms of a permission
22: notice identical to this one.
1.1 root 23:
24: Permission is granted to copy and distribute translations of this
25: manual into another language, under the above conditions for modified
26: versions, except that the sections entitled "GNU General Public
1.1.1.3 root 27: License," "Funding for Free Software," and "Protect Your Freedom--Fight
28: `Look And Feel'", and this permission notice, may be included in
29: translations approved by the Free Software Foundation instead of in the
30: original English.
31:
32:
1.1.1.4 ! root 33: File: gcc.info, Node: Register Arguments, Next: Scalar Return, Prev: Stack Arguments, Up: Stack and Calling
1.1.1.3 root 34:
1.1.1.4 ! root 35: Passing Arguments in Registers
! 36: ------------------------------
1.1.1.3 root 37:
1.1.1.4 ! root 38: This section describes the macros which let you control how various
! 39: types of arguments are passed in registers or how they are arranged in
! 40: the stack.
! 41:
! 42: `FUNCTION_ARG (CUM, MODE, TYPE, NAMED)'
! 43: A C expression that controls whether a function argument is passed
! 44: in a register, and which register.
! 45:
! 46: The arguments are CUM, which summarizes all the previous
! 47: arguments; MODE, the machine mode of the argument; TYPE, the data
! 48: type of the argument as a tree node or 0 if that is not known
! 49: (which happens for C support library functions); and NAMED, which
! 50: is 1 for an ordinary argument and 0 for nameless arguments that
! 51: correspond to `...' in the called function's prototype.
! 52:
! 53: The value of the expression should either be a `reg' RTX for the
! 54: hard register in which to pass the argument, or zero to pass the
! 55: argument on the stack.
! 56:
! 57: For machines like the Vax and 68000, where normally all arguments
! 58: are pushed, zero suffices as a definition.
! 59:
! 60: The usual way to make the ANSI library `stdarg.h' work on a machine
! 61: where some arguments are usually passed in registers, is to cause
! 62: nameless arguments to be passed on the stack instead. This is done
! 63: by making `FUNCTION_ARG' return 0 whenever NAMED is 0.
! 64:
! 65: You may use the macro `MUST_PASS_IN_STACK (MODE, TYPE)' in the
! 66: definition of this macro to determine if this argument is of a
! 67: type that must be passed in the stack. If `REG_PARM_STACK_SPACE'
! 68: is not defined and `FUNCTION_ARG' returns non-zero for such an
! 69: argument, the compiler will abort. If `REG_PARM_STACK_SPACE' is
! 70: defined, the argument will be computed in the stack and then
! 71: loaded into a register.
! 72:
! 73: `FUNCTION_INCOMING_ARG (CUM, MODE, TYPE, NAMED)'
! 74: Define this macro if the target machine has "register windows", so
! 75: that the register in which a function sees an arguments is not
! 76: necessarily the same as the one in which the caller passed the
! 77: argument.
! 78:
! 79: For such machines, `FUNCTION_ARG' computes the register in which
! 80: the caller passes the value, and `FUNCTION_INCOMING_ARG' should be
! 81: defined in a similar fashion to tell the function being called
! 82: where the arguments will arrive.
! 83:
! 84: If `FUNCTION_INCOMING_ARG' is not defined, `FUNCTION_ARG' serves
! 85: both purposes.
! 86:
! 87: `FUNCTION_ARG_PARTIAL_NREGS (CUM, MODE, TYPE, NAMED)'
! 88: A C expression for the number of words, at the beginning of an
! 89: argument, must be put in registers. The value must be zero for
! 90: arguments that are passed entirely in registers or that are
! 91: entirely pushed on the stack.
! 92:
! 93: On some machines, certain arguments must be passed partially in
! 94: registers and partially in memory. On these machines, typically
! 95: the first N words of arguments are passed in registers, and the
! 96: rest on the stack. If a multi-word argument (a `double' or a
! 97: structure) crosses that boundary, its first few words must be
! 98: passed in registers and the rest must be pushed. This macro tells
! 99: the compiler when this occurs, and how many of the words should go
! 100: in registers.
! 101:
! 102: `FUNCTION_ARG' for these arguments should return the first
! 103: register to be used by the caller for this argument; likewise
! 104: `FUNCTION_INCOMING_ARG', for the called function.
! 105:
! 106: `FUNCTION_ARG_PASS_BY_REFERENCE (CUM, MODE, TYPE, NAMED)'
! 107: A C expression that indicates when an argument must be passed by
! 108: reference. If nonzero for an argument, a copy of that argument is
! 109: made in memory and a pointer to the argument is passed instead of
! 110: the argument itself. The pointer is passed in whatever way is
! 111: appropriate for passing a pointer to that type.
! 112:
! 113: On machines where `REG_PARM_STACK_SPACE' is not defined, a suitable
! 114: definition of this macro might be
! 115: #define FUNCTION_ARG_PASS_BY_REFERENCE\
! 116: (CUM, MODE, TYPE, NAMED) \
! 117: MUST_PASS_IN_STACK (MODE, TYPE)
! 118:
! 119: `FUNCTION_ARG_CALLEE_COPIES (CUM, MODE, TYPE, NAMED)'
! 120: If defined, a C expression that indicates when it is the called
! 121: function's responsibility to make a copy of arguments passed by
! 122: invisible reference. Normally, the caller makes a copy and passes
! 123: the address of the copy to the routine being called. When
! 124: FUNCTION_ARG_CALLEE_COPIES is defined and is nonzero, the caller
! 125: does not make a copy. Instead, it passes a pointer to the "live"
! 126: value. The called function must not modify this value. If it can
! 127: be determined that the value won't be modified, it need not make a
! 128: copy; otherwise a copy must be made.
! 129:
! 130: `CUMULATIVE_ARGS'
! 131: A C type for declaring a variable that is used as the first
! 132: argument of `FUNCTION_ARG' and other related values. For some
! 133: target machines, the type `int' suffices and can hold the number
! 134: of bytes of argument so far.
! 135:
! 136: There is no need to record in `CUMULATIVE_ARGS' anything about the
! 137: arguments that have been passed on the stack. The compiler has
! 138: other variables to keep track of that. For target machines on
! 139: which all arguments are passed on the stack, there is no need to
! 140: store anything in `CUMULATIVE_ARGS'; however, the data structure
! 141: must exist and should not be empty, so use `int'.
! 142:
! 143: `INIT_CUMULATIVE_ARGS (CUM, FNTYPE, LIBNAME)'
! 144: A C statement (sans semicolon) for initializing the variable CUM
! 145: for the state at the beginning of the argument list. The variable
! 146: has type `CUMULATIVE_ARGS'. The value of FNTYPE is the tree node
! 147: for the data type of the function which will receive the args, or 0
! 148: if the args are to a compiler support library function.
! 149:
! 150: When processing a call to a compiler support library function,
! 151: LIBNAME identifies which one. It is a `symbol_ref' rtx which
! 152: contains the name of the function, as a string. LIBNAME is 0 when
! 153: an ordinary C function call is being processed. Thus, each time
! 154: this macro is called, either LIBNAME or FNTYPE is nonzero, but
! 155: never both of them at once.
! 156:
! 157: `INIT_CUMULATIVE_INCOMING_ARGS (CUM, FNTYPE, LIBNAME)'
! 158: Like `INIT_CUMULATIVE_ARGS' but overrides it for the purposes of
! 159: finding the arguments for the function being compiled. If this
! 160: macro is undefined, `INIT_CUMULATIVE_ARGS' is used instead.
! 161:
! 162: The value passed for LIBNAME is always 0, since library routines
! 163: with special calling conventions are never compiled with GNU CC.
! 164: The argument LIBNAME exists for symmetry with
! 165: `INIT_CUMULATIVE_ARGS'.
! 166:
! 167: `FUNCTION_ARG_ADVANCE (CUM, MODE, TYPE, NAMED)'
! 168: A C statement (sans semicolon) to update the summarizer variable
! 169: CUM to advance past an argument in the argument list. The values
! 170: MODE, TYPE and NAMED describe that argument. Once this is done,
! 171: the variable CUM is suitable for analyzing the *following*
! 172: argument with `FUNCTION_ARG', etc.
! 173:
! 174: This macro need not do anything if the argument in question was
! 175: passed on the stack. The compiler knows how to track the amount
! 176: of stack space used for arguments without any special help.
! 177:
! 178: `FUNCTION_ARG_PADDING (MODE, TYPE)'
! 179: If defined, a C expression which determines whether, and in which
! 180: direction, to pad out an argument with extra space. The value
! 181: should be of type `enum direction': either `upward' to pad above
! 182: the argument, `downward' to pad below, or `none' to inhibit
! 183: padding.
! 184:
! 185: The *amount* of padding is always just enough to reach the next
! 186: multiple of `FUNCTION_ARG_BOUNDARY'; this macro does not control
! 187: it.
! 188:
! 189: This macro has a default definition which is right for most
! 190: systems. For little-endian machines, the default is to pad
! 191: upward. For big-endian machines, the default is to pad downward
! 192: for an argument of constant size shorter than an `int', and upward
! 193: otherwise.
! 194:
! 195: `FUNCTION_ARG_BOUNDARY (MODE, TYPE)'
! 196: If defined, a C expression that gives the alignment boundary, in
! 197: bits, of an argument with the specified mode and type. If it is
! 198: not defined, `PARM_BOUNDARY' is used for all arguments.
! 199:
! 200: `FUNCTION_ARG_REGNO_P (REGNO)'
! 201: A C expression that is nonzero if REGNO is the number of a hard
! 202: register in which function arguments are sometimes passed. This
! 203: does *not* include implicit arguments such as the static chain and
! 204: the structure-value address. On many machines, no registers can be
! 205: used for this purpose since all function arguments are pushed on
! 206: the stack.
1.1.1.3 root 207:
208:
1.1.1.4 ! root 209: File: gcc.info, Node: Scalar Return, Next: Aggregate Return, Prev: Register Arguments, Up: Stack and Calling
1.1.1.3 root 210:
1.1.1.4 ! root 211: How Scalar Function Values Are Returned
! 212: ---------------------------------------
1.1.1.3 root 213:
1.1.1.4 ! root 214: This section discusses the macros that control returning scalars as
! 215: values--values that can fit in registers.
1.1.1.3 root 216:
1.1.1.4 ! root 217: `TRADITIONAL_RETURN_FLOAT'
! 218: Define this macro if `-traditional' should not cause functions
! 219: declared to return `float' to convert the value to `double'.
! 220:
! 221: `FUNCTION_VALUE (VALTYPE, FUNC)'
! 222: A C expression to create an RTX representing the place where a
! 223: function returns a value of data type VALTYPE. VALTYPE is a tree
! 224: node representing a data type. Write `TYPE_MODE (VALTYPE)' to get
! 225: the machine mode used to represent that type. On many machines,
! 226: only the mode is relevant. (Actually, on most machines, scalar
! 227: values are returned in the same place regardless of mode).
! 228:
! 229: If `PROMOTE_FUNCTION_RETURN' is defined, you must apply the same
! 230: promotion rules specified in `PROMOTE_MODE' if VALTYPE is a scalar
! 231: type.
! 232:
! 233: If the precise function being called is known, FUNC is a tree node
! 234: (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
! 235: makes it possible to use a different value-returning convention
! 236: for specific functions when all their calls are known.
! 237:
! 238: `FUNCTION_VALUE' is not used for return vales with aggregate data
! 239: types, because these are returned in another way. See
! 240: `STRUCT_VALUE_REGNUM' and related macros, below.
! 241:
! 242: `FUNCTION_OUTGOING_VALUE (VALTYPE, FUNC)'
! 243: Define this macro if the target machine has "register windows" so
! 244: that the register in which a function returns its value is not the
! 245: same as the one in which the caller sees the value.
! 246:
! 247: For such machines, `FUNCTION_VALUE' computes the register in which
! 248: the caller will see the value. `FUNCTION_OUTGOING_VALUE' should be
! 249: defined in a similar fashion to tell the function where to put the
! 250: value.
! 251:
! 252: If `FUNCTION_OUTGOING_VALUE' is not defined, `FUNCTION_VALUE'
! 253: serves both purposes.
! 254:
! 255: `FUNCTION_OUTGOING_VALUE' is not used for return vales with
! 256: aggregate data types, because these are returned in another way.
! 257: See `STRUCT_VALUE_REGNUM' and related macros, below.
! 258:
! 259: `LIBCALL_VALUE (MODE)'
! 260: A C expression to create an RTX representing the place where a
! 261: library function returns a value of mode MODE. If the precise
! 262: function being called is known, FUNC is a tree node
! 263: (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
! 264: makes it possible to use a different value-returning convention
! 265: for specific functions when all their calls are known.
! 266:
! 267: Note that "library function" in this context means a compiler
! 268: support routine, used to perform arithmetic, whose name is known
! 269: specially by the compiler and was not mentioned in the C code being
! 270: compiled.
! 271:
! 272: The definition of `LIBRARY_VALUE' need not be concerned aggregate
! 273: data types, because none of the library functions returns such
! 274: types.
! 275:
! 276: `FUNCTION_VALUE_REGNO_P (REGNO)'
! 277: A C expression that is nonzero if REGNO is the number of a hard
! 278: register in which the values of called function may come back.
! 279:
! 280: A register whose use for returning values is limited to serving as
! 281: the second of a pair (for a value of type `double', say) need not
! 282: be recognized by this macro. So for most machines, this definition
! 283: suffices:
! 284:
! 285: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
! 286:
! 287: If the machine has register windows, so that the caller and the
! 288: called function use different registers for the return value, this
! 289: macro should recognize only the caller's register numbers.
! 290:
! 291: `APPLY_RESULT_SIZE'
! 292: Define this macro if `untyped_call' and `untyped_return' need more
! 293: space than is implied by `FUNCTION_VALUE_REGNO_P' for saving and
! 294: restoring an arbitrary return value.
1.1.1.3 root 295:
296:
1.1.1.4 ! root 297: File: gcc.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling
1.1.1.3 root 298:
1.1.1.4 ! root 299: How Large Values Are Returned
! 300: -----------------------------
1.1.1.3 root 301:
1.1.1.4 ! root 302: When a function value's mode is `BLKmode' (and in some other cases),
! 303: the value is not returned according to `FUNCTION_VALUE' (*note Scalar
! 304: Return::.). Instead, the caller passes the address of a block of
! 305: memory in which the value should be stored. This address is called the
! 306: "structure value address".
! 307:
! 308: This section describes how to control returning structure values in
! 309: memory.
! 310:
! 311: `RETURN_IN_MEMORY (TYPE)'
! 312: A C expression which can inhibit the returning of certain function
! 313: values in registers, based on the type of value. A nonzero value
! 314: says to return the function value in memory, just as large
! 315: structures are always returned. Here TYPE will be a C expression
! 316: of type `tree', representing the data type of the value.
! 317:
! 318: Note that values of mode `BLKmode' must be explicitly handled by
! 319: this macro. Also, the option `-fpcc-struct-return' takes effect
! 320: regardless of this macro. On most systems, it is possible to
! 321: leave the macro undefined; this causes a default definition to be
! 322: used, whose value is the constant 1 for `BLKmode' values, and 0
! 323: otherwise.
! 324:
! 325: Do not use this macro to indicate that structures and unions
! 326: should always be returned in memory. You should instead use
! 327: `DEFAULT_PCC_STRUCT_RETURN' to indicate this.
! 328:
! 329: `DEFAULT_PCC_STRUCT_RETURN'
! 330: Define this macro to be 1 if all structure and union return values
! 331: must be in memory. Since this results in slower code, this should
! 332: be defined only if needed for compatibility with other compilers
! 333: or with an ABI. If you define this macro to be 0, then the
! 334: conventions used for structure and union return values are decided
! 335: by the `RETURN_IN_MEMORY' macro.
! 336:
! 337: If not defined, this defaults to the value 1.
! 338:
! 339: `STRUCT_VALUE_REGNUM'
! 340: If the structure value address is passed in a register, then
! 341: `STRUCT_VALUE_REGNUM' should be the number of that register.
! 342:
! 343: `STRUCT_VALUE'
! 344: If the structure value address is not passed in a register, define
! 345: `STRUCT_VALUE' as an expression returning an RTX for the place
! 346: where the address is passed. If it returns 0, the address is
! 347: passed as an "invisible" first argument.
! 348:
! 349: `STRUCT_VALUE_INCOMING_REGNUM'
! 350: On some architectures the place where the structure value address
! 351: is found by the called function is not the same place that the
! 352: caller put it. This can be due to register windows, or it could
! 353: be because the function prologue moves it to a different place.
! 354:
! 355: If the incoming location of the structure value address is in a
! 356: register, define this macro as the register number.
! 357:
! 358: `STRUCT_VALUE_INCOMING'
! 359: If the incoming location is not a register, then you should define
! 360: `STRUCT_VALUE_INCOMING' as an expression for an RTX for where the
! 361: called function should find the value. If it should find the
! 362: value on the stack, define this to create a `mem' which refers to
! 363: the frame pointer. A definition of 0 means that the address is
! 364: passed as an "invisible" first argument.
! 365:
! 366: `PCC_STATIC_STRUCT_RETURN'
! 367: Define this macro if the usual system convention on the target
! 368: machine for returning structures and unions is for the called
! 369: function to return the address of a static variable containing the
! 370: value.
1.1.1.3 root 371:
1.1.1.4 ! root 372: Do not define this if the usual system convention is for the
! 373: caller to pass an address to the subroutine.
1.1.1.3 root 374:
1.1.1.4 ! root 375: This macro has effect in `-fpcc-struct-return' mode, but it does
! 376: nothing when you use `-freg-struct-return' mode.
1.1.1.2 root 377:
378:
1.1.1.4 ! root 379: File: gcc.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling
1.1.1.2 root 380:
1.1.1.4 ! root 381: Caller-Saves Register Allocation
! 382: --------------------------------
1.1.1.2 root 383:
1.1.1.4 ! root 384: If you enable it, GNU CC can save registers around function calls.
! 385: This makes it possible to use call-clobbered registers to hold
! 386: variables that must live across calls.
! 387:
! 388: `DEFAULT_CALLER_SAVES'
! 389: Define this macro if function calls on the target machine do not
! 390: preserve any registers; in other words, if `CALL_USED_REGISTERS'
! 391: has 1 for all registers. This macro enables `-fcaller-saves' by
! 392: default. Eventually that option will be enabled by default on all
! 393: machines and both the option and this macro will be eliminated.
! 394:
! 395: `CALLER_SAVE_PROFITABLE (REFS, CALLS)'
! 396: A C expression to determine whether it is worthwhile to consider
! 397: placing a pseudo-register in a call-clobbered hard register and
! 398: saving and restoring it around each function call. The expression
! 399: should be 1 when this is worth doing, and 0 otherwise.
1.1.1.2 root 400:
1.1.1.4 ! root 401: If you don't define this macro, a default is used which is good on
! 402: most machines: `4 * CALLS < REFS'.
1.1.1.3 root 403:
404:
1.1.1.4 ! root 405: File: gcc.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling
1.1.1.3 root 406:
1.1.1.4 ! root 407: Function Entry and Exit
! 408: -----------------------
1.1.1.3 root 409:
1.1.1.4 ! root 410: This section describes the macros that output function entry
! 411: ("prologue") and exit ("epilogue") code.
1.1.1.3 root 412:
1.1.1.4 ! root 413: `FUNCTION_PROLOGUE (FILE, SIZE)'
! 414: A C compound statement that outputs the assembler code for entry
! 415: to a function. The prologue is responsible for setting up the
! 416: stack frame, initializing the frame pointer register, saving
! 417: registers that must be saved, and allocating SIZE additional bytes
! 418: of storage for the local variables. SIZE is an integer. FILE is
! 419: a stdio stream to which the assembler code should be output.
! 420:
! 421: The label for the beginning of the function need not be output by
! 422: this macro. That has already been done when the macro is run.
! 423:
! 424: To determine which registers to save, the macro can refer to the
! 425: array `regs_ever_live': element R is nonzero if hard register R is
! 426: used anywhere within the function. This implies the function
! 427: prologue should save register R, provided it is not one of the
! 428: call-used registers. (`FUNCTION_EPILOGUE' must likewise use
! 429: `regs_ever_live'.)
! 430:
! 431: On machines that have "register windows", the function entry code
! 432: does not save on the stack the registers that are in the windows,
! 433: even if they are supposed to be preserved by function calls;
! 434: instead it takes appropriate steps to "push" the register stack,
! 435: if any non-call-used registers are used in the function.
! 436:
! 437: On machines where functions may or may not have frame-pointers, the
! 438: function entry code must vary accordingly; it must set up the frame
! 439: pointer if one is wanted, and not otherwise. To determine whether
! 440: a frame pointer is in wanted, the macro can refer to the variable
! 441: `frame_pointer_needed'. The variable's value will be 1 at run
! 442: time in a function that needs a frame pointer. *Note
! 443: Elimination::.
! 444:
! 445: The function entry code is responsible for allocating any stack
! 446: space required for the function. This stack space consists of the
! 447: regions listed below. In most cases, these regions are allocated
! 448: in the order listed, with the last listed region closest to the
! 449: top of the stack (the lowest address if `STACK_GROWS_DOWNWARD' is
! 450: defined, and the highest address if it is not defined). You can
! 451: use a different order for a machine if doing so is more convenient
! 452: or required for compatibility reasons. Except in cases where
! 453: required by standard or by a debugger, there is no reason why the
! 454: stack layout used by GCC need agree with that used by other
! 455: compilers for a machine.
! 456:
! 457: * A region of `current_function_pretend_args_size' bytes of
! 458: uninitialized space just underneath the first argument
! 459: arriving on the stack. (This may not be at the very start of
! 460: the allocated stack region if the calling sequence has pushed
! 461: anything else since pushing the stack arguments. But
! 462: usually, on such machines, nothing else has been pushed yet,
! 463: because the function prologue itself does all the pushing.)
! 464: This region is used on machines where an argument may be
! 465: passed partly in registers and partly in memory, and, in some
! 466: cases to support the features in `varargs.h' and `stdargs.h'.
! 467:
! 468: * An area of memory used to save certain registers used by the
! 469: function. The size of this area, which may also include
! 470: space for such things as the return address and pointers to
! 471: previous stack frames, is machine-specific and usually
! 472: depends on which registers have been used in the function.
! 473: Machines with register windows often do not require a save
! 474: area.
! 475:
! 476: * A region of at least SIZE bytes, possibly rounded up to an
! 477: allocation boundary, to contain the local variables of the
! 478: function. On some machines, this region and the save area
! 479: may occur in the opposite order, with the save area closer to
! 480: the top of the stack.
! 481:
! 482: * Optionally, when `ACCUMULATE_OUTGOING_ARGS' is defined, a
! 483: region of `current_function_outgoing_args_size' bytes to be
! 484: used for outgoing argument lists of the function. *Note
! 485: Stack Arguments::.
! 486:
! 487: Normally, it is necessary for the macros `FUNCTION_PROLOGUE' and
! 488: `FUNCTION_EPILOGUE' to treat leaf functions specially. The C
! 489: variable `leaf_function' is nonzero for such a function.
! 490:
! 491: `EXIT_IGNORE_STACK'
! 492: Define this macro as a C expression that is nonzero if the return
! 493: instruction or the function epilogue ignores the value of the stack
! 494: pointer; in other words, if it is safe to delete an instruction to
! 495: adjust the stack pointer before a return from the function.
! 496:
! 497: Note that this macro's value is relevant only for functions for
! 498: which frame pointers are maintained. It is never safe to delete a
! 499: final stack adjustment in a function that has no frame pointer,
! 500: and the compiler knows this regardless of `EXIT_IGNORE_STACK'.
! 501:
! 502: `FUNCTION_EPILOGUE (FILE, SIZE)'
! 503: A C compound statement that outputs the assembler code for exit
! 504: from a function. The epilogue is responsible for restoring the
! 505: saved registers and stack pointer to their values when the
! 506: function was called, and returning control to the caller. This
! 507: macro takes the same arguments as the macro `FUNCTION_PROLOGUE',
! 508: and the registers to restore are determined from `regs_ever_live'
! 509: and `CALL_USED_REGISTERS' in the same way.
! 510:
! 511: On some machines, there is a single instruction that does all the
! 512: work of returning from the function. On these machines, give that
! 513: instruction the name `return' and do not define the macro
! 514: `FUNCTION_EPILOGUE' at all.
! 515:
! 516: Do not define a pattern named `return' if you want the
! 517: `FUNCTION_EPILOGUE' to be used. If you want the target switches
! 518: to control whether return instructions or epilogues are used,
! 519: define a `return' pattern with a validity condition that tests the
! 520: target switches appropriately. If the `return' pattern's validity
! 521: condition is false, epilogues will be used.
! 522:
! 523: On machines where functions may or may not have frame-pointers, the
! 524: function exit code must vary accordingly. Sometimes the code for
! 525: these two cases is completely different. To determine whether a
! 526: frame pointer is wanted, the macro can refer to the variable
! 527: `frame_pointer_needed'. The variable's value will be 1 when
! 528: compiling a function that needs a frame pointer.
! 529:
! 530: Normally, `FUNCTION_PROLOGUE' and `FUNCTION_EPILOGUE' must treat
! 531: leaf functions specially. The C variable `leaf_function' is
! 532: nonzero for such a function. *Note Leaf Functions::.
! 533:
! 534: On some machines, some functions pop their arguments on exit while
! 535: others leave that for the caller to do. For example, the 68020
! 536: when given `-mrtd' pops arguments in functions that take a fixed
! 537: number of arguments.
! 538:
! 539: Your definition of the macro `RETURN_POPS_ARGS' decides which
! 540: functions pop their own arguments. `FUNCTION_EPILOGUE' needs to
! 541: know what was decided. The variable that is called
! 542: `current_function_pops_args' is the number of bytes of its
! 543: arguments that a function should pop. *Note Scalar Return::.
! 544:
! 545: `DELAY_SLOTS_FOR_EPILOGUE'
! 546: Define this macro if the function epilogue contains delay slots to
! 547: which instructions from the rest of the function can be "moved".
! 548: The definition should be a C expression whose value is an integer
! 549: representing the number of delay slots there.
! 550:
! 551: `ELIGIBLE_FOR_EPILOGUE_DELAY (INSN, N)'
! 552: A C expression that returns 1 if INSN can be placed in delay slot
! 553: number N of the epilogue.
! 554:
! 555: The argument N is an integer which identifies the delay slot now
! 556: being considered (since different slots may have different rules of
! 557: eligibility). It is never negative and is always less than the
! 558: number of epilogue delay slots (what `DELAY_SLOTS_FOR_EPILOGUE'
! 559: returns). If you reject a particular insn for a given delay slot,
! 560: in principle, it may be reconsidered for a subsequent delay slot.
! 561: Also, other insns may (at least in principle) be considered for
! 562: the so far unfilled delay slot.
! 563:
! 564: The insns accepted to fill the epilogue delay slots are put in an
! 565: RTL list made with `insn_list' objects, stored in the variable
! 566: `current_function_epilogue_delay_list'. The insn for the first
! 567: delay slot comes first in the list. Your definition of the macro
! 568: `FUNCTION_EPILOGUE' should fill the delay slots by outputting the
! 569: insns in this list, usually by calling `final_scan_insn'.
1.1.1.3 root 570:
1.1.1.4 ! root 571: You need not define this macro if you did not define
! 572: `DELAY_SLOTS_FOR_EPILOGUE'.
1.1.1.3 root 573:
574:
1.1.1.4 ! root 575: File: gcc.info, Node: Profiling, Prev: Function Entry, Up: Stack and Calling
1.1.1.3 root 576:
1.1.1.4 ! root 577: Generating Code for Profiling
! 578: -----------------------------
1.1.1.3 root 579:
1.1.1.4 ! root 580: These macros will help you generate code for profiling.
1.1.1.3 root 581:
1.1.1.4 ! root 582: `FUNCTION_PROFILER (FILE, LABELNO)'
! 583: A C statement or compound statement to output to FILE some
! 584: assembler code to call the profiling subroutine `mcount'. Before
! 585: calling, the assembler code must load the address of a counter
! 586: variable into a register where `mcount' expects to find the
! 587: address. The name of this variable is `LP' followed by the number
! 588: LABELNO, so you would generate the name using `LP%d' in a
! 589: `fprintf'.
! 590:
! 591: The details of how the address should be passed to `mcount' are
! 592: determined by your operating system environment, not by GNU CC. To
! 593: figure them out, compile a small program for profiling using the
! 594: system's installed C compiler and look at the assembler code that
! 595: results.
! 596:
! 597: `PROFILE_BEFORE_PROLOGUE'
! 598: Define this macro if the code for function profiling should come
! 599: before the function prologue. Normally, the profiling code comes
! 600: after.
! 601:
! 602: `FUNCTION_BLOCK_PROFILER (FILE, LABELNO)'
! 603: A C statement or compound statement to output to FILE some
! 604: assembler code to initialize basic-block profiling for the current
! 605: object module. This code should call the subroutine
! 606: `__bb_init_func' once per object module, passing it as its sole
! 607: argument the address of a block allocated in the object module.
! 608:
! 609: The name of the block is a local symbol made with this statement:
! 610:
! 611: ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 0);
! 612:
! 613: Of course, since you are writing the definition of
! 614: `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you
! 615: can take a short cut in the definition of this macro and use the
! 616: name that you know will result.
! 617:
! 618: The first word of this block is a flag which will be nonzero if the
! 619: object module has already been initialized. So test this word
! 620: first, and do not call `__bb_init_func' if the flag is nonzero.
! 621:
! 622: `BLOCK_PROFILER (FILE, BLOCKNO)'
! 623: A C statement or compound statement to increment the count
! 624: associated with the basic block number BLOCKNO. Basic blocks are
! 625: numbered separately from zero within each compilation. The count
! 626: associated with block number BLOCKNO is at index BLOCKNO in a
! 627: vector of words; the name of this array is a local symbol made
! 628: with this statement:
! 629:
! 630: ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 2);
! 631:
! 632: Of course, since you are writing the definition of
! 633: `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you
! 634: can take a short cut in the definition of this macro and use the
! 635: name that you know will result.
! 636:
! 637: `BLOCK_PROFILER_CODE'
! 638: A C function or functions which are needed in the library to
! 639: support block profiling.
1.1.1.2 root 640:
641:
1.1.1.4 ! root 642: File: gcc.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Target Macros
1.1.1.2 root 643:
1.1.1.4 ! root 644: Implementing the Varargs Macros
! 645: ===============================
1.1.1.2 root 646:
1.1.1.4 ! root 647: GNU CC comes with an implementation of `varargs.h' and `stdarg.h'
! 648: that work without change on machines that pass arguments on the stack.
! 649: Other machines require their own implementations of varargs, and the
! 650: two machine independent header files must have conditionals to include
! 651: it.
! 652:
! 653: ANSI `stdarg.h' differs from traditional `varargs.h' mainly in the
! 654: calling convention for `va_start'. The traditional implementation
! 655: takes just one argument, which is the variable in which to store the
! 656: argument pointer. The ANSI implementation of `va_start' takes an
! 657: additional second argument. The user is supposed to write the last
! 658: named argument of the function here.
! 659:
! 660: However, `va_start' should not use this argument. The way to find
! 661: the end of the named arguments is with the built-in functions described
! 662: below.
! 663:
! 664: `__builtin_saveregs ()'
! 665: Use this built-in function to save the argument registers in
! 666: memory so that the varargs mechanism can access them. Both ANSI
! 667: and traditional versions of `va_start' must use
! 668: `__builtin_saveregs', unless you use `SETUP_INCOMING_VARARGS' (see
! 669: below) instead.
! 670:
! 671: On some machines, `__builtin_saveregs' is open-coded under the
! 672: control of the macro `EXPAND_BUILTIN_SAVEREGS'. On other machines,
! 673: it calls a routine written in assembler language, found in
! 674: `libgcc2.c'.
! 675:
! 676: Code generated for the call to `__builtin_saveregs' appears at the
! 677: beginning of the function, as opposed to where the call to
! 678: `__builtin_saveregs' is written, regardless of what the code is.
! 679: This is because the registers must be saved before the function
! 680: starts to use them for its own purposes.
! 681:
! 682: `__builtin_args_info (CATEGORY)'
! 683: Use this built-in function to find the first anonymous arguments in
! 684: registers.
! 685:
! 686: In general, a machine may have several categories of registers
! 687: used for arguments, each for a particular category of data types.
! 688: (For example, on some machines, floating-point registers are used
! 689: for floating-point arguments while other arguments are passed in
! 690: the general registers.) To make non-varargs functions use the
! 691: proper calling convention, you have defined the `CUMULATIVE_ARGS'
! 692: data type to record how many registers in each category have been
! 693: used so far
! 694:
! 695: `__builtin_args_info' accesses the same data structure of type
! 696: `CUMULATIVE_ARGS' after the ordinary argument layout is finished
! 697: with it, with CATEGORY specifying which word to access. Thus, the
! 698: value indicates the first unused register in a given category.
! 699:
! 700: Normally, you would use `__builtin_args_info' in the implementation
! 701: of `va_start', accessing each category just once and storing the
! 702: value in the `va_list' object. This is because `va_list' will
! 703: have to update the values, and there is no way to alter the values
! 704: accessed by `__builtin_args_info'.
! 705:
! 706: `__builtin_next_arg (LASTARG)'
! 707: This is the equivalent of `__builtin_args_info', for stack
! 708: arguments. It returns the address of the first anonymous stack
! 709: argument, as type `void *'. If `ARGS_GROW_DOWNWARD', it returns
! 710: the address of the location above the first anonymous stack
! 711: argument. Use it in `va_start' to initialize the pointer for
! 712: fetching arguments from the stack. Also use it in `va_start' to
! 713: verify that the second parameter LASTARG is the last named argument
! 714: of the current function.
! 715:
! 716: `__builtin_classify_type (OBJECT)'
! 717: Since each machine has its own conventions for which data types are
! 718: passed in which kind of register, your implementation of `va_arg'
! 719: has to embody these conventions. The easiest way to categorize the
! 720: specified data type is to use `__builtin_classify_type' together
! 721: with `sizeof' and `__alignof__'.
! 722:
! 723: `__builtin_classify_type' ignores the value of OBJECT, considering
! 724: only its data type. It returns an integer describing what kind of
! 725: type that is--integer, floating, pointer, structure, and so on.
! 726:
! 727: The file `typeclass.h' defines an enumeration that you can use to
! 728: interpret the values of `__builtin_classify_type'.
! 729:
! 730: These machine description macros help implement varargs:
! 731:
! 732: `EXPAND_BUILTIN_SAVEREGS (ARGS)'
! 733: If defined, is a C expression that produces the machine-specific
! 734: code for a call to `__builtin_saveregs'. This code will be moved
! 735: to the very beginning of the function, before any parameter access
! 736: are made. The return value of this function should be an RTX that
! 737: contains the value to use as the return of `__builtin_saveregs'.
! 738:
! 739: The argument ARGS is a `tree_list' containing the arguments that
! 740: were passed to `__builtin_saveregs'.
! 741:
! 742: If this macro is not defined, the compiler will output an ordinary
! 743: call to the library function `__builtin_saveregs'.
! 744:
! 745: `SETUP_INCOMING_VARARGS (ARGS_SO_FAR, MODE, TYPE,'
! 746: PRETEND_ARGS_SIZE, SECOND_TIME) This macro offers an alternative
! 747: to using `__builtin_saveregs' and defining the macro
! 748: `EXPAND_BUILTIN_SAVEREGS'. Use it to store the anonymous register
! 749: arguments into the stack so that all the arguments appear to have
! 750: been passed consecutively on the stack. Once this is done, you
! 751: can use the standard implementation of varargs that works for
! 752: machines that pass all their arguments on the stack.
! 753:
! 754: The argument ARGS_SO_FAR is the `CUMULATIVE_ARGS' data structure,
! 755: containing the values that obtain after processing of the named
! 756: arguments. The arguments MODE and TYPE describe the last named
! 757: argument--its machine mode and its data type as a tree node.
! 758:
! 759: The macro implementation should do two things: first, push onto the
! 760: stack all the argument registers *not* used for the named
! 761: arguments, and second, store the size of the data thus pushed into
! 762: the `int'-valued variable whose name is supplied as the argument
! 763: PRETEND_ARGS_SIZE. The value that you store here will serve as
! 764: additional offset for setting up the stack frame.
! 765:
! 766: Because you must generate code to push the anonymous arguments at
! 767: compile time without knowing their data types,
! 768: `SETUP_INCOMING_VARARGS' is only useful on machines that have just
! 769: a single category of argument register and use it uniformly for
! 770: all data types.
! 771:
! 772: If the argument SECOND_TIME is nonzero, it means that the
! 773: arguments of the function are being analyzed for the second time.
! 774: This happens for an inline function, which is not actually
! 775: compiled until the end of the source file. The macro
! 776: `SETUP_INCOMING_VARARGS' should not generate any instructions in
! 777: this case.
! 778:
! 779: `STRICT_ARGUMENT_NAMING'
! 780: Define this macro if the location where a function argument is
! 781: passed depends on whether or not it is a named argument.
! 782:
! 783: This macro controls how the NAMED argument to `FUNCTION_ARG' is
! 784: set for varargs and stdarg functions. With this macro defined,
! 785: the NAMED argument is always true for named arguments, and false
! 786: for unnamed arguments. If this is not defined, but
! 787: `SETUP_INCOMING_VARARGS' is defined, then all arguments are
! 788: treated as named. Otherwise, all named arguments except the last
! 789: are treated as named.
! 790:
! 791:
! 792: File: gcc.info, Node: Trampolines, Next: Library Calls, Prev: Varargs, Up: Target Macros
1.1.1.2 root 793:
1.1.1.4 ! root 794: Trampolines for Nested Functions
! 795: ================================
1.1.1.2 root 796:
1.1.1.4 ! root 797: A "trampoline" is a small piece of code that is created at run time
! 798: when the address of a nested function is taken. It normally resides on
! 799: the stack, in the stack frame of the containing function. These macros
! 800: tell GNU CC how to generate code to allocate and initialize a
! 801: trampoline.
! 802:
! 803: The instructions in the trampoline must do two things: load a
! 804: constant address into the static chain register, and jump to the real
! 805: address of the nested function. On CISC machines such as the m68k,
! 806: this requires two instructions, a move immediate and a jump. Then the
! 807: two addresses exist in the trampoline as word-long immediate operands.
! 808: On RISC machines, it is often necessary to load each address into a
! 809: register in two parts. Then pieces of each address form separate
! 810: immediate operands.
! 811:
! 812: The code generated to initialize the trampoline must store the
! 813: variable parts--the static chain value and the function address--into
! 814: the immediate operands of the instructions. On a CISC machine, this is
! 815: simply a matter of copying each address to a memory reference at the
! 816: proper offset from the start of the trampoline. On a RISC machine, it
! 817: may be necessary to take out pieces of the address and store them
! 818: separately.
! 819:
! 820: `TRAMPOLINE_TEMPLATE (FILE)'
! 821: A C statement to output, on the stream FILE, assembler code for a
! 822: block of data that contains the constant parts of a trampoline.
! 823: This code should not include a label--the label is taken care of
! 824: automatically.
! 825:
! 826: `TRAMPOLINE_SECTION'
! 827: The name of a subroutine to switch to the section in which the
! 828: trampoline template is to be placed (*note Sections::.). The
! 829: default is a value of `readonly_data_section', which places the
! 830: trampoline in the section containing read-only data.
! 831:
! 832: `TRAMPOLINE_SIZE'
! 833: A C expression for the size in bytes of the trampoline, as an
! 834: integer.
! 835:
! 836: `TRAMPOLINE_ALIGNMENT'
! 837: Alignment required for trampolines, in bits.
! 838:
! 839: If you don't define this macro, the value of `BIGGEST_ALIGNMENT'
! 840: is used for aligning trampolines.
! 841:
! 842: `INITIALIZE_TRAMPOLINE (ADDR, FNADDR, STATIC_CHAIN)'
! 843: A C statement to initialize the variable parts of a trampoline.
! 844: aDDR is an RTX for the address of the trampoline; FNADDR is an RTX
! 845: for the address of the nested function; STATIC_CHAIN is an RTX for
! 846: the static chain value that should be passed to the function when
! 847: it is called.
! 848:
! 849: `ALLOCATE_TRAMPOLINE (FP)'
! 850: A C expression to allocate run-time space for a trampoline. The
! 851: expression value should be an RTX representing a memory reference
! 852: to the space for the trampoline.
! 853:
! 854: If this macro is not defined, by default the trampoline is
! 855: allocated as a stack slot. This default is right for most
! 856: machines. The exceptions are machines where it is impossible to
! 857: execute instructions in the stack area. On such machines, you may
! 858: have to implement a separate stack, using this macro in
! 859: conjunction with `FUNCTION_PROLOGUE' and `FUNCTION_EPILOGUE'.
! 860:
! 861: FP points to a data structure, a `struct function', which
! 862: describes the compilation status of the immediate containing
! 863: function of the function which the trampoline is for. Normally
! 864: (when `ALLOCATE_TRAMPOLINE' is not defined), the stack slot for the
! 865: trampoline is in the stack frame of this containing function.
! 866: Other allocation strategies probably must do something analogous
! 867: with this information.
! 868:
! 869: Implementing trampolines is difficult on many machines because they
! 870: have separate instruction and data caches. Writing into a stack
! 871: location fails to clear the memory in the instruction cache, so when
! 872: the program jumps to that location, it executes the old contents.
! 873:
! 874: Here are two possible solutions. One is to clear the relevant parts
! 875: of the instruction cache whenever a trampoline is set up. The other is
! 876: to make all trampolines identical, by having them jump to a standard
! 877: subroutine. The former technique makes trampoline execution faster; the
! 878: latter makes initialization faster.
! 879:
! 880: To clear the instruction cache when a trampoline is initialized,
! 881: define the following macros which describe the shape of the cache.
! 882:
! 883: `INSN_CACHE_SIZE'
! 884: The total size in bytes of the cache.
! 885:
! 886: `INSN_CACHE_LINE_WIDTH'
! 887: The length in bytes of each cache line. The cache is divided into
! 888: cache lines which are disjoint slots, each holding a contiguous
! 889: chunk of data fetched from memory. Each time data is brought into
! 890: the cache, an entire line is read at once. The data loaded into a
! 891: cache line is always aligned on a boundary equal to the line size.
! 892:
! 893: `INSN_CACHE_DEPTH'
! 894: The number of alternative cache lines that can hold any particular
! 895: memory location.
! 896:
! 897: Alternatively, if the machine has system calls or instructions to
! 898: clear the instruction cache directly, you can define the following
! 899: macro.
! 900:
! 901: `CLEAR_INSN_CACHE (BEG, END)'
! 902: If defined, expands to a C expression clearing the *instruction
! 903: cache* in the specified interval. If it is not defined, and the
! 904: macro INSN_CACHE_SIZE is defined, some generic code is generated
! 905: to clear the cache. The definition of this macro would typically
! 906: be a series of `asm' statements. Both BEG and END are both pointer
! 907: expressions.
! 908:
! 909: To use a standard subroutine, define the following macro. In
! 910: addition, you must make sure that the instructions in a trampoline fill
! 911: an entire cache line with identical instructions, or else ensure that
! 912: the beginning of the trampoline code is always aligned at the same
! 913: point in its cache line. Look in `m68k.h' as a guide.
! 914:
! 915: `TRANSFER_FROM_TRAMPOLINE'
! 916: Define this macro if trampolines need a special subroutine to do
! 917: their work. The macro should expand to a series of `asm'
! 918: statements which will be compiled with GNU CC. They go in a
! 919: library function named `__transfer_from_trampoline'.
! 920:
! 921: If you need to avoid executing the ordinary prologue code of a
! 922: compiled C function when you jump to the subroutine, you can do so
! 923: by placing a special label of your own in the assembler code. Use
! 924: one `asm' statement to generate an assembler label, and another to
! 925: make the label global. Then trampolines can use that label to
! 926: jump directly to your special assembler code.
1.1 root 927:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.