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:: return values in registers, values, returned by functions, scalars, returned as values
   7
   8 .. _scalar-return:
   9
  10 How Scalar Function Values Are Returned
  11 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  12
  13 This section discusses the macros that control returning scalars as
  14 values---values that can fit in registers.
  15
  16 .. function:: rtx TARGET_FUNCTION_VALUE (const_tree ret_type, const_tree fn_decl_or_type, bool outgoing)
  17
  18   .. hook-start:TARGET_FUNCTION_VALUE
  19
  20   Define this to return an RTX representing the place where a function
  21   returns or receives a value of data type :samp:`{ret_type}`, a tree node
  22   representing a data type.  :samp:`{fn_decl_or_type}` is a tree node
  23   representing ``FUNCTION_DECL`` or ``FUNCTION_TYPE`` of a
  24   function being called.  If :samp:`{outgoing}` is false, the hook should
  25   compute the register in which the caller will see the return value.
  26   Otherwise, the hook should return an RTX representing the place where
  27   a function returns a value.
  28
  29   On many machines, only ``TYPE_MODE (ret_type)`` is relevant.
  30   (Actually, on most machines, scalar values are returned in the same
  31   place regardless of mode.)  The value of the expression is usually a
  32   ``reg`` RTX for the hard register where the return value is stored.
  33   The value can also be a ``parallel`` RTX, if the return value is in
  34   multiple places.  See ``TARGET_FUNCTION_ARG`` for an explanation of the
  35   ``parallel`` form.   Note that the callee will populate every
  36   location specified in the ``parallel``, but if the first element of
  37   the ``parallel`` contains the whole return value, callers will use
  38   that element as the canonical location and ignore the others.  The m68k
  39   port uses this type of ``parallel`` to return pointers in both
  40   :samp:`%a0` (the canonical location) and :samp:`%d0`.
  41
  42   If ``TARGET_PROMOTE_FUNCTION_RETURN`` returns true, you must apply
  43   the same promotion rules specified in ``PROMOTE_MODE`` if
  44   :samp:`{valtype}` is a scalar type.
  45
  46   If the precise function being called is known, :samp:`{func}` is a tree
  47   node (``FUNCTION_DECL``) for it; otherwise, :samp:`{func}` is a null
  48   pointer.  This makes it possible to use a different value-returning
  49   convention for specific functions when all their calls are
  50   known.
  51
  52   Some target machines have 'register windows' so that the register in
  53   which a function returns its value is not the same as the one in which
  54   the caller sees the value.  For such machines, you should return
  55   different RTX depending on :samp:`{outgoing}`.
  56
  57   ``TARGET_FUNCTION_VALUE`` is not used for return values with
  58   aggregate data types, because these are returned in another way.  See
  59   ``TARGET_STRUCT_VALUE_RTX`` and related macros, below.
  60
  61 .. hook-end
  62
  63 .. c:macro:: FUNCTION_VALUE (valtype, func)
  64
  65   This macro has been deprecated.  Use ``TARGET_FUNCTION_VALUE`` for
  66   a new target instead.
  67
  68 .. c:macro:: LIBCALL_VALUE (mode)
  69
  70   A C expression to create an RTX representing the place where a library
  71   function returns a value of mode :samp:`{mode}`.
  72
  73   Note that 'library function' in this context means a compiler
  74   support routine, used to perform arithmetic, whose name is known
  75   specially by the compiler and was not mentioned in the C code being
  76   compiled.
  77
  78 .. function:: rtx TARGET_LIBCALL_VALUE (machine_mode mode, const_rtx fun)
  79
  80   .. hook-start:TARGET_LIBCALL_VALUE
  81
  82   Define this hook if the back-end needs to know the name of the libcall
  83   function in order to determine where the result should be returned.
  84
  85   The mode of the result is given by :samp:`{mode}` and the name of the called
  86   library function is given by :samp:`{fun}`.  The hook should return an RTX
  87   representing the place where the library function result will be returned.
  88
  89   If this hook is not defined, then LIBCALL_VALUE will be used.
  90
  91 .. hook-end
  92
  93 .. c:macro:: FUNCTION_VALUE_REGNO_P (regno)
  94
  95   A C expression that is nonzero if :samp:`{regno}` is the number of a hard
  96   register in which the values of called function may come back.
  97
  98   A register whose use for returning values is limited to serving as the
  99   second of a pair (for a value of type ``double``, say) need not be
 100   recognized by this macro.  So for most machines, this definition
 101   suffices:
 102
 103   .. code-block:: c++
 104
 105     #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
 106
 107   If the machine has register windows, so that the caller and the called
 108   function use different registers for the return value, this macro
 109   should recognize only the caller's register numbers.
 110
 111   This macro has been deprecated.  Use ``TARGET_FUNCTION_VALUE_REGNO_P``
 112   for a new target instead.
 113
 114 .. function:: bool TARGET_FUNCTION_VALUE_REGNO_P (const unsigned int regno)
 115
 116   .. hook-start:TARGET_FUNCTION_VALUE_REGNO_P
 117
 118   A target hook that return ``true`` if :samp:`{regno}` is the number of a hard
 119   register in which the values of called function may come back.
 120
 121   A register whose use for returning values is limited to serving as the
 122   second of a pair (for a value of type ``double``, say) need not be
 123   recognized by this target hook.
 124
 125   If the machine has register windows, so that the caller and the called
 126   function use different registers for the return value, this target hook
 127   should recognize only the caller's register numbers.
 128
 129   If this hook is not defined, then FUNCTION_VALUE_REGNO_P will be used.
 130
 131 .. hook-end
 132
 133 .. c:macro:: APPLY_RESULT_SIZE
 134
 135   Define this macro if :samp:`untyped_call` and :samp:`untyped_return`
 136   need more space than is implied by ``FUNCTION_VALUE_REGNO_P`` for
 137   saving and restoring an arbitrary return value.
 138
 139 .. c:var:: bool TARGET_OMIT_STRUCT_RETURN_REG
 140
 141   .. hook-start:TARGET_OMIT_STRUCT_RETURN_REG
 142
 143   Normally, when a function returns a structure by memory, the address
 144   is passed as an invisible pointer argument, but the compiler also
 145   arranges to return the address from the function like it would a normal
 146   pointer return value.  Define this to true if that behavior is
 147   undesirable on your target.
 148
 149 .. hook-end
 150
 151 .. function:: bool TARGET_RETURN_IN_MSB (const_tree type)
 152
 153   .. hook-start:TARGET_RETURN_IN_MSB
 154
 155   This hook should return true if values of type :samp:`{type}` are returned
 156   at the most significant end of a register (in other words, if they are
 157   padded at the least significant end).  You can assume that :samp:`{type}`
 158   is returned in a register; the caller is required to check this.
 159
 160   Note that the register provided by ``TARGET_FUNCTION_VALUE`` must
 161   be able to hold the complete return value.  For example, if a 1-, 2-
 162   or 3-byte structure is returned at the most significant end of a
 163   4-byte register, ``TARGET_FUNCTION_VALUE`` should provide an
 164   ``SImode`` rtx.
 165
 166 .. hook-end