From patchwork Sun Feb 18 12:00:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Georg-Johann Lay X-Patchwork-Id: 1900646 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=gjlay.de header.i=@gjlay.de header.a=rsa-sha256 header.s=strato-dkim-0002 header.b=qiomHX0V; dkim=pass header.d=gjlay.de header.i=@gjlay.de header.a=ed25519-sha256 header.s=strato-dkim-0003 header.b=3XFJK/Ts; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=server2.sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Td45Y12s4z1ybm for ; Sun, 18 Feb 2024 23:01:35 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 7ACA83861035 for ; Sun, 18 Feb 2024 12:01:31 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mo4-p00-ob.smtp.rzone.de (mo4-p00-ob.smtp.rzone.de [81.169.146.217]) by sourceware.org (Postfix) with ESMTPS id 728F5386184B for ; Sun, 18 Feb 2024 12:00:22 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 728F5386184B Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=gjlay.de Authentication-Results: sourceware.org; spf=none smtp.mailfrom=gjlay.de ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 728F5386184B Authentication-Results: server2.sourceware.org; arc=pass smtp.remote-ip=81.169.146.217 ARC-Seal: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1708257624; cv=pass; b=Lgu/7quJcU3X8JVeeUlNH2xmWWMfrss+x4hhj3QdtUASpliVdyTYVLi/6ki6VanC2LKWVUbM4fakKgHKMG5+eKy42ZdRlG/m+aaROkuSB4h937raeV9jHg04+3bBN3Osib3YH3bEnQ+/2eJblHk6UwWUY3wnfNa/1udXrYjQ+9A= ARC-Message-Signature: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1708257624; c=relaxed/simple; bh=bxJYceeDj7UgfsI93F90Y+Zbu0fFhtM2eDCoPYzogEc=; h=DKIM-Signature:DKIM-Signature:Message-ID:Date:MIME-Version:From: To:Subject; b=T+Ix/FzhaxiOW81FquSqrhtTEFEjFX94RnvebZATKA9uWxce8DqhXl+5ii/t36rXIi8DXepyHq9SZhNo/atRQfMVttH7T3iaobB7ufMtp6IzaUEujrBOvCEO+Rt8SHha5jhFpS2zRwptDyzVclLq82MMujB/Tc2h/3RZGw4cn0o= ARC-Authentication-Results: i=2; server2.sourceware.org ARC-Seal: i=1; a=rsa-sha256; t=1708257621; cv=none; d=strato.com; s=strato-dkim-0002; b=rs1njor4f4+Y2nEQIIUfRM5uGOQK3dhe/UINpKP6SBK9Vp2AOOgGjh6noq2FnGSKhr l7R4JZpuYg+vVCEquthrcIRrlhE2tb5RHPHdzlAUY9FvZBU9TSMgFYJ7dbRwo2Xx2R6R wLCDxw3107x7f8ZEHn35AP6MYSk/QNMFdEr24wBr5eRBv63RKlN6oLgvdxdgZVJ1d6Ah GIaDZx7+F+0cmUkULO2KidWVaLNmWi63bRWoxFHizU4QIAuH5XFK3I0i5NInwPYaZtIq Lp5fBGCXINOJKplH/Eo3mNUKYZI2pn1YZfjMkBeLF9bWT+vf7UiajipXsUXr1PJKLfJ2 cgCQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; t=1708257621; s=strato-dkim-0002; d=strato.com; h=Subject:To:From:Date:Message-ID:Cc:Date:From:Subject:Sender; bh=rQlc6/LSjB2YLF1kQjJuQD9QxT3lbSHRCXxl6DosEB4=; b=ohHfUIBenCPa8eYBmFhR1iNpQjMYOFCS+C3tVuZleRdk+4037TLFAjjr4TKrPRGa6n bbmR+DLlFl1XGfnFAN3j5imbzIl1jBizepx24owSj7hAeCu6usMug1EzJRr8/lt5TXPC k9EK0kUuEWl9bHwXc2EeznLnebdiUWAVPdAQMQxf2VjUU8f5R54WgqwRb5mjS5dCZ1Wj OS1nzOYAokUcaNwstNEKf2ahl6Q6eTvPIzG31I+hH0XOqpk809Wt++COfr6QVIeRC3+z Z3uhq71BUU8n9e8Qz9kkqopeE5ZdU1iW4X1JN5XoSkQBCzAkQAJYdlGlq8wySYE593Un H4Fg== ARC-Authentication-Results: i=1; strato.com; arc=none; dkim=none X-RZG-CLASS-ID: mo00 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1708257621; s=strato-dkim-0002; d=gjlay.de; h=Subject:To:From:Date:Message-ID:Cc:Date:From:Subject:Sender; bh=rQlc6/LSjB2YLF1kQjJuQD9QxT3lbSHRCXxl6DosEB4=; b=qiomHX0Vl9dNXwZWKraSp91wA5poGOC9Vz2QuvNyq7dRZzZcsGw+R1dncmlgJcgiHB BOuI8ux8QrYoAwh3Mzz944sziJOfaMN88OayzV9YYTrr4317kDhwLiQEfhWuJqDhPYjY 9gLOz89p6pR/0kwesaT9yuhpSTykWmwUVZeImBsUJSHiMo9DYNslSDSvZb4HsU3jiI7e Xt+9a5Hi6xHhAol2t3IbPFqg0hImzTJY+RGvqEE/LpCCkbKfdbJug2pJdd5BTvM92aX1 YPxhQHENMWrN0PX1ujZ7HnaZX5GHCTmH6DpBIxEwZ31M2rCX/mO5XeH5OPFnfno3KVyV nnlg== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; t=1708257621; s=strato-dkim-0003; d=gjlay.de; h=Subject:To:From:Date:Message-ID:Cc:Date:From:Subject:Sender; bh=rQlc6/LSjB2YLF1kQjJuQD9QxT3lbSHRCXxl6DosEB4=; b=3XFJK/TsgotbnM2BwGD9n85Y1SSU2d40Wm41aGtE11k4mvo6YvO0PqacmBD/Itcslf IoDv2FMoZ9NQ6WSgBnDw== X-RZG-AUTH: ":LXoWVUeid/7A29J/hMvvT3koxZnKT7Qq0xotTetVnKkSgcSjpmy9KwoMJ/K0VA==" Received: from [192.168.2.102] by smtp.strato.de (RZmta 49.11.2 DYNA|AUTH) with ESMTPSA id Lb68c601IC0KKtj (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits)) (Client did not present a certificate) for ; Sun, 18 Feb 2024 13:00:20 +0100 (CET) Message-ID: <1a8aee9b-a025-47f8-a3e0-a2b19b89f745@gjlay.de> Date: Sun, 18 Feb 2024 13:00:20 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US From: Georg-Johann Lay To: gcc-patches@gcc.gnu.org Subject: [patch,avr,applied] Minor improvements to option and attribute documentation. X-Spam-Status: No, score=-11.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_PASS, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Applied this patch. Johann --- AVR: Improve documentation for -mmcu=. gcc/ * doc/invoke.texi (AVR Options) <-mmcu>: Remove "Atmel". Note on complete device support. 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 --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 2b8ba1949bf..e048404dffe 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 diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index d0e67729f56..e18886e0ac7 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -23732,12 +23732,22 @@ These options are defined for AVR implementations: @table @gcctabopt @opindex mmcu @item -mmcu=@var{mcu} -Specify Atmel AVR instruction set architectures (ISA) or MCU type. - -The default for this option is@tie{}@samp{avr2}. - -GCC supports the following AVR devices and ISAs: - +Specify the AVR instruction set architecture (ISA) or device type. +The default for this option is@tie{}@code{avr2}. + +The following AVR devices and ISAs are supported. +@emph{Note:} A complete device support consists of +startup code @code{crt@var{mcu}.o}, a device header @code{avr/io*.h}, +a device library @code{lib@var{mcu}.a} and a +@uref{https://gcc.gnu.org/wiki/avr-gcc#spec-files,device-specs} file +@code{specs-@var{mcu}}. Only the latter is provided by the compiler +according the supported @code{@var{mcu}}s below. The rest is supported +by @w{@uref{https://www.nongnu.org/avr-libc/,AVR-LibC}}, or by means of +@uref{https://gcc.gnu.org/wiki/avr-gcc#atpack,@code{atpack}} files +from the hardware manufacturer. + +@c Auto-generated. Re-build when new devices are added to avr-mcus.def +@c by running "make avr-mcus" in $builddir/gcc. @include avr-mmcu.texi @opindex mabsdata