..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. _arm-function-attributes:

ARM Function Attributes
^^^^^^^^^^^^^^^^^^^^^^^

These function attributes are supported for ARM targets:

.. index:: general-regs-only function attribute, ARM

.. arm-fn-attr:: general-regs-only

  Indicates that no floating-point or Advanced SIMD registers should be
  used when generating code for this function.  If the function explicitly
  uses floating-point code, then the compiler gives an error.  This is
  the same behavior as that of the command-line option
  :option:`-mgeneral-regs-only`.

.. index:: interrupt function attribute, ARM

.. arm-fn-attr:: interrupt

  Use this attribute to indicate
  that the specified function is an interrupt handler.  The compiler generates
  function entry and exit sequences suitable for use in an interrupt handler
  when this attribute is present.

  You can specify the kind of interrupt to be handled by
  adding an optional parameter to the interrupt attribute like this:

  .. code-block:: c++

    void f () __attribute__ ((interrupt ("IRQ")));

  Permissible values for this parameter are: ``IRQ``, ``FIQ``,
  ``SWI``, ``ABORT`` and ``UNDEF``.

  On ARMv7-M the interrupt type is ignored, and the attribute means the function
  may be called with a word-aligned stack pointer.

.. index:: isr function attribute, ARM

.. arm-fn-attr:: isr

  Use this attribute on ARM to write Interrupt Service Routines. This is an
  alias to the :arm-fn-attr:`interrupt` attribute above.

.. index:: long_call function attribute, ARM, short_call function attribute, ARM, indirect calls, ARM

.. arm-fn-attr:: long_call, short_call

  These attributes specify how a particular function is called.
  These attributes override the
  :option:`-mlong-calls` (see :ref:`arm-options`)
  command-line switch and ``#pragma long_calls`` settings.  For ARM, the
  :arm-fn-attr:`long_call` attribute indicates that the function might be far
  away from the call site and require a different (more expensive)
  calling sequence.   The ``short_call`` attribute always places
  the offset to the function from the call site into the :samp:`BL`
  instruction directly.

.. index:: naked function attribute, ARM

.. arm-fn-attr:: naked

  This attribute allows the compiler to construct the
  requisite function declaration, while allowing the body of the
  function to be assembly code. The specified function will not have
  prologue/epilogue sequences generated by the compiler. Only basic
  ``asm`` statements can safely be included in naked functions
  (see :ref:`basic-asm`). While using extended ``asm`` or a mixture of
  basic ``asm`` and C code may appear to work, they cannot be
  depended upon to work reliably and are not supported.

.. index:: pcs function attribute, ARM

.. arm-fn-attr:: pcs

  The :arm-fn-attr:`pcs` attribute can be used to control the calling convention
  used for a function on ARM.  The attribute takes an argument that specifies
  the calling convention to use.

  When compiling using the AAPCS ABI (or a variant of it) then valid
  values for the argument are ``"aapcs"`` and ``"aapcs-vfp"``.  In
  order to use a variant other than ``"aapcs"`` then the compiler must
  be permitted to use the appropriate co-processor registers (i.e., the
  VFP registers must be available in order to use ``"aapcs-vfp"``).
  For example,

  .. code-block:: c++

    /* Argument passed in r0, and result returned in r0+r1.  */
    double f2d (float) __attribute__((pcs("aapcs")));

  Variadic functions always use the ``"aapcs"`` calling convention and
  the compiler rejects attempts to specify an alternative.

.. index:: target function attribute

.. arm-fn-attr:: target (options)

  As discussed in :ref:`common-function-attributes`, this attribute 
  allows specification of target-specific compilation options.

  On ARM, the following options are allowed:

  :samp:`thumb`

    .. index:: target("thumb") function attribute, ARM

    Force code generation in the Thumb (T16/T32) ISA, depending on the
    architecture level.

  :samp:`arm`

    .. index:: target("arm") function attribute, ARM

    Force code generation in the ARM (A32) ISA.

    Functions from different modes can be inlined in the caller's mode.

  :samp:`fpu=`

    .. index:: target("fpu=") function attribute, ARM

    Specifies the fpu for which to tune the performance of this function.
    The behavior and permissible arguments are the same as for the :option:`-mfpu=`
    command-line option.

  :samp:`arch=`

    .. index:: arch= function attribute, ARM

    Specifies the architecture version and architectural extensions to use
    for this function.  The behavior and permissible arguments are the same as
    for the :option:`-march=` command-line option.

    The above target attributes can be specified as follows:

    .. code-block:: c++

      __attribute__((target("arch=armv8-a+crc")))
      int
      f (int a)
      {
        return a + 5;
      }

    Additionally, the architectural extension string may be specified on its
    own.  This can be used to turn on and off particular architectural extensions
    without having to specify a particular architecture version or core.  Example:

    .. code-block:: c++

      __attribute__((target("+crc+nocrypto")))
      int
      foo (int a)
      {
        return a + 5;
      }

    In this example ``target("+crc+nocrypto")`` enables the ``crc``
    extension and disables the ``crypto`` extension for the function ``foo``
    without modifying an existing :option:`-march=` or :option:`-mcpu` option.