home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / gnu / info / gcc.info-20 (.txt) < prev    next >
GNU Info File  |  1994-11-17  |  51KB  |  864 lines

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