[gcc r14-9056] AVR: Add examples for ISR macro to interrupt attribute doc.

[gcc r14-9056] AVR: Add examples for ISR macro to interrupt attribute doc.

[Georg-Johann Lay]

https://gcc.gnu.org/g:0b2284bb263e5fddc3e6921f6342e95bd157fc6d

commit r14-9056-g0b2284bb263e5fddc3e6921f6342e95bd157fc6d
Author: Georg-Johann Lay <avr@gjlay.de>
Date:   Sun Feb 18 11:59:06 2024 +0100

    AVR: Add examples for ISR macro to interrupt attribute doc.
    
    gcc/
            * doc/extend.texi (AVR Function Attributes): Fuse description
            of "signal" and "interrupt" attribute.  Link pseudo instruction.

Diff:
---
 gcc/doc/extend.texi | 71 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 41 insertions(+), 30 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 2b8ba1949bf1..e048404dffe5 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -5060,20 +5060,47 @@ without modifying an existing @option{-march=} or @option{-mcpu} option.
 These function attributes are supported by the AVR back end:
 
 @table @code
+@cindex @code{signal} function attribute, AVR
 @cindex @code{interrupt} function attribute, AVR
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler.  The compiler generates
+@item signal
+@itemx interrupt
+The function is an interrupt service routine (ISR).  The compiler generates
 function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+when one of the attributes is present.
+
+The AVR hardware globally disables interrupts when an interrupt is executed.
+
+@itemize @bullet
+@item ISRs with the @code{signal} attribute do not re-enable interrupts.
+It is save to enable interrupts in a @code{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.
+
+@item ISRs with the @code{interrupt} attribute re-enable interrupts.
+The first instruction of the routine is a @code{SEI} instruction to
+globally enable interrupts.
+@end itemize
+
+The recommended way to use these attributes is by means of the
+@code{ISR} macro provided by @code{avr/interrupt.h} from
+@w{@uref{https://www.nongnu.org/avr-libc/user-manual/group__avr__interrupts.html,,AVR-LibC}}:
+@example
+#include <avr/interrupt.h>
 
-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 @code{SEI} instruction to
-re-enable interrupts.  See also the @code{signal} function attribute
-that does not insert a @code{SEI} instruction.  If both @code{signal} and
-@code{interrupt} are specified for the same function, @code{signal}
-is silently ignored.
+ISR (INT0_vect) // Uses the "signal" attribute.
+@{
+    // Code
+@}
+
+ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
+@{
+    // Code
+@}
+@end example
+
+When both @code{signal} and @code{interrupt} are specified for the same
+function, then @code{signal} is silently ignored.
 
 @cindex @code{naked} function attribute, AVR
 @item naked
@@ -5088,7 +5115,9 @@ depended upon to work reliably and are not supported.
 
 @cindex @code{no_gccisr} function attribute, AVR
 @item no_gccisr
-Do not use @code{__gcc_isr} pseudo instructions in a function with
+Do not use the @code{__gcc_isr}
+@uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
+in a function with
 the @code{interrupt} or @code{signal} attribute aka. interrupt
 service routine (ISR).
 Use this attribute if the preamble of the ISR prologue should always read
@@ -5141,24 +5170,6 @@ or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
 as needed.
 @end itemize
 
-@cindex @code{signal} function attribute, AVR
-@item 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 @code{interrupt} function attribute. 
-
-The AVR hardware globally disables interrupts when an interrupt is executed.
-Interrupt handler functions defined with the @code{signal} attribute
-do not re-enable interrupts.  It is save to enable interrupts in a
-@code{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 @code{signal} and @code{interrupt} are specified for the same
-function, @code{signal} is silently ignored.
 @end table
 
 @node Blackfin Function Attributes