git.ipfire.org Git - thirdparty/gcc.git/blob

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: arguments on stack, stack arguments
   7
   8 .. _stack-arguments:
   9
  10 Passing Function Arguments on the Stack
  11 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  12
  13 The macros in this section control how arguments are passed
  14 on the stack.  See the following section for other macros that
  15 control passing certain arguments in registers.
  16
  17 .. include:: ../tm.rst.in
  18   :start-after: [TARGET_PROMOTE_PROTOTYPES]
  19   :end-before: [TARGET_PROMOTE_PROTOTYPES]
  20
  21
  22 .. include:: ../tm.rst.in
  23   :start-after: [TARGET_PUSH_ARGUMENT]
  24   :end-before: [TARGET_PUSH_ARGUMENT]
  25
  26
  27 .. c:macro:: PUSH_ARGS_REVERSED
  28
  29   A C expression.  If nonzero, function arguments will be evaluated from
  30   last to first, rather than from first to last.  If this macro is not
  31   defined, it defaults to ``PUSH_ARGS`` on targets where the stack
  32   and args grow in opposite directions, and 0 otherwise.
  33
  34 .. c:macro:: PUSH_ROUNDING (npushed)
  35
  36   A C expression that is the number of bytes actually pushed onto the
  37   stack when an instruction attempts to push :samp:`{npushed}` bytes.
  38
  39   On some machines, the definition
  40
  41   .. code-block:: c++
  42
  43     #define PUSH_ROUNDING(BYTES) (BYTES)
  44
  45   will suffice.  But on other machines, instructions that appear
  46   to push one byte actually push two bytes in an attempt to maintain
  47   alignment.  Then the definition should be
  48
  49   .. code-block:: c++
  50
  51     #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
  52
  53   If the value of this macro has a type, it should be an unsigned type.
  54
  55 .. index:: outgoing_args_size, crtl->outgoing_args_size
  56
  57 .. c:macro:: ACCUMULATE_OUTGOING_ARGS
  58
  59   A C expression.  If nonzero, the maximum amount of space required for outgoing arguments
  60   will be computed and placed into
  61   ``crtl->outgoing_args_size``.  No space will be pushed
  62   onto the stack for each call; instead, the function prologue should
  63   increase the stack frame size by this amount.
  64
  65   Setting both ``PUSH_ARGS`` and ``ACCUMULATE_OUTGOING_ARGS``
  66   is not proper.
  67
  68 .. c:macro:: REG_PARM_STACK_SPACE (fndecl)
  69
  70   Define this macro if functions should assume that stack space has been
  71   allocated for arguments even when their values are passed in
  72   registers.
  73
  74   The value of this macro is the size, in bytes, of the area reserved for
  75   arguments passed in registers for the function represented by :samp:`{fndecl}`,
  76   which can be zero if GCC is calling a library function.
  77   The argument :samp:`{fndecl}` can be the FUNCTION_DECL, or the type itself
  78   of the function.
  79
  80   This space can be allocated by the caller, or be a part of the
  81   machine-dependent stack frame: ``OUTGOING_REG_PARM_STACK_SPACE`` says
  82   which.
  83
  84 .. above is overfull.  not sure what to do.  -mew 5feb93  did
  85
  86 .. something, not sure if it looks good.  -mew 10feb93
  87
  88 .. c:macro:: INCOMING_REG_PARM_STACK_SPACE (fndecl)
  89
  90   Like ``REG_PARM_STACK_SPACE``, but for incoming register arguments.
  91   Define this macro if space guaranteed when compiling a function body
  92   is different to space required when making a call, a situation that
  93   can arise with K&R style function definitions.
  94
  95 .. c:macro:: OUTGOING_REG_PARM_STACK_SPACE (fntype)
  96
  97   Define this to a nonzero value if it is the responsibility of the
  98   caller to allocate the area reserved for arguments passed in registers
  99   when calling a function of :samp:`{fntype}`.  :samp:`{fntype}` may be NULL
 100   if the function called is a library function.
 101
 102   If ``ACCUMULATE_OUTGOING_ARGS`` is defined, this macro controls
 103   whether the space for these arguments counts in the value of
 104   ``crtl->outgoing_args_size``.
 105
 106 .. c:macro:: STACK_PARMS_IN_REG_PARM_AREA
 107
 108   Define this macro if ``REG_PARM_STACK_SPACE`` is defined, but the
 109   stack parameters don't skip the area specified by it.
 110
 111   .. i changed this, makes more sens and it should have taken care of the
 112
 113   .. overfull.. not as specific, tho.  -mew 5feb93
 114
 115   Normally, when a parameter is not passed in registers, it is placed on the
 116   stack beyond the ``REG_PARM_STACK_SPACE`` area.  Defining this macro
 117   suppresses this behavior and causes the parameter to be passed on the
 118   stack in its natural location.
 119
 120 .. include:: ../tm.rst.in
 121   :start-after: [TARGET_RETURN_POPS_ARGS]
 122   :end-before: [TARGET_RETURN_POPS_ARGS]
 123
 124
 125 .. c:macro:: CALL_POPS_ARGS (cum)
 126
 127   A C expression that should indicate the number of bytes a call sequence
 128   pops off the stack.  It is added to the value of ``RETURN_POPS_ARGS``
 129   when compiling a function call.
 130
 131   :samp:`{cum}` is the variable in which all arguments to the called function
 132   have been accumulated.
 133
 134   On certain architectures, such as the SH5, a call trampoline is used
 135   that pops certain registers off the stack, depending on the arguments
 136   that have been passed to the function.  Since this is a property of the
 137   call site, not of the called function, ``RETURN_POPS_ARGS`` is not
 138   appropriate.