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 .. _arm-function-attributes:
   7
   8 ARM Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported for ARM targets:
  12
  13 .. index:: general-regs-only function attribute, ARM
  14
  15 .. arm-fn-attr:: general-regs-only
  16
  17   Indicates that no floating-point or Advanced SIMD registers should be
  18   used when generating code for this function.  If the function explicitly
  19   uses floating-point code, then the compiler gives an error.  This is
  20   the same behavior as that of the command-line option
  21   :option:`-mgeneral-regs-only`.
  22
  23 .. index:: interrupt function attribute, ARM
  24
  25 .. arm-fn-attr:: interrupt
  26
  27   Use this attribute to indicate
  28   that the specified function is an interrupt handler.  The compiler generates
  29   function entry and exit sequences suitable for use in an interrupt handler
  30   when this attribute is present.
  31
  32   You can specify the kind of interrupt to be handled by
  33   adding an optional parameter to the interrupt attribute like this:
  34
  35   .. code-block:: c++
  36
  37     void f () __attribute__ ((interrupt ("IRQ")));
  38
  39   Permissible values for this parameter are: ``IRQ``, ``FIQ``,
  40   ``SWI``, ``ABORT`` and ``UNDEF``.
  41
  42   On ARMv7-M the interrupt type is ignored, and the attribute means the function
  43   may be called with a word-aligned stack pointer.
  44
  45 .. index:: isr function attribute, ARM
  46
  47 .. arm-fn-attr:: isr
  48
  49   Use this attribute on ARM to write Interrupt Service Routines. This is an
  50   alias to the :arm-fn-attr:`interrupt` attribute above.
  51
  52 .. index:: long_call function attribute, ARM, short_call function attribute, ARM, indirect calls, ARM
  53
  54 .. arm-fn-attr:: long_call, short_call
  55
  56   These attributes specify how a particular function is called.
  57   These attributes override the
  58   :option:`-mlong-calls` (see :ref:`arm-options`)
  59   command-line switch and ``#pragma long_calls`` settings.  For ARM, the
  60   :arm-fn-attr:`long_call` attribute indicates that the function might be far
  61   away from the call site and require a different (more expensive)
  62   calling sequence.   The ``short_call`` attribute always places
  63   the offset to the function from the call site into the :samp:`BL`
  64   instruction directly.
  65
  66 .. index:: naked function attribute, ARM
  67
  68 .. arm-fn-attr:: naked
  69
  70   This attribute allows the compiler to construct the
  71   requisite function declaration, while allowing the body of the
  72   function to be assembly code. The specified function will not have
  73   prologue/epilogue sequences generated by the compiler. Only basic
  74   ``asm`` statements can safely be included in naked functions
  75   (see :ref:`basic-asm`). While using extended ``asm`` or a mixture of
  76   basic ``asm`` and C code may appear to work, they cannot be
  77   depended upon to work reliably and are not supported.
  78
  79 .. index:: pcs function attribute, ARM
  80
  81 .. arm-fn-attr:: pcs
  82
  83   The :arm-fn-attr:`pcs` attribute can be used to control the calling convention
  84   used for a function on ARM.  The attribute takes an argument that specifies
  85   the calling convention to use.
  86
  87   When compiling using the AAPCS ABI (or a variant of it) then valid
  88   values for the argument are ``"aapcs"`` and ``"aapcs-vfp"``.  In
  89   order to use a variant other than ``"aapcs"`` then the compiler must
  90   be permitted to use the appropriate co-processor registers (i.e., the
  91   VFP registers must be available in order to use ``"aapcs-vfp"``).
  92   For example,
  93
  94   .. code-block:: c++
  95
  96     /* Argument passed in r0, and result returned in r0+r1.  */
  97     double f2d (float) __attribute__((pcs("aapcs")));
  98
  99   Variadic functions always use the ``"aapcs"`` calling convention and
 100   the compiler rejects attempts to specify an alternative.
 101
 102 .. index:: target function attribute
 103
 104 .. arm-fn-attr:: target (options)
 105
 106   As discussed in :ref:`common-function-attributes`, this attribute
 107   allows specification of target-specific compilation options.
 108
 109   On ARM, the following options are allowed:
 110
 111   :samp:`thumb`
 112
 113     .. index:: target("thumb") function attribute, ARM
 114
 115     Force code generation in the Thumb (T16/T32) ISA, depending on the
 116     architecture level.
 117
 118   :samp:`arm`
 119
 120     .. index:: target("arm") function attribute, ARM
 121
 122     Force code generation in the ARM (A32) ISA.
 123
 124     Functions from different modes can be inlined in the caller's mode.
 125
 126   :samp:`fpu=`
 127
 128     .. index:: target("fpu=") function attribute, ARM
 129
 130     Specifies the fpu for which to tune the performance of this function.
 131     The behavior and permissible arguments are the same as for the :option:`-mfpu=`
 132     command-line option.
 133
 134   :samp:`arch=`
 135
 136     .. index:: arch= function attribute, ARM
 137
 138     Specifies the architecture version and architectural extensions to use
 139     for this function.  The behavior and permissible arguments are the same as
 140     for the :option:`-march=` command-line option.
 141
 142     The above target attributes can be specified as follows:
 143
 144     .. code-block:: c++
 145
 146       __attribute__((target("arch=armv8-a+crc")))
 147       int
 148       f (int a)
 149       {
 150         return a + 5;
 151       }
 152
 153     Additionally, the architectural extension string may be specified on its
 154     own.  This can be used to turn on and off particular architectural extensions
 155     without having to specify a particular architecture version or core.  Example:
 156
 157     .. code-block:: c++
 158
 159       __attribute__((target("+crc+nocrypto")))
 160       int
 161       foo (int a)
 162       {
 163         return a + 5;
 164       }
 165
 166     In this example ``target("+crc+nocrypto")`` enables the ``crc``
 167     extension and disables the ``crypto`` extension for the function ``foo``
 168     without modifying an existing :option:`-march=` or :option:`-mcpu` option.