gcc: AVR Function Attributes

1 
1 6.31.5 AVR Function Attributes
1 ------------------------------
1 
1 These function attributes are supported by the AVR back end:
1 
1 'interrupt'
1      Use this attribute to indicate that the specified function is an
1      interrupt handler.  The compiler generates function entry and exit
1      sequences suitable for use in an interrupt handler when this
1      attribute is present.
1 
1      On the AVR, the hardware globally disables interrupts when an
1      interrupt is executed.  The first instruction of an interrupt
1      handler declared with this attribute is a 'SEI' instruction to
1      re-enable interrupts.  See also the 'signal' function attribute
1      that does not insert a 'SEI' instruction.  If both 'signal' and
1      'interrupt' are specified for the same function, 'signal' is
1      silently ignored.
1 
1 'naked'
1      This attribute allows the compiler to construct the requisite
1      function declaration, while allowing the body of the function to be
1      assembly code.  The specified function will not have
1      prologue/epilogue sequences generated by the compiler.  Only basic
11      'asm' statements can safely be included in naked functions (⇒
      Basic Asm).  While using extended 'asm' or a mixture of basic
1      'asm' and C code may appear to work, they cannot be depended upon
1      to work reliably and are not supported.
1 
1 'no_gccisr'
1      Do not use '__gcc_isr' pseudo instructions in a function with the
1      'interrupt' or 'signal' attribute aka.  interrupt service routine
1      (ISR). Use this attribute if the preamble of the ISR prologue
1      should always read
1           push  __zero_reg__
1           push  __tmp_reg__
1           in    __tmp_reg__, __SREG__
1           push  __tmp_reg__
1           clr   __zero_reg__
1      and accordingly for the postamble of the epilogue -- no matter
1      whether the mentioned registers are actually used in the ISR or
1      not.  Situations where you might want to use this attribute
1      include:
1         * Code that (effectively) clobbers bits of 'SREG' other than the
1           'I'-flag by writing to the memory location of 'SREG'.
1         * Code that uses inline assembler to jump to a different
1           function which expects (parts of) the prologue code as
1           outlined above to be present.
1      To disable '__gcc_isr' generation for the whole compilation unit,
1      there is option '-mno-gas-isr-prologues', ⇒AVR Options.
1 
1 'OS_main'
1 'OS_task'
1      On AVR, functions with the 'OS_main' or 'OS_task' attribute do not
1      save/restore any call-saved register in their prologue/epilogue.
1 
1      The 'OS_main' attribute can be used when there _is guarantee_ that
1      interrupts are disabled at the time when the function is entered.
1      This saves resources when the stack pointer has to be changed to
1      set up a frame for local variables.
1 
1      The 'OS_task' attribute can be used when there is _no guarantee_
1      that interrupts are disabled at that time when the function is
1      entered like for, e.g.  task functions in a multi-threading
1      operating system.  In that case, changing the stack pointer
1      register is guarded by save/clear/restore of the global interrupt
1      enable flag.
1 
1      The differences to the 'naked' function attribute are:
1         * 'naked' functions do not have a return instruction whereas
1           'OS_main' and 'OS_task' functions have a 'RET' or 'RETI'
1           return instruction.
1         * 'naked' functions do not set up a frame for local variables or
1           a frame pointer whereas 'OS_main' and 'OS_task' do this as
1           needed.
1 
1 'signal'
1      Use this attribute on the AVR to indicate that the specified
1      function is an interrupt handler.  The compiler generates function
1      entry and exit sequences suitable for use in an interrupt handler
1      when this attribute is present.
1 
1      See also the 'interrupt' function attribute.
1 
1      The AVR hardware globally disables interrupts when an interrupt is
1      executed.  Interrupt handler functions defined with the 'signal'
1      attribute do not re-enable interrupts.  It is save to enable
1      interrupts in a 'signal' handler.  This "save" only applies to the
1      code generated by the compiler and not to the IRQ layout of the
1      application which is responsibility of the application.
1 
1      If both 'signal' and 'interrupt' are specified for the same
1      function, 'signal' is silently ignored.
1