From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1733) id BFEB93861812; Sun, 18 Feb 2024 12:01:02 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BFEB93861812 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1708257662; bh=/KCOBlGfMpeFixGBRRkYeBavsLyAJkzmBRdxbbhvXWU=; h=From:To:Subject:Date:From; b=CS0O7vawKHJ5+CenoCvLsq5kH3Sb+dQRVjl+f/wVm+2KWAJvPbG3xpCt4vtwRHNMe 0ERgqfkgkK7xzFXn/7UpaoKzfPNZKqkwHqERBtBW2OzBVDLARLdVMGW5TBJLH0j8qX YyLkaW8wo9jVtG7SPv1c/noSswlYM6uxZW1WWwgk= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Georg-Johann Lay To: gcc-cvs@gcc.gnu.org Subject: [gcc r14-9056] AVR: Add examples for ISR macro to interrupt attribute doc. X-Act-Checkin: gcc X-Git-Author: Georg-Johann Lay X-Git-Refname: refs/heads/master X-Git-Oldrev: 3796216bfa49b5ca288afe0760931a4c5b8ea346 X-Git-Newrev: 0b2284bb263e5fddc3e6921f6342e95bd157fc6d Message-Id: <20240218120102.BFEB93861812@sourceware.org> Date: Sun, 18 Feb 2024 12:01:02 +0000 (GMT) List-Id: https://gcc.gnu.org/g:0b2284bb263e5fddc3e6921f6342e95bd157fc6d commit r14-9056-g0b2284bb263e5fddc3e6921f6342e95bd157fc6d Author: Georg-Johann Lay 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 -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