![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-19 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / cc|
Return to gcc.info-19 CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: This is Info file gcc.info, produced by Makeinfo-1.54 from the input
2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
6: Published by the Free Software Foundation 675 Massachusetts Avenue
7: Cambridge, MA 02139 USA
8:
9: Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
10:
11: Permission is granted to make and distribute verbatim copies of this
12: manual provided the copyright notice and this permission notice are
13: preserved on all copies.
14:
15: Permission is granted to copy and distribute modified versions of
16: this manual under the conditions for verbatim copying, provided also
17: that the sections entitled "GNU General Public License" and "Protect
18: Your Freedom--Fight `Look And Feel'" are included exactly as in the
19: original, and provided that the entire resulting derived work is
20: distributed under the terms of a permission notice identical to this
21: one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that the sections entitled "GNU General Public
26: License" and "Protect Your Freedom--Fight `Look And Feel'", and this
27: permission notice, may be included in translations approved by the Free
28: Software Foundation instead of in the original English.
29:
30:
31: File: gcc.info, Node: Scalar Return, Next: Aggregate Return, Prev: Register Arguments, Up: Stack and Calling
32:
33: How Scalar Function Values Are Returned
34: ---------------------------------------
35:
36: This section discusses the macros that control returning scalars as
37: values--values that can fit in registers.
38:
39: `TRADITIONAL_RETURN_FLOAT'
40: Define this macro if `-traditional' should not cause functions
41: declared to return `float' to convert the value to `double'.
42:
43: `FUNCTION_VALUE (VALTYPE, FUNC)'
44: A C expression to create an RTX representing the place where a
45: function returns a value of data type VALTYPE. VALTYPE is a tree
46: node representing a data type. Write `TYPE_MODE (VALTYPE)' to get
47: the machine mode used to represent that type. On many machines,
48: only the mode is relevant. (Actually, on most machines, scalar
49: values are returned in the same place regardless of mode).
50:
51: If `PROMOTE_FUNCTION_RETURN' is defined, you must apply the same
52: promotion rules specified in `PROMOTE_MODE' if VALTYPE is a scalar
53: type.
54:
55: If the precise function being called is known, FUNC is a tree node
56: (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
57: makes it possible to use a different value-returning convention
58: for specific functions when all their calls are known.
59:
60: `FUNCTION_VALUE' is not used for return vales with aggregate data
61: types, because these are returned in another way. See
62: `STRUCT_VALUE_REGNUM' and related macros, below.
63:
64: `FUNCTION_OUTGOING_VALUE (VALTYPE, FUNC)'
65: Define this macro if the target machine has "register windows" so
66: that the register in which a function returns its value is not the
67: same as the one in which the caller sees the value.
68:
69: For such machines, `FUNCTION_VALUE' computes the register in which
70: the caller will see the value. `FUNCTION_OUTGOING_VALUE' should be
71: defined in a similar fashion to tell the function where to put the
72: value.
73:
74: If `FUNCTION_OUTGOING_VALUE' is not defined, `FUNCTION_VALUE'
75: serves both purposes.
76:
77: `FUNCTION_OUTGOING_VALUE' is not used for return vales with
78: aggregate data types, because these are returned in another way.
79: See `STRUCT_VALUE_REGNUM' and related macros, below.
80:
81: `LIBCALL_VALUE (MODE)'
82: A C expression to create an RTX representing the place where a
83: library function returns a value of mode MODE. If the precise
84: function being called is known, FUNC is a tree node
85: (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
86: makes it possible to use a different value-returning convention
87: for specific functions when all their calls are known.
88:
89: Note that "library function" in this context means a compiler
90: support routine, used to perform arithmetic, whose name is known
91: specially by the compiler and was not mentioned in the C code being
92: compiled.
93:
94: The definition of `LIBRARY_VALUE' need not be concerned aggregate
95: data types, because none of the library functions returns such
96: types.
97:
98: `FUNCTION_VALUE_REGNO_P (REGNO)'
99: A C expression that is nonzero if REGNO is the number of a hard
100: register in which the values of called function may come back.
101:
102: A register whose use for returning values is limited to serving as
103: the second of a pair (for a value of type `double', say) need not
104: be recognized by this macro. So for most machines, this definition
105: suffices:
106:
107: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
108:
109: If the machine has register windows, so that the caller and the
110: called function use different registers for the return value, this
111: macro should recognize only the caller's register numbers.
112:
113: `APPLY_RESULT_SIZE'
114: Define this macro if `untyped_call' and `untyped_return' need more
115: space than is implied by `FUNCTION_VALUE_REGNO_P' for saving and
116: restoring an arbitrary return value.
117:
118:
119: File: gcc.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling
120:
121: How Large Values Are Returned
122: -----------------------------
123:
124: When a function value's mode is `BLKmode' (and in some other cases),
125: the value is not returned according to `FUNCTION_VALUE' (*note Scalar
126: Return::.). Instead, the caller passes the address of a block of
127: memory in which the value should be stored. This address is called the
128: "structure value address".
129:
130: This section describes how to control returning structure values in
131: memory.
132:
133: `RETURN_IN_MEMORY (TYPE)'
134: A C expression which can inhibit the returning of certain function
135: values in registers, based on the type of value. A nonzero value
136: says to return the function value in memory, just as large
137: structures are always returned. Here TYPE will be a C expression
138: of type `tree', representing the data type of the value.
139:
140: Note that values of mode `BLKmode' must be explicitly handled by
141: this macro. Also, the option `-fpcc-struct-return' takes effect
142: regardless of this macro. On most systems, it is possible to
143: leave the macro undefined; this causes a default definition to be
144: used, whose value is the constant 1 for `BLKmode' values, and 0
145: otherwise.
146:
147: Do not use this macro to indicate that structures and unions
148: should always be returned in memory. You should instead use
149: `DEFAULT_PCC_STRUCT_RETURN' to indicate this.
150:
151: `DEFAULT_PCC_STRUCT_RETURN'
152: Define this macro to be 1 if all structure and union return values
153: must be in memory. Since this results in slower code, this should
154: be defined only if needed for compatibility with other compilers
155: or with an ABI. If you define this macro to be 0, then the
156: conventions used for structure and union return values are decided
157: by the `RETURN_IN_MEMORY' macro.
158:
159: If not defined, this defaults to the value 1.
160:
161: `STRUCT_VALUE_REGNUM'
162: If the structure value address is passed in a register, then
163: `STRUCT_VALUE_REGNUM' should be the number of that register.
164:
165: `STRUCT_VALUE'
166: If the structure value address is not passed in a register, define
167: `STRUCT_VALUE' as an expression returning an RTX for the place
168: where the address is passed. If it returns 0, the address is
169: passed as an "invisible" first argument.
170:
171: `STRUCT_VALUE_INCOMING_REGNUM'
172: On some architectures the place where the structure value address
173: is found by the called function is not the same place that the
174: caller put it. This can be due to register windows, or it could
175: be because the function prologue moves it to a different place.
176:
177: If the incoming location of the structure value address is in a
178: register, define this macro as the register number.
179:
180: `STRUCT_VALUE_INCOMING'
181: If the incoming location is not a register, then you should define
182: `STRUCT_VALUE_INCOMING' as an expression for an RTX for where the
183: called function should find the value. If it should find the
184: value on the stack, define this to create a `mem' which refers to
185: the frame pointer. A definition of 0 means that the address is
186: passed as an "invisible" first argument.
187:
188: `PCC_STATIC_STRUCT_RETURN'
189: Define this macro if the usual system convention on the target
190: machine for returning structures and unions is for the called
191: function to return the address of a static variable containing the
192: value.
193:
194: Do not define this if the usual system convention is for the
195: caller to pass an address to the subroutine.
196:
197: This macro has effect in `-fpcc-struct-return' mode, but not in
198: `-freg-struct-return' mode.
199:
200:
201: File: gcc.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling
202:
203: Caller-Saves Register Allocation
204: --------------------------------
205:
206: If you enable it, GNU CC can save registers around function calls.
207: This makes it possible to use call-clobbered registers to hold
208: variables that must live across calls.
209:
210: `DEFAULT_CALLER_SAVES'
211: Define this macro if function calls on the target machine do not
212: preserve any registers; in other words, if `CALL_USED_REGISTERS'
213: has 1 for all registers. This macro enables `-fcaller-saves' by
214: default. Eventually that option will be enabled by default on all
215: machines and both the option and this macro will be eliminated.
216:
217: `CALLER_SAVE_PROFITABLE (REFS, CALLS)'
218: A C expression to determine whether it is worthwhile to consider
219: placing a pseudo-register in a call-clobbered hard register and
220: saving and restoring it around each function call. The expression
221: should be 1 when this is worth doing, and 0 otherwise.
222:
223: If you don't define this macro, a default is used which is good on
224: most machines: `4 * CALLS < REFS'.
225:
226:
227: File: gcc.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling
228:
229: Function Entry and Exit
230: -----------------------
231:
232: This section describes the macros that output function entry
233: ("prologue") and exit ("epilogue") code.
234:
235: `FUNCTION_PROLOGUE (FILE, SIZE)'
236: A C compound statement that outputs the assembler code for entry
237: to a function. The prologue is responsible for setting up the
238: stack frame, initializing the frame pointer register, saving
239: registers that must be saved, and allocating SIZE additional bytes
240: of storage for the local variables. SIZE is an integer. FILE is
241: a stdio stream to which the assembler code should be output.
242:
243: The label for the beginning of the function need not be output by
244: this macro. That has already been done when the macro is run.
245:
246: To determine which registers to save, the macro can refer to the
247: array `regs_ever_live': element R is nonzero if hard register R is
248: used anywhere within the function. This implies the function
249: prologue should save register R, provided it is not one of the
250: call-used registers. (`FUNCTION_EPILOGUE' must likewise use
251: `regs_ever_live'.)
252:
253: On machines that have "register windows", the function entry code
254: does not save on the stack the registers that are in the windows,
255: even if they are supposed to be preserved by function calls;
256: instead it takes appropriate steps to "push" the register stack,
257: if any non-call-used registers are used in the function.
258:
259: On machines where functions may or may not have frame-pointers, the
260: function entry code must vary accordingly; it must set up the frame
261: pointer if one is wanted, and not otherwise. To determine whether
262: a frame pointer is in wanted, the macro can refer to the variable
263: `frame_pointer_needed'. The variable's value will be 1 at run
264: time in a function that needs a frame pointer. *Note
265: Elimination::.
266:
267: The function entry code is responsible for allocating any stack
268: space required for the function. This stack space consists of the
269: regions listed below. In most cases, these regions are allocated
270: in the order listed, with the last listed region closest to the
271: top of the stack (the lowest address if `STACK_GROWS_DOWNWARD' is
272: defined, and the highest address if it is not defined). You can
273: use a different order for a machine if doing so is more convenient
274: or required for compatibility reasons. Except in cases where
275: required by standard or by a debugger, there is no reason why the
276: stack layout used by GCC need agree with that used by other
277: compilers for a machine.
278:
279: * A region of `current_function_pretend_args_size' bytes of
280: uninitialized space just underneath the first argument
281: arriving on the stack. (This may not be at the very start of
282: the allocated stack region if the calling sequence has pushed
283: anything else since pushing the stack arguments. But
284: usually, on such machines, nothing else has been pushed yet,
285: because the function prologue itself does all the pushing.)
286: This region is used on machines where an argument may be
287: passed partly in registers and partly in memory, and, in some
288: cases to support the features in `varargs.h' and `stdargs.h'.
289:
290: * An area of memory used to save certain registers used by the
291: function. The size of this area, which may also include
292: space for such things as the return address and pointers to
293: previous stack frames, is machine-specific and usually
294: depends on which registers have been used in the function.
295: Machines with register windows often do not require a save
296: area.
297:
298: * A region of at least SIZE bytes, possibly rounded up to an
299: allocation boundary, to contain the local variables of the
300: function. On some machines, this region and the save area
301: may occur in the opposite order, with the save area closer to
302: the top of the stack.
303:
304: * Optionally, when `ACCUMULATE_OUTGOING_ARGS' is defined, a
305: region of `current_function_outgoing_args_size' bytes to be
306: used for outgoing argument lists of the function. *Note
307: Stack Arguments::.
308:
309: Normally, it is necessary for the macros `FUNCTION_PROLOGUE' and
310: `FUNCTION_EPILOGUE' to treat leaf functions specially. The C
311: variable `leaf_function' is nonzero for such a function.
312:
313: `EXIT_IGNORE_STACK'
314: Define this macro as a C expression that is nonzero if the return
315: instruction or the function epilogue ignores the value of the stack
316: pointer; in other words, if it is safe to delete an instruction to
317: adjust the stack pointer before a return from the function.
318:
319: Note that this macro's value is relevant only for functions for
320: which frame pointers are maintained. It is never safe to delete a
321: final stack adjustment in a function that has no frame pointer,
322: and the compiler knows this regardless of `EXIT_IGNORE_STACK'.
323:
324: `FUNCTION_EPILOGUE (FILE, SIZE)'
325: A C compound statement that outputs the assembler code for exit
326: from a function. The epilogue is responsible for restoring the
327: saved registers and stack pointer to their values when the
328: function was called, and returning control to the caller. This
329: macro takes the same arguments as the macro `FUNCTION_PROLOGUE',
330: and the registers to restore are determined from `regs_ever_live'
331: and `CALL_USED_REGISTERS' in the same way.
332:
333: On some machines, there is a single instruction that does all the
334: work of returning from the function. On these machines, give that
335: instruction the name `return' and do not define the macro
336: `FUNCTION_EPILOGUE' at all.
337:
338: Do not define a pattern named `return' if you want the
339: `FUNCTION_EPILOGUE' to be used. If you want the target switches
340: to control whether return instructions or epilogues are used,
341: define a `return' pattern with a validity condition that tests the
342: target switches appropriately. If the `return' pattern's validity
343: condition is false, epilogues will be used.
344:
345: On machines where functions may or may not have frame-pointers, the
346: function exit code must vary accordingly. Sometimes the code for
347: these two cases is completely different. To determine whether a
348: frame pointer is wanted, the macro can refer to the variable
349: `frame_pointer_needed'. The variable's value will be 1 when
350: compiling a function that needs a frame pointer.
351:
352: Normally, `FUNCTION_PROLOGUE' and `FUNCTION_EPILOGUE' must treat
353: leaf functions specially. The C variable `leaf_function' is
354: nonzero for such a function. *Note Leaf Functions::.
355:
356: On some machines, some functions pop their arguments on exit while
357: others leave that for the caller to do. For example, the 68020
358: when given `-mrtd' pops arguments in functions that take a fixed
359: number of arguments.
360:
361: Your definition of the macro `RETURN_POPS_ARGS' decides which
362: functions pop their own arguments. `FUNCTION_EPILOGUE' needs to
363: know what was decided. The variable that is called
364: `current_function_pops_args' is the number of bytes of its
365: arguments that a function should pop. *Note Scalar Return::.
366:
367: `DELAY_SLOTS_FOR_EPILOGUE'
368: Define this macro if the function epilogue contains delay slots to
369: which instructions from the rest of the function can be "moved".
370: The definition should be a C expression whose value is an integer
371: representing the number of delay slots there.
372:
373: `ELIGIBLE_FOR_EPILOGUE_DELAY (INSN, N)'
374: A C expression that returns 1 if INSN can be placed in delay slot
375: number N of the epilogue.
376:
377: The argument N is an integer which identifies the delay slot now
378: being considered (since different slots may have different rules of
379: eligibility). It is never negative and is always less than the
380: number of epilogue delay slots (what `DELAY_SLOTS_FOR_EPILOGUE'
381: returns). If you reject a particular insn for a given delay slot,
382: in principle, it may be reconsidered for a subsequent delay slot.
383: Also, other insns may (at least in principle) be considered for
384: the so far unfilled delay slot.
385:
386: The insns accepted to fill the epilogue delay slots are put in an
387: RTL list made with `insn_list' objects, stored in the variable
388: `current_function_epilogue_delay_list'. The insn for the first
389: delay slot comes first in the list. Your definition of the macro
390: `FUNCTION_EPILOGUE' should fill the delay slots by outputting the
391: insns in this list, usually by calling `final_scan_insn'.
392:
393: You need not define this macro if you did not define
394: `DELAY_SLOTS_FOR_EPILOGUE'.
395:
396:
397: File: gcc.info, Node: Profiling, Prev: Function Entry, Up: Stack and Calling
398:
399: Generating Code for Profiling
400: -----------------------------
401:
402: These macros will help you generate code for profiling.
403:
404: `FUNCTION_PROFILER (FILE, LABELNO)'
405: A C statement or compound statement to output to FILE some
406: assembler code to call the profiling subroutine `mcount'. Before
407: calling, the assembler code must load the address of a counter
408: variable into a register where `mcount' expects to find the
409: address. The name of this variable is `LP' followed by the number
410: LABELNO, so you would generate the name using `LP%d' in a
411: `fprintf'.
412:
413: The details of how the address should be passed to `mcount' are
414: determined by your operating system environment, not by GNU CC. To
415: figure them out, compile a small program for profiling using the
416: system's installed C compiler and look at the assembler code that
417: results.
418:
419: `PROFILE_BEFORE_PROLOGUE'
420: Define this macro if the code for function profiling should come
421: before the function prologue. Normally, the profiling code comes
422: after.
423:
424: `FUNCTION_BLOCK_PROFILER (FILE, LABELNO)'
425: A C statement or compound statement to output to FILE some
426: assembler code to initialize basic-block profiling for the current
427: object module. This code should call the subroutine
428: `__bb_init_func' once per object module, passing it as its sole
429: argument the address of a block allocated in the object module.
430:
431: The name of the block is a local symbol made with this statement:
432:
433: ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 0);
434:
435: Of course, since you are writing the definition of
436: `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you
437: can take a short cut in the definition of this macro and use the
438: name that you know will result.
439:
440: The first word of this block is a flag which will be nonzero if the
441: object module has already been initialized. So test this word
442: first, and do not call `__bb_init_func' if the flag is nonzero.
443:
444: `BLOCK_PROFILER (FILE, BLOCKNO)'
445: A C statement or compound statement to increment the count
446: associated with the basic block number BLOCKNO. Basic blocks are
447: numbered separately from zero within each compilation. The count
448: associated with block number BLOCKNO is at index BLOCKNO in a
449: vector of words; the name of this array is a local symbol made
450: with this statement:
451:
452: ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 2);
453:
454: Of course, since you are writing the definition of
455: `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you
456: can take a short cut in the definition of this macro and use the
457: name that you know will result.
458:
459: `BLOCK_PROFILER_CODE'
460: A C function or functions which are needed in the library to
461: support block profiling.
462:
463:
464: File: gcc.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Target Macros
465:
466: Implementing the Varargs Macros
467: ===============================
468:
469: GNU CC comes with an implementation of `varargs.h' and `stdarg.h'
470: that work without change on machines that pass arguments on the stack.
471: Other machines require their own implementations of varargs, and the
472: two machine independent header files must have conditionals to include
473: it.
474:
475: ANSI `stdarg.h' differs from traditional `varargs.h' mainly in the
476: calling convention for `va_start'. The traditional implementation
477: takes just one argument, which is the variable in which to store the
478: argument pointer. The ANSI implementation of `va_start' takes an
479: additional second argument. The user is supposed to write the last
480: named argument of the function here.
481:
482: However, `va_start' should not use this argument. The way to find
483: the end of the named arguments is with the built-in functions described
484: below.
485:
486: `__builtin_saveregs ()'
487: Use this built-in function to save the argument registers in
488: memory so that the varargs mechanism can access them. Both ANSI
489: and traditional versions of `va_start' must use
490: `__builtin_saveregs', unless you use `SETUP_INCOMING_VARARGS' (see
491: below) instead.
492:
493: On some machines, `__builtin_saveregs' is open-coded under the
494: control of the macro `EXPAND_BUILTIN_SAVEREGS'. On other machines,
495: it calls a routine written in assembler language, found in
496: `libgcc2.c'.
497:
498: Code generated for the call to `__builtin_saveregs' appears at the
499: beginning of the function, as opposed to where the call to
500: `__builtin_saveregs' is written, regardless of what the code is.
501: This is because the registers must be saved before the function
502: starts to use them for its own purposes.
503:
504: `__builtin_args_info (CATEGORY)'
505: Use this built-in function to find the first anonymous arguments in
506: registers.
507:
508: In general, a machine may have several categories of registers
509: used for arguments, each for a particular category of data types.
510: (For example, on some machines, floating-point registers are used
511: for floating-point arguments while other arguments are passed in
512: the general registers.) To make non-varargs functions use the
513: proper calling convention, you have defined the `CUMULATIVE_ARGS'
514: data type to record how many registers in each category have been
515: used so far
516:
517: `__builtin_args_info' accesses the same data structure of type
518: `CUMULATIVE_ARGS' after the ordinary argument layout is finished
519: with it, with CATEGORY specifying which word to access. Thus, the
520: value indicates the first unused register in a given category.
521:
522: Normally, you would use `__builtin_args_info' in the implementation
523: of `va_start', accessing each category just once and storing the
524: value in the `va_list' object. This is because `va_list' will
525: have to update the values, and there is no way to alter the values
526: accessed by `__builtin_args_info'.
527:
528: `__builtin_next_arg ()'
529: This is the equivalent of `__builtin_args_info', for stack
530: arguments. It returns the address of the first anonymous stack
531: argument, as type `void *'. If `ARGS_GROW_DOWNWARD', it returns
532: the address of the location above the first anonymous stack
533: argument. Use it in `va_start' to initialize the pointer for
534: fetching arguments from the stack.
535:
536: `__builtin_classify_type (OBJECT)'
537: Since each machine has its own conventions for which data types are
538: passed in which kind of register, your implementation of `va_arg'
539: has to embody these conventions. The easiest way to categorize the
540: specified data type is to use `__builtin_classify_type' together
541: with `sizeof' and `__alignof__'.
542:
543: `__builtin_classify_type' ignores the value of OBJECT, considering
544: only its data type. It returns an integer describing what kind of
545: type that is--integer, floating, pointer, structure, and so on.
546:
547: The file `typeclass.h' defines an enumeration that you can use to
548: interpret the values of `__builtin_classify_type'.
549:
550: These machine description macros help implement varargs:
551:
552: `EXPAND_BUILTIN_SAVEREGS (ARGS)'
553: If defined, is a C expression that produces the machine-specific
554: code for a call to `__builtin_saveregs'. This code will be moved
555: to the very beginning of the function, before any parameter access
556: are made. The return value of this function should be an RTX that
557: contains the value to use as the return of `__builtin_saveregs'.
558:
559: The argument ARGS is a `tree_list' containing the arguments that
560: were passed to `__builtin_saveregs'.
561:
562: If this macro is not defined, the compiler will output an ordinary
563: call to the library function `__builtin_saveregs'.
564:
565: `SETUP_INCOMING_VARARGS (ARGS_SO_FAR, MODE, TYPE,'
566: PRETEND_ARGS_SIZE, SECOND_TIME) This macro offers an alternative
567: to using `__builtin_saveregs' and defining the macro
568: `EXPAND_BUILTIN_SAVEREGS'. Use it to store the anonymous register
569: arguments into the stack so that all the arguments appear to have
570: been passed consecutively on the stack. Once this is done, you
571: can use the standard implementation of varargs that works for
572: machines that pass all their arguments on the stack.
573:
574: The argument ARGS_SO_FAR is the `CUMULATIVE_ARGS' data structure,
575: containing the values that obtain after processing of the named
576: arguments. The arguments MODE and TYPE describe the last named
577: argument--its machine mode and its data type as a tree node.
578:
579: The macro implementation should do two things: first, push onto the
580: stack all the argument registers *not* used for the named
581: arguments, and second, store the size of the data thus pushed into
582: the `int'-valued variable whose name is supplied as the argument
583: PRETEND_ARGS_SIZE. The value that you store here will serve as
584: additional offset for setting up the stack frame.
585:
586: Because you must generate code to push the anonymous arguments at
587: compile time without knowing their data types,
588: `SETUP_INCOMING_VARARGS' is only useful on machines that have just
589: a single category of argument register and use it uniformly for
590: all data types.
591:
592: If the argument SECOND_TIME is nonzero, it means that the
593: arguments of the function are being analyzed for the second time.
594: This happens for an inline function, which is not actually
595: compiled until the end of the source file. The macro
596: `SETUP_INCOMING_VARARGS' should not generate any instructions in
597: this case.
598:
599:
600: File: gcc.info, Node: Trampolines, Next: Library Calls, Prev: Varargs, Up: Target Macros
601:
602: Trampolines for Nested Functions
603: ================================
604:
605: A "trampoline" is a small piece of code that is created at run time
606: when the address of a nested function is taken. It normally resides on
607: the stack, in the stack frame of the containing function. These macros
608: tell GNU CC how to generate code to allocate and initialize a
609: trampoline.
610:
611: The instructions in the trampoline must do two things: load a
612: constant address into the static chain register, and jump to the real
613: address of the nested function. On CISC machines such as the m68k,
614: this requires two instructions, a move immediate and a jump. Then the
615: two addresses exist in the trampoline as word-long immediate operands.
616: On RISC machines, it is often necessary to load each address into a
617: register in two parts. Then pieces of each address form separate
618: immediate operands.
619:
620: The code generated to initialize the trampoline must store the
621: variable parts--the static chain value and the function address--into
622: the immediate operands of the instructions. On a CISC machine, this is
623: simply a matter of copying each address to a memory reference at the
624: proper offset from the start of the trampoline. On a RISC machine, it
625: may be necessary to take out pieces of the address and store them
626: separately.
627:
628: `TRAMPOLINE_TEMPLATE (FILE)'
629: A C statement to output, on the stream FILE, assembler code for a
630: block of data that contains the constant parts of a trampoline.
631: This code should not include a label--the label is taken care of
632: automatically.
633:
634: `TRAMPOLINE_SECTION'
635: The name of a subroutine to switch to the section in which the
636: trampoline template is to be placed (*note Sections::.). The
637: default is a value of `readonly_data_section', which places the
638: trampoline in the section containing read-only data.
639:
640: `TRAMPOLINE_SIZE'
641: A C expression for the size in bytes of the trampoline, as an
642: integer.
643:
644: `TRAMPOLINE_ALIGNMENT'
645: Alignment required for trampolines, in bits.
646:
647: If you don't define this macro, the value of `BIGGEST_ALIGNMENT'
648: is used for aligning trampolines.
649:
650: `INITIALIZE_TRAMPOLINE (ADDR, FNADDR, STATIC_CHAIN)'
651: A C statement to initialize the variable parts of a trampoline.
652: aDDR is an RTX for the address of the trampoline; FNADDR is an RTX
653: for the address of the nested function; STATIC_CHAIN is an RTX for
654: the static chain value that should be passed to the function when
655: it is called.
656:
657: `ALLOCATE_TRAMPOLINE (FP)'
658: A C expression to allocate run-time space for a trampoline. The
659: expression value should be an RTX representing a memory reference
660: to the space for the trampoline.
661:
662: If this macro is not defined, by default the trampoline is
663: allocated as a stack slot. This default is right for most
664: machines. The exceptions are machines where it is impossible to
665: execute instructions in the stack area. On such machines, you may
666: have to implement a separate stack, using this macro in
667: conjunction with `FUNCTION_PROLOGUE' and `FUNCTION_EPILOGUE'.
668:
669: FP points to a data structure, a `struct function', which
670: describes the compilation status of the immediate containing
671: function of the function which the trampoline is for. Normally
672: (when `ALLOCATE_TRAMPOLINE' is not defined), the stack slot for the
673: trampoline is in the stack frame of this containing function.
674: Other allocation strategies probably must do something analogous
675: with this information.
676:
677: Implementing trampolines is difficult on many machines because they
678: have separate instruction and data caches. Writing into a stack
679: location fails to clear the memory in the instruction cache, so when
680: the program jumps to that location, it executes the old contents.
681:
682: Here are two possible solutions. One is to clear the relevant parts
683: of the instruction cache whenever a trampoline is set up. The other is
684: to make all trampolines identical, by having them jump to a standard
685: subroutine. The former technique makes trampoline execution faster; the
686: latter makes initialization faster.
687:
688: To clear the instruction cache when a trampoline is initialized,
689: define the following macros which describe the shape of the cache.
690:
691: `INSN_CACHE_SIZE'
692: The total size in bytes of the cache.
693:
694: `INSN_CACHE_LINE_WIDTH'
695: The length in bytes of each cache line. The cache is divided into
696: cache lines which are disjoint slots, each holding a contiguous
697: chunk of data fetched from memory. Each time data is brought into
698: the cache, an entire line is read at once. The data loaded into a
699: cache line is always aligned on a boundary equal to the line size.
700:
701: `INSN_CACHE_DEPTH'
702: The number of alternative cache lines that can hold any particular
703: memory location.
704:
705: Alternatively, if the machine has system calls or instructions to
706: clear the instruction cache directly, you can define the following
707: macro.
708:
709: `'
710: If defined, expands to a C expression clearing the *instruction
711: cache* in the specified interval. If it is not defined, and the
712: macro INSN_CACHE_SIZE is defined, some generic code is generated
713: to clear the cache. The definition of this macro would typically
714: be a series of `asm' statements. Both BEG and END are both pointer
715: expressions.
716:
717: To use a standard subroutine, define the following macro. In
718: addition, you must make sure that the instructions in a trampoline fill
719: an entire cache line with identical instructions, or else ensure that
720: the beginning of the trampoline code is always aligned at the same
721: point in its cache line. Look in `m68k.h' as a guide.
722:
723: `TRANSFER_FROM_TRAMPOLINE'
724: Define this macro if trampolines need a special subroutine to do
725: their work. The macro should expand to a series of `asm'
726: statements which will be compiled with GNU CC. They go in a
727: library function named `__transfer_from_trampoline'.
728:
729: If you need to avoid executing the ordinary prologue code of a
730: compiled C function when you jump to the subroutine, you can do so
731: by placing a special label of your own in the assembler code. Use
732: one `asm' statement to generate an assembler label, and another to
733: make the label global. Then trampolines can use that label to
734: jump directly to your special assembler code.
735:
736:
737: File: gcc.info, Node: Library Calls, Next: Addressing Modes, Prev: Trampolines, Up: Target Macros
738:
739: Implicit Calls to Library Routines
740: ==================================
741:
742: `MULSI3_LIBCALL'
743: A C string constant giving the name of the function to call for
744: multiplication of one signed full-word by another. If you do not
745: define this macro, the default name is used, which is `__mulsi3',
746: a function defined in `libgcc.a'.
747:
748: `DIVSI3_LIBCALL'
749: A C string constant giving the name of the function to call for
750: division of one signed full-word by another. If you do not define
751: this macro, the default name is used, which is `__divsi3', a
752: function defined in `libgcc.a'.
753:
754: `UDIVSI3_LIBCALL'
755: A C string constant giving the name of the function to call for
756: division of one unsigned full-word by another. If you do not
757: define this macro, the default name is used, which is `__udivsi3',
758: a function defined in `libgcc.a'.
759:
760: `MODSI3_LIBCALL'
761: A C string constant giving the name of the function to call for the
762: remainder in division of one signed full-word by another. If you
763: do not define this macro, the default name is used, which is
764: `__modsi3', a function defined in `libgcc.a'.
765:
766: `UMODSI3_LIBCALL'
767: A C string constant giving the name of the function to call for the
768: remainder in division of one unsigned full-word by another. If
769: you do not define this macro, the default name is used, which is
770: `__umodsi3', a function defined in `libgcc.a'.
771:
772: `MULDI3_LIBCALL'
773: A C string constant giving the name of the function to call for
774: multiplication of one signed double-word by another. If you do not
775: define this macro, the default name is used, which is `__muldi3',
776: a function defined in `libgcc.a'.
777:
778: `DIVDI3_LIBCALL'
779: A C string constant giving the name of the function to call for
780: division of one signed double-word by another. If you do not
781: define this macro, the default name is used, which is `__divdi3', a
782: function defined in `libgcc.a'.
783:
784: `UDIVDI3_LIBCALL'
785: A C string constant giving the name of the function to call for
786: division of one unsigned full-word by another. If you do not
787: define this macro, the default name is used, which is `__udivdi3',
788: a function defined in `libgcc.a'.
789:
790: `MODDI3_LIBCALL'
791: A C string constant giving the name of the function to call for the
792: remainder in division of one signed double-word by another. If
793: you do not define this macro, the default name is used, which is
794: `__moddi3', a function defined in `libgcc.a'.
795:
796: `UMODDI3_LIBCALL'
797: A C string constant giving the name of the function to call for the
798: remainder in division of one unsigned full-word by another. If
799: you do not define this macro, the default name is used, which is
800: `__umoddi3', a function defined in `libgcc.a'.
801:
802: `TARGET_EDOM'
803: The value of `EDOM' on the target machine, as a C integer constant
804: expression. If you don't define this macro, GNU CC does not
805: attempt to deposit the value of `EDOM' into `errno' directly.
806: Look in `/usr/include/errno.h' to find the value of `EDOM' on your
807: system.
808:
809: If you do not define `TARGET_EDOM', then compiled code reports
810: domain errors by calling the library function and letting it
811: report the error. If mathematical functions on your system use
812: `matherr' when there is an error, then you should leave
813: `TARGET_EDOM' undefined so that `matherr' is used normally.
814:
815: `GEN_ERRNO_RTX'
816: Define this macro as a C expression to create an rtl expression
817: that refers to the global "variable" `errno'. (On certain systems,
818: `errno' may not actually be a variable.) If you don't define this
819: macro, a reasonable default is used.
820:
821: `TARGET_MEM_FUNCTIONS'
822: Define this macro if GNU CC should generate calls to the System V
823: (and ANSI C) library functions `memcpy' and `memset' rather than
824: the BSD functions `bcopy' and `bzero'.
825:
826: `LIBGCC_NEEDS_DOUBLE'
827: Define this macro if only `float' arguments cannot be passed to
828: library routines (so they must be converted to `double'). This
829: macro affects both how library calls are generated and how the
830: library routines in `libgcc1.c' accept their arguments. It is
831: useful on machines where floating and fixed point arguments are
832: passed differently, such as the i860.
833:
834: `FLOAT_ARG_TYPE'
835: Define this macro to override the type used by the library
836: routines to pick up arguments of type `float'. (By default, they
837: use a union of `float' and `int'.)
838:
839: The obvious choice would be `float'--but that won't work with
840: traditional C compilers that expect all arguments declared as
841: `float' to arrive as `double'. To avoid this conversion, the
842: library routines ask for the value as some other type and then
843: treat it as a `float'.
844:
845: On some systems, no other type will work for this. For these
846: systems, you must use `LIBGCC_NEEDS_DOUBLE' instead, to force
847: conversion of the values `double' before they are passed.
848:
849: `FLOATIFY (PASSED-VALUE)'
850: Define this macro to override the way library routines redesignate
851: a `float' argument as a `float' instead of the type it was passed
852: as. The default is an expression which takes the `float' field of
853: the union.
854:
855: `FLOAT_VALUE_TYPE'
856: Define this macro to override the type used by the library
857: routines to return values that ought to have type `float'. (By
858: default, they use `int'.)
859:
860: The obvious choice would be `float'--but that won't work with
861: traditional C compilers gratuitously convert values declared as
862: `float' into `double'.
863:
864: `INTIFY (FLOAT-VALUE)'
865: Define this macro to override the way the value of a
866: `float'-returning library routine should be packaged in order to
867: return it. These functions are actually declared to return type
868: `FLOAT_VALUE_TYPE' (normally `int').
869:
870: These values can't be returned as type `float' because traditional
871: C compilers would gratuitously convert the value to a `double'.
872:
873: A local variable named `intify' is always available when the macro
874: `INTIFY' is used. It is a union of a `float' field named `f' and
875: a field named `i' whose type is `FLOAT_VALUE_TYPE' or `int'.
876:
877: If you don't define this macro, the default definition works by
878: copying the value through that union.
879:
880: `nongcc_SI_type'
881: Define this macro as the name of the data type corresponding to
882: `SImode' in the system's own C compiler.
883:
884: You need not define this macro if that type is `long int', as it
885: usually is.
886:
887: `nongcc_word_type'
888: Define this macro as the name of the data type corresponding to the
889: word_mode in the system's own C compiler.
890:
891: You need not define this macro if that type is `long int', as it
892: usually is.
893:
894: `perform_...'
895: Define these macros to supply explicit C statements to carry out
896: various arithmetic operations on types `float' and `double' in the
897: library routines in `libgcc1.c'. See that file for a full list of
898: these macros and their arguments.
899:
900: On most machines, you don't need to define any of these macros,
901: because the C compiler that comes with the system takes care of
902: doing them.
903:
904: `NEXT_OBJC_RUNTIME'
905: Define this macro to generate code for Objective C message sending
906: using the calling convention of the NeXT system. This calling
907: convention involves passing the object, the selector and the
908: method arguments all at once to the method-lookup library function.
909:
910: The default calling convention passes just the object and the
911: selector to the lookup function, which returns a pointer to the
912: method.
913:
914:
915: File: gcc.info, Node: Addressing Modes, Next: Condition Code, Prev: Library Calls, Up: Target Macros
916:
917: Addressing Modes
918: ================
919:
920: `HAVE_POST_INCREMENT'
921: Define this macro if the machine supports post-increment
922: addressing.
923:
924: `HAVE_PRE_INCREMENT'
925: `HAVE_POST_DECREMENT'
926: `HAVE_PRE_DECREMENT'
927: Similar for other kinds of addressing.
928:
929: `CONSTANT_ADDRESS_P (X)'
930: A C expression that is 1 if the RTX X is a constant which is a
931: valid address. On most machines, this can be defined as
932: `CONSTANT_P (X)', but a few machines are more restrictive in which
933: constant addresses are supported.
934:
935: `CONSTANT_P' accepts integer-values expressions whose values are
936: not explicitly known, such as `symbol_ref', `label_ref', and
937: `high' expressions and `const' arithmetic expressions, in addition
938: to `const_int' and `const_double' expressions.
939:
940: `MAX_REGS_PER_ADDRESS'
941: A number, the maximum number of registers that can appear in a
942: valid memory address. Note that it is up to you to specify a
943: value equal to the maximum number that `GO_IF_LEGITIMATE_ADDRESS'
944: would ever accept.
945:
946: `GO_IF_LEGITIMATE_ADDRESS (MODE, X, LABEL)'
947: A C compound statement with a conditional `goto LABEL;' executed
948: if X (an RTX) is a legitimate memory address on the target machine
949: for a memory operand of mode MODE.
950:
951: It usually pays to define several simpler macros to serve as
952: subroutines for this one. Otherwise it may be too complicated to
953: understand.
954:
955: This macro must exist in two variants: a strict variant and a
956: non-strict one. The strict variant is used in the reload pass. It
957: must be defined so that any pseudo-register that has not been
958: allocated a hard register is considered a memory reference. In
959: contexts where some kind of register is required, a pseudo-register
960: with no hard register must be rejected.
961:
962: The non-strict variant is used in other passes. It must be
963: defined to accept all pseudo-registers in every context where some
964: kind of register is required.
965:
966: Compiler source files that want to use the strict variant of this
967: macro define the macro `REG_OK_STRICT'. You should use an `#ifdef
968: REG_OK_STRICT' conditional to define the strict variant in that
969: case and the non-strict variant otherwise.
970:
971: Subroutines to check for acceptable registers for various purposes
972: (one for base registers, one for index registers, and so on) are
973: typically among the subroutines used to define
974: `GO_IF_LEGITIMATE_ADDRESS'. Then only these subroutine macros
975: need have two variants; the higher levels of macros may be the
976: same whether strict or not.
977:
978: Normally, constant addresses which are the sum of a `symbol_ref'
979: and an integer are stored inside a `const' RTX to mark them as
980: constant. Therefore, there is no need to recognize such sums
981: specifically as legitimate addresses. Normally you would simply
982: recognize any `const' as legitimate.
983:
984: Usually `PRINT_OPERAND_ADDRESS' is not prepared to handle constant
985: sums that are not marked with `const'. It assumes that a naked
986: `plus' indicates indexing. If so, then you *must* reject such
987: naked constant sums as illegitimate addresses, so that none of
988: them will be given to `PRINT_OPERAND_ADDRESS'.
989:
990: On some machines, whether a symbolic address is legitimate depends
991: on the section that the address refers to. On these machines,
992: define the macro `ENCODE_SECTION_INFO' to store the information
993: into the `symbol_ref', and then check for it here. When you see a
994: `const', you will have to look inside it to find the `symbol_ref'
995: in order to determine the section. *Note Assembler Format::.
996:
997: The best way to modify the name string is by adding text to the
998: beginning, with suitable punctuation to prevent any ambiguity.
999: Allocate the new name in `saveable_obstack'. You will have to
1000: modify `ASM_OUTPUT_LABELREF' to remove and decode the added text
1001: and output the name accordingly, and define `STRIP_NAME_ENCODING'
1002: to access the original name string.
1003:
1004: You can check the information stored here into the `symbol_ref' in
1005: the definitions of the macros `GO_IF_LEGITIMATE_ADDRESS' and
1006: `PRINT_OPERAND_ADDRESS'.
1007:
1008: `REG_OK_FOR_BASE_P (X)'
1009: A C expression that is nonzero if X (assumed to be a `reg' RTX) is
1010: valid for use as a base register. For hard registers, it should
1011: always accept those which the hardware permits and reject the
1012: others. Whether the macro accepts or rejects pseudo registers
1013: must be controlled by `REG_OK_STRICT' as described above. This
1014: usually requires two variant definitions, of which `REG_OK_STRICT'
1015: controls the one actually used.
1016:
1017: `REG_OK_FOR_INDEX_P (X)'
1018: A C expression that is nonzero if X (assumed to be a `reg' RTX) is
1019: valid for use as an index register.
1020:
1021: The difference between an index register and a base register is
1022: that the index register may be scaled. If an address involves the
1023: sum of two registers, neither one of them scaled, then either one
1024: may be labeled the "base" and the other the "index"; but whichever
1025: labeling is used must fit the machine's constraints of which
1026: registers may serve in each capacity. The compiler will try both
1027: labelings, looking for one that is valid, and will reload one or
1028: both registers only if neither labeling works.
1029:
1030: `LEGITIMIZE_ADDRESS (X, OLDX, MODE, WIN)'
1031: A C compound statement that attempts to replace X with a valid
1032: memory address for an operand of mode MODE. WIN will be a C
1033: statement label elsewhere in the code; the macro definition may use
1034:
1035: GO_IF_LEGITIMATE_ADDRESS (MODE, X, WIN);
1036:
1037: to avoid further processing if the address has become legitimate.
1038:
1039: X will always be the result of a call to `break_out_memory_refs',
1040: and OLDX will be the operand that was given to that function to
1041: produce X.
1042:
1043: The code generated by this macro should not alter the substructure
1044: of X. If it transforms X into a more legitimate form, it should
1045: assign X (which will always be a C variable) a new value.
1046:
1047: It is not necessary for this macro to come up with a legitimate
1048: address. The compiler has standard ways of doing so in all cases.
1049: In fact, it is safe for this macro to do nothing. But often a
1050: machine-dependent strategy can generate better code.
1051:
1052: `GO_IF_MODE_DEPENDENT_ADDRESS (ADDR, LABEL)'
1053: A C statement or compound statement with a conditional `goto
1054: LABEL;' executed if memory address X (an RTX) can have different
1055: meanings depending on the machine mode of the memory reference it
1056: is used for or if the address is valid for some modes but not
1057: others.
1058:
1059: Autoincrement and autodecrement addresses typically have
1060: mode-dependent effects because the amount of the increment or
1061: decrement is the size of the operand being addressed. Some
1062: machines have other mode-dependent addresses. Many RISC machines
1063: have no mode-dependent addresses.
1064:
1065: You may assume that ADDR is a valid address for the machine.
1066:
1067: `LEGITIMATE_CONSTANT_P (X)'
1068: A C expression that is nonzero if X is a legitimate constant for
1069: an immediate operand on the target machine. You can assume that X
1070: satisfies `CONSTANT_P', so you need not check this. In fact, `1'
1071: is a suitable definition for this macro on machines where anything
1072: `CONSTANT_P' is valid.
1073:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.