X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=gcc%2Fdoc%2Fgccint.info-16;fp=gcc%2Fdoc%2Fgccint.info-16;h=0000000000000000000000000000000000000000;hb=5a5369932a08c074943c94407697a5813002fd31;hp=ffc5e35cee2a294fd234804c177306c5ad5b662a;hpb=aaf7afc53d3ed4f6c811f6ec493d857ea0459573;p=msp430-gcc.git diff --git a/gcc/doc/gccint.info-16 b/gcc/doc/gccint.info-16 deleted file mode 100644 index ffc5e35c..00000000 --- a/gcc/doc/gccint.info-16 +++ /dev/null @@ -1,881 +0,0 @@ -This is doc/gccint.info, produced by makeinfo version 4.5 from -doc/gccint.texi. - -INFO-DIR-SECTION Programming -START-INFO-DIR-ENTRY -* gccint: (gccint). Internals of the GNU Compiler Collection. -END-INFO-DIR-ENTRY - This file documents the internals of the GNU compilers. - - Published by the Free Software Foundation -59 Temple Place - Suite 330 -Boston, MA 02111-1307 USA - - Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License" and "Funding Free -Software", the Front-Cover texts being (a) (see below), and with the -Back-Cover Texts being (b) (see below). A copy of the license is -included in the section entitled "GNU Free Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - -File: gccint.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling - -How Large Values Are Returned ------------------------------ - - When a function value's mode is `BLKmode' (and in some other cases), -the value is not returned according to `FUNCTION_VALUE' (*note Scalar -Return::). Instead, the caller passes the address of a block of memory -in which the value should be stored. This address is called the -"structure value address". - - This section describes how to control returning structure values in -memory. - -`RETURN_IN_MEMORY (TYPE)' - A C expression which can inhibit the returning of certain function - values in registers, based on the type of value. A nonzero value - says to return the function value in memory, just as large - structures are always returned. Here TYPE will be a C expression - of type `tree', representing the data type of the value. - - Note that values of mode `BLKmode' must be explicitly handled by - this macro. Also, the option `-fpcc-struct-return' takes effect - regardless of this macro. On most systems, it is possible to - leave the macro undefined; this causes a default definition to be - used, whose value is the constant 1 for `BLKmode' values, and 0 - otherwise. - - Do not use this macro to indicate that structures and unions - should always be returned in memory. You should instead use - `DEFAULT_PCC_STRUCT_RETURN' to indicate this. - -`DEFAULT_PCC_STRUCT_RETURN' - Define this macro to be 1 if all structure and union return values - must be in memory. Since this results in slower code, this should - be defined only if needed for compatibility with other compilers - or with an ABI. If you define this macro to be 0, then the - conventions used for structure and union return values are decided - by the `RETURN_IN_MEMORY' macro. - - If not defined, this defaults to the value 1. - -`STRUCT_VALUE_REGNUM' - If the structure value address is passed in a register, then - `STRUCT_VALUE_REGNUM' should be the number of that register. - -`STRUCT_VALUE' - If the structure value address is not passed in a register, define - `STRUCT_VALUE' as an expression returning an RTX for the place - where the address is passed. If it returns 0, the address is - passed as an "invisible" first argument. - -`STRUCT_VALUE_INCOMING_REGNUM' - On some architectures the place where the structure value address - is found by the called function is not the same place that the - caller put it. This can be due to register windows, or it could - be because the function prologue moves it to a different place. - - If the incoming location of the structure value address is in a - register, define this macro as the register number. - -`STRUCT_VALUE_INCOMING' - If the incoming location is not a register, then you should define - `STRUCT_VALUE_INCOMING' as an expression for an RTX for where the - called function should find the value. If it should find the - value on the stack, define this to create a `mem' which refers to - the frame pointer. A definition of 0 means that the address is - passed as an "invisible" first argument. - -`PCC_STATIC_STRUCT_RETURN' - Define this macro if the usual system convention on the target - machine for returning structures and unions is for the called - function to return the address of a static variable containing the - value. - - Do not define this if the usual system convention is for the - caller to pass an address to the subroutine. - - This macro has effect in `-fpcc-struct-return' mode, but it does - nothing when you use `-freg-struct-return' mode. - - -File: gccint.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling - -Caller-Saves Register Allocation --------------------------------- - - If you enable it, GCC can save registers around function calls. This -makes it possible to use call-clobbered registers to hold variables that -must live across calls. - -`DEFAULT_CALLER_SAVES' - Define this macro if function calls on the target machine do not - preserve any registers; in other words, if `CALL_USED_REGISTERS' - has 1 for all registers. When defined, this macro enables - `-fcaller-saves' by default for all optimization levels. It has - no effect for optimization levels 2 and higher, where - `-fcaller-saves' is the default. - -`CALLER_SAVE_PROFITABLE (REFS, CALLS)' - A C expression to determine whether it is worthwhile to consider - placing a pseudo-register in a call-clobbered hard register and - saving and restoring it around each function call. The expression - should be 1 when this is worth doing, and 0 otherwise. - - If you don't define this macro, a default is used which is good on - most machines: `4 * CALLS < REFS'. - -`HARD_REGNO_CALLER_SAVE_MODE (REGNO, NREGS)' - A C expression specifying which mode is required for saving NREGS - of a pseudo-register in call-clobbered hard register REGNO. If - REGNO is unsuitable for caller save, `VOIDmode' should be - returned. For most machines this macro need not be defined since - GCC will select the smallest suitable mode. - - -File: gccint.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling - -Function Entry and Exit ------------------------ - - This section describes the macros that output function entry -("prologue") and exit ("epilogue") code. - - - Target Hook: void TARGET_ASM_FUNCTION_PROLOGUE (FILE *FILE, - HOST_WIDE_INT SIZE) - If defined, a function that outputs the assembler code for entry - to a function. The prologue is responsible for setting up the - stack frame, initializing the frame pointer register, saving - registers that must be saved, and allocating SIZE additional bytes - of storage for the local variables. SIZE is an integer. FILE is - a stdio stream to which the assembler code should be output. - - The label for the beginning of the function need not be output by - this macro. That has already been done when the macro is run. - - To determine which registers to save, the macro can refer to the - array `regs_ever_live': element R is nonzero if hard register R is - used anywhere within the function. This implies the function - prologue should save register R, provided it is not one of the - call-used registers. (`TARGET_ASM_FUNCTION_EPILOGUE' must - likewise use `regs_ever_live'.) - - On machines that have "register windows", the function entry code - does not save on the stack the registers that are in the windows, - even if they are supposed to be preserved by function calls; - instead it takes appropriate steps to "push" the register stack, - if any non-call-used registers are used in the function. - - On machines where functions may or may not have frame-pointers, the - function entry code must vary accordingly; it must set up the frame - pointer if one is wanted, and not otherwise. To determine whether - a frame pointer is in wanted, the macro can refer to the variable - `frame_pointer_needed'. The variable's value will be 1 at run - time in a function that needs a frame pointer. *Note - Elimination::. - - The function entry code is responsible for allocating any stack - space required for the function. This stack space consists of the - regions listed below. In most cases, these regions are allocated - in the order listed, with the last listed region closest to the - top of the stack (the lowest address if `STACK_GROWS_DOWNWARD' is - defined, and the highest address if it is not defined). You can - use a different order for a machine if doing so is more convenient - or required for compatibility reasons. Except in cases where - required by standard or by a debugger, there is no reason why the - stack layout used by GCC need agree with that used by other - compilers for a machine. - - - Target Hook: void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *FILE) - If defined, a function that outputs assembler code at the end of a - prologue. This should be used when the function prologue is being - emitted as RTL, and you have some extra assembler that needs to be - emitted. *Note prologue instruction pattern::. - - - Target Hook: void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *FILE) - If defined, a function that outputs assembler code at the start of - an epilogue. This should be used when the function epilogue is - being emitted as RTL, and you have some extra assembler that needs - to be emitted. *Note epilogue instruction pattern::. - - - Target Hook: void TARGET_ASM_FUNCTION_EPILOGUE (FILE *FILE, - HOST_WIDE_INT SIZE) - If defined, a function that outputs the assembler code for exit - from a function. The epilogue is responsible for restoring the - saved registers and stack pointer to their values when the - function was called, and returning control to the caller. This - macro takes the same arguments as the macro - `TARGET_ASM_FUNCTION_PROLOGUE', and the registers to restore are - determined from `regs_ever_live' and `CALL_USED_REGISTERS' in the - same way. - - On some machines, there is a single instruction that does all the - work of returning from the function. On these machines, give that - instruction the name `return' and do not define the macro - `TARGET_ASM_FUNCTION_EPILOGUE' at all. - - Do not define a pattern named `return' if you want the - `TARGET_ASM_FUNCTION_EPILOGUE' to be used. If you want the target - switches to control whether return instructions or epilogues are - used, define a `return' pattern with a validity condition that - tests the target switches appropriately. If the `return' - pattern's validity condition is false, epilogues will be used. - - On machines where functions may or may not have frame-pointers, the - function exit code must vary accordingly. Sometimes the code for - these two cases is completely different. To determine whether a - frame pointer is wanted, the macro can refer to the variable - `frame_pointer_needed'. The variable's value will be 1 when - compiling a function that needs a frame pointer. - - Normally, `TARGET_ASM_FUNCTION_PROLOGUE' and - `TARGET_ASM_FUNCTION_EPILOGUE' must treat leaf functions specially. - The C variable `current_function_is_leaf' is nonzero for such a - function. *Note Leaf Functions::. - - On some machines, some functions pop their arguments on exit while - others leave that for the caller to do. For example, the 68020 - when given `-mrtd' pops arguments in functions that take a fixed - number of arguments. - - Your definition of the macro `RETURN_POPS_ARGS' decides which - functions pop their own arguments. `TARGET_ASM_FUNCTION_EPILOGUE' - needs to know what was decided. The variable that is called - `current_function_pops_args' is the number of bytes of its - arguments that a function should pop. *Note Scalar Return::. - - * A region of `current_function_pretend_args_size' bytes of - uninitialized space just underneath the first argument - arriving on the stack. (This may not be at the very start of - the allocated stack region if the calling sequence has pushed - anything else since pushing the stack arguments. But - usually, on such machines, nothing else has been pushed yet, - because the function prologue itself does all the pushing.) - This region is used on machines where an argument may be - passed partly in registers and partly in memory, and, in some - cases to support the features in `' and - `'. - - * An area of memory used to save certain registers used by the - function. The size of this area, which may also include - space for such things as the return address and pointers to - previous stack frames, is machine-specific and usually - depends on which registers have been used in the function. - Machines with register windows often do not require a save - area. - - * A region of at least SIZE bytes, possibly rounded up to an - allocation boundary, to contain the local variables of the - function. On some machines, this region and the save area - may occur in the opposite order, with the save area closer to - the top of the stack. - - * Optionally, when `ACCUMULATE_OUTGOING_ARGS' is defined, a - region of `current_function_outgoing_args_size' bytes to be - used for outgoing argument lists of the function. *Note - Stack Arguments::. - - Normally, it is necessary for the macros - `TARGET_ASM_FUNCTION_PROLOGUE' and `TARGET_ASM_FUNCTION_EPILOGUE' - to treat leaf functions specially. The C variable - `current_function_is_leaf' is nonzero for such a function. - -`EXIT_IGNORE_STACK' - Define this macro as a C expression that is nonzero if the return - instruction or the function epilogue ignores the value of the stack - pointer; in other words, if it is safe to delete an instruction to - adjust the stack pointer before a return from the function. - - Note that this macro's value is relevant only for functions for - which frame pointers are maintained. It is never safe to delete a - final stack adjustment in a function that has no frame pointer, - and the compiler knows this regardless of `EXIT_IGNORE_STACK'. - -`EPILOGUE_USES (REGNO)' - Define this macro as a C expression that is nonzero for registers - that are used by the epilogue or the `return' pattern. The stack - and frame pointer registers are already be assumed to be used as - needed. - -`EH_USES (REGNO)' - Define this macro as a C expression that is nonzero for registers - that are used by the exception handling mechanism, and so should - be considered live on entry to an exception edge. - -`DELAY_SLOTS_FOR_EPILOGUE' - Define this macro if the function epilogue contains delay slots to - which instructions from the rest of the function can be "moved". - The definition should be a C expression whose value is an integer - representing the number of delay slots there. - -`ELIGIBLE_FOR_EPILOGUE_DELAY (INSN, N)' - A C expression that returns 1 if INSN can be placed in delay slot - number N of the epilogue. - - The argument N is an integer which identifies the delay slot now - being considered (since different slots may have different rules of - eligibility). It is never negative and is always less than the - number of epilogue delay slots (what `DELAY_SLOTS_FOR_EPILOGUE' - returns). If you reject a particular insn for a given delay slot, - in principle, it may be reconsidered for a subsequent delay slot. - Also, other insns may (at least in principle) be considered for - the so far unfilled delay slot. - - The insns accepted to fill the epilogue delay slots are put in an - RTL list made with `insn_list' objects, stored in the variable - `current_function_epilogue_delay_list'. The insn for the first - delay slot comes first in the list. Your definition of the macro - `TARGET_ASM_FUNCTION_EPILOGUE' should fill the delay slots by - outputting the insns in this list, usually by calling - `final_scan_insn'. - - You need not define this macro if you did not define - `DELAY_SLOTS_FOR_EPILOGUE'. - -`ASM_OUTPUT_MI_THUNK (FILE, THUNK_FNDECL, DELTA, FUNCTION)' - A C compound statement that outputs the assembler code for a thunk - function, used to implement C++ virtual function calls with - multiple inheritance. The thunk acts as a wrapper around a - virtual function, adjusting the implicit object parameter before - handing control off to the real function. - - First, emit code to add the integer DELTA to the location that - contains the incoming first argument. Assume that this argument - contains a pointer, and is the one used to pass the `this' pointer - in C++. This is the incoming argument _before_ the function - prologue, e.g. `%o0' on a sparc. The addition must preserve the - values of all other incoming arguments. - - After the addition, emit code to jump to FUNCTION, which is a - `FUNCTION_DECL'. This is a direct pure jump, not a call, and does - not touch the return address. Hence returning from FUNCTION will - return to whoever called the current `thunk'. - - The effect must be as if FUNCTION had been called directly with - the adjusted first argument. This macro is responsible for - emitting all of the code for a thunk function; - `TARGET_ASM_FUNCTION_PROLOGUE' and `TARGET_ASM_FUNCTION_EPILOGUE' - are not invoked. - - The THUNK_FNDECL is redundant. (DELTA and FUNCTION have already - been extracted from it.) It might possibly be useful on some - targets, but probably not. - - If you do not define this macro, the target-independent code in - the C++ front end will generate a less efficient heavyweight thunk - that calls FUNCTION instead of jumping to it. The generic - approach does not support varargs. - - -File: gccint.info, Node: Profiling, Next: Tail Calls, Prev: Function Entry, Up: Stack and Calling - -Generating Code for Profiling ------------------------------ - - These macros will help you generate code for profiling. - -`FUNCTION_PROFILER (FILE, LABELNO)' - A C statement or compound statement to output to FILE some - assembler code to call the profiling subroutine `mcount'. - - The details of how `mcount' expects to be called are determined by - your operating system environment, not by GCC. To figure them out, - compile a small program for profiling using the system's installed - C compiler and look at the assembler code that results. - - Older implementations of `mcount' expect the address of a counter - variable to be loaded into some register. The name of this - variable is `LP' followed by the number LABELNO, so you would - generate the name using `LP%d' in a `fprintf'. - -`PROFILE_HOOK' - A C statement or compound statement to output to FILE some assembly - code to call the profiling subroutine `mcount' even the target does - not support profiling. - -`NO_PROFILE_COUNTERS' - Define this macro if the `mcount' subroutine on your system does - not need a counter variable allocated for each function. This is - true for almost all modern implementations. If you define this - macro, you must not use the LABELNO argument to - `FUNCTION_PROFILER'. - -`PROFILE_BEFORE_PROLOGUE' - Define this macro if the code for function profiling should come - before the function prologue. Normally, the profiling code comes - after. - -`TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER' - On some targets, it is impossible to use profiling when the frame - pointer has been omitted. For example, on x86 GNU/Linux systems, - the `mcount' routine provided by the GNU C Library finds the - address of the routine that called the routine that called `mcount' - by looking in the immediate caller's stack frame. If the immediate - caller has no frame pointer, this lookup will fail. - - By default, GCC assumes that the target does allow profiling when - the frame pointer is omitted. This macro should be defined to a C - expression that evaluates to `false' if the target does not allow - profiling when the frame pointer is omitted. - - - -File: gccint.info, Node: Tail Calls, Prev: Profiling, Up: Stack and Calling - -Permitting tail calls ---------------------- - -`FUNCTION_OK_FOR_SIBCALL (DECL)' - A C expression that evaluates to true if it is ok to perform a - sibling call to DECL from the current function. - - It is not uncommon for limitations of calling conventions to - prevent tail calls to functions outside the current unit of - translation, or during PIC compilation. Use this macro to enforce - these restrictions, as the `sibcall' md pattern can not fail, or - fall over to a "normal" call. - - -File: gccint.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Target Macros - -Implementing the Varargs Macros -=============================== - - GCC comes with an implementation of `' and `' -that work without change on machines that pass arguments on the stack. -Other machines require their own implementations of varargs, and the -two machine independent header files must have conditionals to include -it. - - ISO `' differs from traditional `' mainly in -the calling convention for `va_start'. The traditional implementation -takes just one argument, which is the variable in which to store the -argument pointer. The ISO implementation of `va_start' takes an -additional second argument. The user is supposed to write the last -named argument of the function here. - - However, `va_start' should not use this argument. The way to find -the end of the named arguments is with the built-in functions described -below. - -`__builtin_saveregs ()' - Use this built-in function to save the argument registers in - memory so that the varargs mechanism can access them. Both ISO - and traditional versions of `va_start' must use - `__builtin_saveregs', unless you use `SETUP_INCOMING_VARARGS' (see - below) instead. - - On some machines, `__builtin_saveregs' is open-coded under the - control of the macro `EXPAND_BUILTIN_SAVEREGS'. On other machines, - it calls a routine written in assembler language, found in - `libgcc2.c'. - - Code generated for the call to `__builtin_saveregs' appears at the - beginning of the function, as opposed to where the call to - `__builtin_saveregs' is written, regardless of what the code is. - This is because the registers must be saved before the function - starts to use them for its own purposes. - -`__builtin_args_info (CATEGORY)' - Use this built-in function to find the first anonymous arguments in - registers. - - In general, a machine may have several categories of registers - used for arguments, each for a particular category of data types. - (For example, on some machines, floating-point registers are used - for floating-point arguments while other arguments are passed in - the general registers.) To make non-varargs functions use the - proper calling convention, you have defined the `CUMULATIVE_ARGS' - data type to record how many registers in each category have been - used so far - - `__builtin_args_info' accesses the same data structure of type - `CUMULATIVE_ARGS' after the ordinary argument layout is finished - with it, with CATEGORY specifying which word to access. Thus, the - value indicates the first unused register in a given category. - - Normally, you would use `__builtin_args_info' in the implementation - of `va_start', accessing each category just once and storing the - value in the `va_list' object. This is because `va_list' will - have to update the values, and there is no way to alter the values - accessed by `__builtin_args_info'. - -`__builtin_next_arg (LASTARG)' - This is the equivalent of `__builtin_args_info', for stack - arguments. It returns the address of the first anonymous stack - argument, as type `void *'. If `ARGS_GROW_DOWNWARD', it returns - the address of the location above the first anonymous stack - argument. Use it in `va_start' to initialize the pointer for - fetching arguments from the stack. Also use it in `va_start' to - verify that the second parameter LASTARG is the last named argument - of the current function. - -`__builtin_classify_type (OBJECT)' - Since each machine has its own conventions for which data types are - passed in which kind of register, your implementation of `va_arg' - has to embody these conventions. The easiest way to categorize the - specified data type is to use `__builtin_classify_type' together - with `sizeof' and `__alignof__'. - - `__builtin_classify_type' ignores the value of OBJECT, considering - only its data type. It returns an integer describing what kind of - type that is--integer, floating, pointer, structure, and so on. - - The file `typeclass.h' defines an enumeration that you can use to - interpret the values of `__builtin_classify_type'. - - These machine description macros help implement varargs: - -`EXPAND_BUILTIN_SAVEREGS ()' - If defined, is a C expression that produces the machine-specific - code for a call to `__builtin_saveregs'. This code will be moved - to the very beginning of the function, before any parameter access - are made. The return value of this function should be an RTX that - contains the value to use as the return of `__builtin_saveregs'. - -`SETUP_INCOMING_VARARGS (ARGS_SO_FAR, MODE, TYPE, PRETEND_ARGS_SIZE, SECOND_TIME)' - This macro offers an alternative to using `__builtin_saveregs' and - defining the macro `EXPAND_BUILTIN_SAVEREGS'. Use it to store the - anonymous register arguments into the stack so that all the - arguments appear to have been passed consecutively on the stack. - Once this is done, you can use the standard implementation of - varargs that works for machines that pass all their arguments on - the stack. - - The argument ARGS_SO_FAR is the `CUMULATIVE_ARGS' data structure, - containing the values that are obtained after processing the named - arguments. The arguments MODE and TYPE describe the last named - argument--its machine mode and its data type as a tree node. - - The macro implementation should do two things: first, push onto the - stack all the argument registers _not_ used for the named - arguments, and second, store the size of the data thus pushed into - the `int'-valued variable whose name is supplied as the argument - PRETEND_ARGS_SIZE. The value that you store here will serve as - additional offset for setting up the stack frame. - - Because you must generate code to push the anonymous arguments at - compile time without knowing their data types, - `SETUP_INCOMING_VARARGS' is only useful on machines that have just - a single category of argument register and use it uniformly for - all data types. - - If the argument SECOND_TIME is nonzero, it means that the - arguments of the function are being analyzed for the second time. - This happens for an inline function, which is not actually - compiled until the end of the source file. The macro - `SETUP_INCOMING_VARARGS' should not generate any instructions in - this case. - -`STRICT_ARGUMENT_NAMING' - Define this macro to be a nonzero value if the location where a - function argument is passed depends on whether or not it is a - named argument. - - This macro controls how the NAMED argument to `FUNCTION_ARG' is - set for varargs and stdarg functions. If this macro returns a - nonzero value, the NAMED argument is always true for named - arguments, and false for unnamed arguments. If it returns a value - of zero, but `SETUP_INCOMING_VARARGS' is defined, then all - arguments are treated as named. Otherwise, all named arguments - except the last are treated as named. - - You need not define this macro if it always returns zero. - -`PRETEND_OUTGOING_VARARGS_NAMED' - If you need to conditionally change ABIs so that one works with - `SETUP_INCOMING_VARARGS', but the other works like neither - `SETUP_INCOMING_VARARGS' nor `STRICT_ARGUMENT_NAMING' was defined, - then define this macro to return nonzero if - `SETUP_INCOMING_VARARGS' is used, zero otherwise. Otherwise, you - should not define this macro. - - -File: gccint.info, Node: Trampolines, Next: Library Calls, Prev: Varargs, Up: Target Macros - -Trampolines for Nested Functions -================================ - - A "trampoline" is a small piece of code that is created at run time -when the address of a nested function is taken. It normally resides on -the stack, in the stack frame of the containing function. These macros -tell GCC how to generate code to allocate and initialize a trampoline. - - The instructions in the trampoline must do two things: load a -constant address into the static chain register, and jump to the real -address of the nested function. On CISC machines such as the m68k, -this requires two instructions, a move immediate and a jump. Then the -two addresses exist in the trampoline as word-long immediate operands. -On RISC machines, it is often necessary to load each address into a -register in two parts. Then pieces of each address form separate -immediate operands. - - The code generated to initialize the trampoline must store the -variable parts--the static chain value and the function address--into -the immediate operands of the instructions. On a CISC machine, this is -simply a matter of copying each address to a memory reference at the -proper offset from the start of the trampoline. On a RISC machine, it -may be necessary to take out pieces of the address and store them -separately. - -`TRAMPOLINE_TEMPLATE (FILE)' - A C statement to output, on the stream FILE, assembler code for a - block of data that contains the constant parts of a trampoline. - This code should not include a label--the label is taken care of - automatically. - - If you do not define this macro, it means no template is needed - for the target. Do not define this macro on systems where the - block move code to copy the trampoline into place would be larger - than the code to generate it on the spot. - -`TRAMPOLINE_SECTION' - The name of a subroutine to switch to the section in which the - trampoline template is to be placed (*note Sections::). The - default is a value of `readonly_data_section', which places the - trampoline in the section containing read-only data. - -`TRAMPOLINE_SIZE' - A C expression for the size in bytes of the trampoline, as an - integer. - -`TRAMPOLINE_ALIGNMENT' - Alignment required for trampolines, in bits. - - If you don't define this macro, the value of `BIGGEST_ALIGNMENT' - is used for aligning trampolines. - -`INITIALIZE_TRAMPOLINE (ADDR, FNADDR, STATIC_CHAIN)' - A C statement to initialize the variable parts of a trampoline. - ADDR is an RTX for the address of the trampoline; FNADDR is an RTX - for the address of the nested function; STATIC_CHAIN is an RTX for - the static chain value that should be passed to the function when - it is called. - -`TRAMPOLINE_ADJUST_ADDRESS (ADDR)' - A C statement that should perform any machine-specific adjustment - in the address of the trampoline. Its argument contains the - address that was passed to `INITIALIZE_TRAMPOLINE'. In case the - address to be used for a function call should be different from - the address in which the template was stored, the different - address should be assigned to ADDR. If this macro is not defined, - ADDR will be used for function calls. - -`ALLOCATE_TRAMPOLINE (FP)' - A C expression to allocate run-time space for a trampoline. The - expression value should be an RTX representing a memory reference - to the space for the trampoline. - - If this macro is not defined, by default the trampoline is - allocated as a stack slot. This default is right for most - machines. The exceptions are machines where it is impossible to - execute instructions in the stack area. On such machines, you may - have to implement a separate stack, using this macro in - conjunction with `TARGET_ASM_FUNCTION_PROLOGUE' and - `TARGET_ASM_FUNCTION_EPILOGUE'. - - FP points to a data structure, a `struct function', which - describes the compilation status of the immediate containing - function of the function which the trampoline is for. Normally - (when `ALLOCATE_TRAMPOLINE' is not defined), the stack slot for the - trampoline is in the stack frame of this containing function. - Other allocation strategies probably must do something analogous - with this information. - - Implementing trampolines is difficult on many machines because they -have separate instruction and data caches. Writing into a stack -location fails to clear the memory in the instruction cache, so when -the program jumps to that location, it executes the old contents. - - Here are two possible solutions. One is to clear the relevant parts -of the instruction cache whenever a trampoline is set up. The other is -to make all trampolines identical, by having them jump to a standard -subroutine. The former technique makes trampoline execution faster; the -latter makes initialization faster. - - To clear the instruction cache when a trampoline is initialized, -define the following macros which describe the shape of the cache. - -`INSN_CACHE_SIZE' - The total size in bytes of the cache. - -`INSN_CACHE_LINE_WIDTH' - The length in bytes of each cache line. The cache is divided into - cache lines which are disjoint slots, each holding a contiguous - chunk of data fetched from memory. Each time data is brought into - the cache, an entire line is read at once. The data loaded into a - cache line is always aligned on a boundary equal to the line size. - -`INSN_CACHE_DEPTH' - The number of alternative cache lines that can hold any particular - memory location. - - Alternatively, if the machine has system calls or instructions to -clear the instruction cache directly, you can define the following -macro. - -`CLEAR_INSN_CACHE (BEG, END)' - If defined, expands to a C expression clearing the _instruction - cache_ in the specified interval. If it is not defined, and the - macro `INSN_CACHE_SIZE' is defined, some generic code is generated - to clear the cache. The definition of this macro would typically - be a series of `asm' statements. Both BEG and END are both pointer - expressions. - - To use a standard subroutine, define the following macro. In -addition, you must make sure that the instructions in a trampoline fill -an entire cache line with identical instructions, or else ensure that -the beginning of the trampoline code is always aligned at the same -point in its cache line. Look in `m68k.h' as a guide. - -`TRANSFER_FROM_TRAMPOLINE' - Define this macro if trampolines need a special subroutine to do - their work. The macro should expand to a series of `asm' - statements which will be compiled with GCC. They go in a library - function named `__transfer_from_trampoline'. - - If you need to avoid executing the ordinary prologue code of a - compiled C function when you jump to the subroutine, you can do so - by placing a special label of your own in the assembler code. Use - one `asm' statement to generate an assembler label, and another to - make the label global. Then trampolines can use that label to - jump directly to your special assembler code. - - -File: gccint.info, Node: Library Calls, Next: Addressing Modes, Prev: Trampolines, Up: Target Macros - -Implicit Calls to Library Routines -================================== - - Here is an explanation of implicit calls to library routines. - -`MULSI3_LIBCALL' - A C string constant giving the name of the function to call for - multiplication of one signed full-word by another. If you do not - define this macro, the default name is used, which is `__mulsi3', - a function defined in `libgcc.a'. - -`DIVSI3_LIBCALL' - A C string constant giving the name of the function to call for - division of one signed full-word by another. If you do not define - this macro, the default name is used, which is `__divsi3', a - function defined in `libgcc.a'. - -`UDIVSI3_LIBCALL' - A C string constant giving the name of the function to call for - division of one unsigned full-word by another. If you do not - define this macro, the default name is used, which is `__udivsi3', - a function defined in `libgcc.a'. - -`MODSI3_LIBCALL' - A C string constant giving the name of the function to call for the - remainder in division of one signed full-word by another. If you - do not define this macro, the default name is used, which is - `__modsi3', a function defined in `libgcc.a'. - -`UMODSI3_LIBCALL' - A C string constant giving the name of the function to call for the - remainder in division of one unsigned full-word by another. If - you do not define this macro, the default name is used, which is - `__umodsi3', a function defined in `libgcc.a'. - -`MULDI3_LIBCALL' - A C string constant giving the name of the function to call for - multiplication of one signed double-word by another. If you do not - define this macro, the default name is used, which is `__muldi3', - a function defined in `libgcc.a'. - -`DIVDI3_LIBCALL' - A C string constant giving the name of the function to call for - division of one signed double-word by another. If you do not - define this macro, the default name is used, which is `__divdi3', a - function defined in `libgcc.a'. - -`UDIVDI3_LIBCALL' - A C string constant giving the name of the function to call for - division of one unsigned full-word by another. If you do not - define this macro, the default name is used, which is `__udivdi3', - a function defined in `libgcc.a'. - -`MODDI3_LIBCALL' - A C string constant giving the name of the function to call for the - remainder in division of one signed double-word by another. If - you do not define this macro, the default name is used, which is - `__moddi3', a function defined in `libgcc.a'. - -`UMODDI3_LIBCALL' - A C string constant giving the name of the function to call for the - remainder in division of one unsigned full-word by another. If - you do not define this macro, the default name is used, which is - `__umoddi3', a function defined in `libgcc.a'. - -`INIT_TARGET_OPTABS' - Define this macro as a C statement that declares additional library - routines renames existing ones. `init_optabs' calls this macro - after initializing all the normal library routines. - -`FLOAT_LIB_COMPARE_RETURNS_BOOL' - Define this macro as a C statement that returns nonzero if a call - to the floating point comparison library function will return a - boolean value that indicates the result of the comparison. It - should return zero if one of gcc's own libgcc functions is called. - - Most ports don't need to define this macro. - -`TARGET_EDOM' - The value of `EDOM' on the target machine, as a C integer constant - expression. If you don't define this macro, GCC does not attempt - to deposit the value of `EDOM' into `errno' directly. Look in - `/usr/include/errno.h' to find the value of `EDOM' on your system. - - If you do not define `TARGET_EDOM', then compiled code reports - domain errors by calling the library function and letting it - report the error. If mathematical functions on your system use - `matherr' when there is an error, then you should leave - `TARGET_EDOM' undefined so that `matherr' is used normally. - -`GEN_ERRNO_RTX' - Define this macro as a C expression to create an rtl expression - that refers to the global "variable" `errno'. (On certain systems, - `errno' may not actually be a variable.) If you don't define this - macro, a reasonable default is used. - -`TARGET_MEM_FUNCTIONS' - Define this macro if GCC should generate calls to the ISO C (and - System V) library functions `memcpy', `memmove' and `memset' - rather than the BSD functions `bcopy' and `bzero'. - -`LIBGCC_NEEDS_DOUBLE' - Define this macro if `float' arguments cannot be passed to library - routines (so they must be converted to `double'). This macro - affects both how library calls are generated and how the library - routines in `libgcc.a' accept their arguments. It is useful on - machines where floating and fixed point arguments are passed - differently, such as the i860. - -`NEXT_OBJC_RUNTIME' - Define this macro to generate code for Objective-C message sending - using the calling convention of the NeXT system. This calling - convention involves passing the object, the selector and the - method arguments all at once to the method-lookup library function. - - The default calling convention passes just the object and the - selector to the lookup function, which returns a pointer to the - method. -