]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | |
3ed1b4ce | 120 | function, :avr-fn-attr:`signal` is silently ignored. |