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

.. _avr-function-attributes:

AVR Function Attributes
^^^^^^^^^^^^^^^^^^^^^^^

These function attributes are supported by the AVR back end:

.. index:: interrupt function attribute, AVR

.. avr-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.

  On the AVR, the hardware globally disables interrupts when an
  interrupt is executed.  The first instruction of an interrupt handler
  declared with this attribute is a ``SEI`` instruction to
  re-enable interrupts.  See also the :avr-fn-attr:`signal` function attribute
  that does not insert a ``SEI`` instruction.  If both :avr-fn-attr:`signal` and
  :avr-fn-attr:`interrupt` are specified for the same function, :avr-fn-attr:`signal`
  is silently ignored.

.. index:: naked function attribute, AVR

.. avr-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:: no_gccisr function attribute, AVR

.. avr-fn-attr:: no_gccisr

  Do not use ``__gcc_isr`` pseudo instructions in a function with
  the :avr-fn-attr:`interrupt` or :avr-fn-attr:`signal` attribute aka. interrupt
  service routine (ISR).
  Use this attribute if the preamble of the ISR prologue should always read

  .. code-block:: c++

    push  __zero_reg__
    push  __tmp_reg__
    in    __tmp_reg__, __SREG__
    push  __tmp_reg__
    clr   __zero_reg__

  and accordingly for the postamble of the epilogue --- no matter whether
  the mentioned registers are actually used in the ISR or not.
  Situations where you might want to use this attribute include:

  * Code that (effectively) clobbers bits of ``SREG`` other than the
    ``I`` -flag by writing to the memory location of ``SREG``.

  * Code that uses inline assembler to jump to a different function which
    expects (parts of) the prologue code as outlined above to be present.

  To disable ``__gcc_isr`` generation for the whole compilation unit,
  there is option :option:`-mno-gas-isr-prologues`, see :ref:`avr-options`.

.. index:: OS_main function attribute, AVR, OS_task function attribute, AVR

.. avr-fn-attr:: OS_main, OS_task

  On AVR, functions with the :avr-fn-attr:`OS_main` or ``OS_task`` attribute
  do not save/restore any call-saved register in their prologue/epilogue.

  The :avr-fn-attr:`OS_main` attribute can be used when there *is
  guarantee* that interrupts are disabled at the time when the function
  is entered.  This saves resources when the stack pointer has to be
  changed to set up a frame for local variables.

  The ``OS_task`` attribute can be used when there is *no
  guarantee* that interrupts are disabled at that time when the function
  is entered like for, e.g. task functions in a multi-threading operating
  system. In that case, changing the stack pointer register is
  guarded by save/clear/restore of the global interrupt enable flag.

  The differences to the :avr-fn-attr:`naked` function attribute are:

  * :avr-fn-attr:`naked` functions do not have a return instruction whereas 
    :avr-fn-attr:`OS_main` and ``OS_task`` functions have a ``RET`` or
    ``RETI`` return instruction.

  * :avr-fn-attr:`naked` functions do not set up a frame for local variables
    or a frame pointer whereas :avr-fn-attr:`OS_main` and ``OS_task`` do this
    as needed.

.. index:: signal function attribute, AVR

.. avr-fn-attr:: signal

  Use this attribute on the AVR 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.

  See also the :avr-fn-attr:`interrupt` function attribute. 

  The AVR hardware globally disables interrupts when an interrupt is executed.
  Interrupt handler functions defined with the :avr-fn-attr:`signal` attribute
  do not re-enable interrupts.  It is save to enable interrupts in a
  :avr-fn-attr:`signal` handler.  This 'save' only applies to the code
  generated by the compiler and not to the IRQ layout of the
  application which is responsibility of the application.

  If both :avr-fn-attr:`signal` and :avr-fn-attr:`interrupt` are specified for the same
  function, :avr-fn-attr:`signal` is silently ignored.