gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/avr-function-attributes.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 .. _avr-function-attributes:
   7
   8 AVR Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported by the AVR back end:
  12
  13 .. index:: interrupt function attribute, AVR
  14
  15 .. avr-fn-attr:: interrupt
  16
  17   Use this attribute to indicate
  18   that the specified function is an interrupt handler.  The compiler generates
  19   function entry and exit sequences suitable for use in an interrupt handler
  20   when this attribute is present.
  21
  22   On the AVR, the hardware globally disables interrupts when an
  23   interrupt is executed.  The first instruction of an interrupt handler
  24   declared with this attribute is a ``SEI`` instruction to
  25   re-enable interrupts.  See also the :avr-fn-attr:`signal` function attribute
  26   that does not insert a ``SEI`` instruction.  If both :avr-fn-attr:`signal` and
  27   :avr-fn-attr:`interrupt` are specified for the same function, :avr-fn-attr:`signal`
  28   is silently ignored.
  29
  30 .. index:: naked function attribute, AVR
  31
  32 .. avr-fn-attr:: naked
  33
  34   This attribute allows the compiler to construct the
  35   requisite function declaration, while allowing the body of the
  36   function to be assembly code. The specified function will not have
  37   prologue/epilogue sequences generated by the compiler. Only basic
  38   ``asm`` statements can safely be included in naked functions
  39   (see :ref:`basic-asm`). While using extended ``asm`` or a mixture of
  40   basic ``asm`` and C code may appear to work, they cannot be
  41   depended upon to work reliably and are not supported.
  42
  43 .. index:: no_gccisr function attribute, AVR
  44
  45 .. avr-fn-attr:: no_gccisr
  46
  47   Do not use ``__gcc_isr`` pseudo instructions in a function with
  48   the :avr-fn-attr:`interrupt` or :avr-fn-attr:`signal` attribute aka. interrupt
  49   service routine (ISR).
  50   Use this attribute if the preamble of the ISR prologue should always read
  51
  52   .. code-block:: c++
  53
  54     push  __zero_reg__
  55     push  __tmp_reg__
  56     in    __tmp_reg__, __SREG__
  57     push  __tmp_reg__
  58     clr   __zero_reg__
  59
  60   and accordingly for the postamble of the epilogue --- no matter whether
  61   the mentioned registers are actually used in the ISR or not.
  62   Situations where you might want to use this attribute include:
  63
  64   * Code that (effectively) clobbers bits of ``SREG`` other than the
  65     ``I`` -flag by writing to the memory location of ``SREG``.
  66
  67   * Code that uses inline assembler to jump to a different function which
  68     expects (parts of) the prologue code as outlined above to be present.
  69
  70   To disable ``__gcc_isr`` generation for the whole compilation unit,
  71   there is option :option:`-mno-gas-isr-prologues`, see :ref:`avr-options`.
  72
  73 .. index:: OS_main function attribute, AVR, OS_task function attribute, AVR
  74
  75 .. avr-fn-attr:: OS_main, OS_task
  76
  77   On AVR, functions with the :avr-fn-attr:`OS_main` or ``OS_task`` attribute
  78   do not save/restore any call-saved register in their prologue/epilogue.
  79
  80   The :avr-fn-attr:`OS_main` attribute can be used when there *is
  81   guarantee* that interrupts are disabled at the time when the function
  82   is entered.  This saves resources when the stack pointer has to be
  83   changed to set up a frame for local variables.
  84
  85   The ``OS_task`` attribute can be used when there is *no
  86   guarantee* that interrupts are disabled at that time when the function
  87   is entered like for, e.g. task functions in a multi-threading operating
  88   system. In that case, changing the stack pointer register is
  89   guarded by save/clear/restore of the global interrupt enable flag.
  90
  91   The differences to the :avr-fn-attr:`naked` function attribute are:
  92
  93   * :avr-fn-attr:`naked` functions do not have a return instruction whereas
  94     :avr-fn-attr:`OS_main` and ``OS_task`` functions have a ``RET`` or
  95     ``RETI`` return instruction.
  96
  97   * :avr-fn-attr:`naked` functions do not set up a frame for local variables
  98     or a frame pointer whereas :avr-fn-attr:`OS_main` and ``OS_task`` do this
  99     as needed.
 100
 101 .. index:: signal function attribute, AVR
 102
 103 .. avr-fn-attr:: signal
 104
 105   Use this attribute on the AVR to indicate that the specified
 106   function is an interrupt handler.  The compiler generates function
 107   entry and exit sequences suitable for use in an interrupt handler when this
 108   attribute is present.
 109
 110   See also the :avr-fn-attr:`interrupt` function attribute.
 111
 112   The AVR hardware globally disables interrupts when an interrupt is executed.
 113   Interrupt handler functions defined with the :avr-fn-attr:`signal` attribute
 114   do not re-enable interrupts.  It is save to enable interrupts in a
 115   :avr-fn-attr:`signal` handler.  This 'save' only applies to the code
 116   generated by the compiler and not to the IRQ layout of the
 117   application which is responsibility of the application.
 118
 119   If both :avr-fn-attr:`signal` and :avr-fn-attr:`interrupt` are specified for the same
 120   function, :avr-fn-attr:`signal` is silently ignored.