gcc/doc/gccint/target-macros/stack-layout-and-calling-conventions/registers-that-address-the-stack-frame.rst

   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 .. _frame-registers:
   7
   8 Registers That Address the Stack Frame
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 .. prevent bad page break with this line
  12
  13 This discusses registers that address the stack frame.
  14
  15 .. c:macro:: STACK_POINTER_REGNUM
  16
  17   The register number of the stack pointer register, which must also be a
  18   fixed register according to ``FIXED_REGISTERS``.  On most machines,
  19   the hardware determines which register this is.
  20
  21 .. c:macro:: FRAME_POINTER_REGNUM
  22
  23   The register number of the frame pointer register, which is used to
  24   access automatic variables in the stack frame.  On some machines, the
  25   hardware determines which register this is.  On other machines, you can
  26   choose any register you wish for this purpose.
  27
  28 .. c:macro:: HARD_FRAME_POINTER_REGNUM
  29
  30   On some machines the offset between the frame pointer and starting
  31   offset of the automatic variables is not known until after register
  32   allocation has been done (for example, because the saved registers are
  33   between these two locations).  On those machines, define
  34   ``FRAME_POINTER_REGNUM`` the number of a special, fixed register to
  35   be used internally until the offset is known, and define
  36   ``HARD_FRAME_POINTER_REGNUM`` to be the actual hard register number
  37   used for the frame pointer.
  38
  39   You should define this macro only in the very rare circumstances when it
  40   is not possible to calculate the offset between the frame pointer and
  41   the automatic variables until after register allocation has been
  42   completed.  When this macro is defined, you must also indicate in your
  43   definition of ``ELIMINABLE_REGS`` how to eliminate
  44   ``FRAME_POINTER_REGNUM`` into either ``HARD_FRAME_POINTER_REGNUM``
  45   or ``STACK_POINTER_REGNUM``.
  46
  47   Do not define this macro if it would be the same as
  48   ``FRAME_POINTER_REGNUM``.
  49
  50 .. c:macro:: ARG_POINTER_REGNUM
  51
  52   The register number of the arg pointer register, which is used to access
  53   the function's argument list.  On some machines, this is the same as the
  54   frame pointer register.  On some machines, the hardware determines which
  55   register this is.  On other machines, you can choose any register you
  56   wish for this purpose.  If this is not the same register as the frame
  57   pointer register, then you must mark it as a fixed register according to
  58   ``FIXED_REGISTERS``, or arrange to be able to eliminate it
  59   (see :ref:`elimination`).
  60
  61 .. c:macro:: HARD_FRAME_POINTER_IS_FRAME_POINTER
  62
  63   Define this to a preprocessor constant that is nonzero if
  64   ``hard_frame_pointer_rtx`` and ``frame_pointer_rtx`` should be
  65   the same.  The default definition is :samp:`(HARD_FRAME_POINTER_REGNUM
  66   == FRAME_POINTER_REGNUM)`; you only need to define this macro if that
  67   definition is not suitable for use in preprocessor conditionals.
  68
  69 .. c:macro:: HARD_FRAME_POINTER_IS_ARG_POINTER
  70
  71   Define this to a preprocessor constant that is nonzero if
  72   ``hard_frame_pointer_rtx`` and ``arg_pointer_rtx`` should be the
  73   same.  The default definition is :samp:`(HARD_FRAME_POINTER_REGNUM ==
  74   ARG_POINTER_REGNUM)`; you only need to define this macro if that
  75   definition is not suitable for use in preprocessor conditionals.
  76
  77 .. c:macro:: RETURN_ADDRESS_POINTER_REGNUM
  78
  79   The register number of the return address pointer register, which is used to
  80   access the current function's return address from the stack.  On some
  81   machines, the return address is not at a fixed offset from the frame
  82   pointer or stack pointer or argument pointer.  This register can be defined
  83   to point to the return address on the stack, and then be converted by
  84   ``ELIMINABLE_REGS`` into either the frame pointer or stack pointer.
  85
  86   Do not define this macro unless there is no other way to get the return
  87   address from the stack.
  88
  89 .. c:macro:: STATIC_CHAIN_REGNUM
  90
  91 .. c:macro:: STATIC_CHAIN_INCOMING_REGNUM
  92
  93   Register numbers used for passing a function's static chain pointer.  If
  94   register windows are used, the register number as seen by the called
  95   function is ``STATIC_CHAIN_INCOMING_REGNUM``, while the register
  96   number as seen by the calling function is ``STATIC_CHAIN_REGNUM``.  If
  97   these registers are the same, ``STATIC_CHAIN_INCOMING_REGNUM`` need
  98   not be defined.
  99
 100   The static chain register need not be a fixed register.
 101
 102   If the static chain is passed in memory, these macros should not be
 103   defined; instead, the ``TARGET_STATIC_CHAIN`` hook should be used.
 104
 105 .. include:: ../tm.rst.in
 106   :start-after: [TARGET_STATIC_CHAIN]
 107   :end-before: [TARGET_STATIC_CHAIN]
 108
 109
 110 .. c:macro:: DWARF_FRAME_REGISTERS
 111
 112   This macro specifies the maximum number of hard registers that can be
 113   saved in a call frame.  This is used to size data structures used in
 114   DWARF2 exception handling.
 115
 116   Prior to GCC 3.0, this macro was needed in order to establish a stable
 117   exception handling ABI in the face of adding new hard registers for ISA
 118   extensions.  In GCC 3.0 and later, the EH ABI is insulated from changes
 119   in the number of hard registers.  Nevertheless, this macro can still be
 120   used to reduce the runtime memory requirements of the exception handling
 121   routines, which can be substantial if the ISA contains a lot of
 122   registers that are not call-saved.
 123
 124   If this macro is not defined, it defaults to
 125   ``FIRST_PSEUDO_REGISTER``.
 126
 127 .. c:macro:: PRE_GCC3_DWARF_FRAME_REGISTERS
 128
 129   This macro is similar to ``DWARF_FRAME_REGISTERS``, but is provided
 130   for backward compatibility in pre GCC 3.0 compiled code.
 131
 132   If this macro is not defined, it defaults to
 133   ``DWARF_FRAME_REGISTERS``.
 134
 135 .. c:macro:: DWARF_REG_TO_UNWIND_COLUMN (regno)
 136
 137   Define this macro if the target's representation for dwarf registers
 138   is different than the internal representation for unwind column.
 139   Given a dwarf register, this macro should return the internal unwind
 140   column number to use instead.
 141
 142 .. c:macro:: DWARF_FRAME_REGNUM (regno)
 143
 144   Define this macro if the target's representation for dwarf registers
 145   used in .eh_frame or .debug_frame is different from that used in other
 146   debug info sections.  Given a GCC hard register number, this macro
 147   should return the .eh_frame register number.  The default is
 148   ``DEBUGGER_REGNO (regno)``.
 149
 150 .. c:macro:: DWARF2_FRAME_REG_OUT (regno, for_eh)
 151
 152   Define this macro to map register numbers held in the call frame info
 153   that GCC has collected using ``DWARF_FRAME_REGNUM`` to those that
 154   should be output in .debug_frame (``for_eh`` is zero) and
 155   .eh_frame (``for_eh`` is nonzero).  The default is to
 156   return ``regno``.
 157
 158 .. c:macro:: REG_VALUE_IN_UNWIND_CONTEXT
 159
 160   Define this macro if the target stores register values as
 161   ``_Unwind_Word`` type in unwind context.  It should be defined if
 162   target register size is larger than the size of ``void *``.  The
 163   default is to store register values as ``void *`` type.
 164
 165 .. c:macro:: ASSUME_EXTENDED_UNWIND_CONTEXT
 166
 167   Define this macro to be 1 if the target always uses extended unwind
 168   context with version, args_size and by_value fields.  If it is undefined,
 169   it will be defined to 1 when ``REG_VALUE_IN_UNWIND_CONTEXT`` is
 170   defined and 0 otherwise.
 171
 172 .. c:macro:: DWARF_LAZY_REGISTER_VALUE (regno, value)
 173
 174   Define this macro if the target has pseudo DWARF registers whose
 175   values need to be computed lazily on demand by the unwinder (such as when
 176   referenced in a CFA expression).  The macro returns true if :samp:`{regno}`
 177   is such a register and stores its value in :samp:`*{value}` if so.