AVR: Propose to use attribute signal(n) via AVR-LibC's ISR_N.

gcc/
	* doc/extend.texi (AVR Function Attributes): Propose to use
	attribute signal(n) via AVR-LibC's ISR_N from avr/interrupt.h

1 files changed, 23 insertions, 7 deletions

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 927aa24..48b27ff 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -5147,22 +5147,38 @@ the attribute, rather than providing the ISR name itself as the function name:
 
 @example
 __attribute__((signal(1)))
-void my_handler (void)
+static void my_handler (void)
 @{
    // Code for __vector_1
 @}
+@end example
 
-#include <avr/io.h>
+Notice that the handler function needs not to be externally visible.
+The recommended way to use these attributes is by means of the
+@code{ISR_N} 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>
 
-__attribute__((__signal__(PCINT0_vect_num, PCINT1_vect_num)))
-static void my_pcint0_1_handler (void)
+ISR_N (PCINT0_vect_num)
+static void my_pcint0_handler (void)
 @{
-   // Code for PCINT0 and PCINT1 (__vector_3 and __vector_4
-   // on ATmega328).
+   // Code
+@}
+
+ISR_N (ADC_vect_num, ISR_NOBLOCK)
+static void my_adc_handler (void)
+@{
+    // Code
 @}
 @end example
 
-Notice that the handler function needs not to be externally visible.
+@code{ISR_N} can be specified more than once, in which case several
+interrupt vectors are pointing to the same handler function.  This
+is similar to the @code{ISR_ALIASOF} macro provided by AVR-LibC, but
+without the overhead introduced by @code{ISR_ALIASOF}.
+
 
 @cindex @code{noblock} function attribute, AVR
 @item noblock