From 883755a164ac5e56b049e8bf3b68d12eab3962a9 Mon Sep 17 00:00:00 2001 From: David Wohlferd Date: Mon, 19 May 2014 17:40:40 +0000 Subject: [PATCH] extend.texi: Create Label Attributes section, move all label attributes into it and reference it. 2014-05-19 David Wohlferd * doc/extend.texi: Create Label Attributes section, move all label attributes into it and reference it. From-SVN: r210621 --- gcc/ChangeLog | 5 +++ gcc/doc/extend.texi | 119 ++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 89 insertions(+), 35 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 06f6bb2..91369fc 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2014-05-19 David Wohlferd + + * doc/extend.texi: Create Label Attributes section, + move all label attributes into it and reference it. + 2014-05-19 Richard Earnshaw * arm.c (thumb1_reorg): When scanning backwards skip anything diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 2009c75..f36efb0 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -55,6 +55,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Mixed Declarations:: Mixing declarations and code. * Function Attributes:: Declaring that functions have no side effects, or that they can never return. +* Label Attributes:: Specifying attributes on labels. * Attribute Syntax:: Formal syntax for attributes. * Function Prototypes:: Prototype declarations and old-style definitions. * C++ Comments:: C++ comments are recognized. @@ -2181,7 +2182,8 @@ attributes are currently defined for functions on all targets: @code{error} and @code{warning}. Several other attributes are defined for functions on particular target systems. Other attributes, including @code{section} are -supported for variables declarations (@pxref{Variable Attributes}) +supported for variables declarations (@pxref{Variable Attributes}), +labels (@pxref{Label Attributes}) and for types (@pxref{Type Attributes}). GCC plugins may provide their own attributes. @@ -3617,8 +3619,8 @@ than 2.96. @cindex @code{hot} function attribute The @code{hot} attribute on a function is used to inform the compiler that the function is a hot spot of the compiled program. The function is -optimized more aggressively and on many target it is placed into special -subsection of the text section so all hot functions appears close together +optimized more aggressively and on many targets it is placed into a special +subsection of the text section so all hot functions appear close together, improving locality. When profile feedback is available, via @option{-fprofile-use}, hot functions @@ -3627,23 +3629,14 @@ are automatically detected and this attribute is ignored. The @code{hot} attribute on functions is not implemented in GCC versions earlier than 4.3. -@cindex @code{hot} label attribute -The @code{hot} attribute on a label is used to inform the compiler that -path following the label are more likely than paths that are not so -annotated. This attribute is used in cases where @code{__builtin_expect} -cannot be used, for instance with computed goto or @code{asm goto}. - -The @code{hot} attribute on labels is not implemented in GCC versions -earlier than 4.8. - @item cold @cindex @code{cold} function attribute The @code{cold} attribute on functions is used to inform the compiler that the function is unlikely to be executed. The function is optimized for -size rather than speed and on many targets it is placed into special -subsection of the text section so all cold functions appears close together +size rather than speed and on many targets it is placed into a special +subsection of the text section so all cold functions appear close together, improving code locality of non-cold parts of program. The paths leading -to call of cold functions within code are marked as unlikely by the branch +to calls of cold functions within code are marked as unlikely by the branch prediction mechanism. It is thus useful to mark functions used to handle unlikely conditions, such as @code{perror}, as cold to improve optimization of hot functions that do call marked functions in rare occasions. @@ -3654,15 +3647,6 @@ are automatically detected and this attribute is ignored. The @code{cold} attribute on functions is not implemented in GCC versions earlier than 4.3. -@cindex @code{cold} label attribute -The @code{cold} attribute on labels is used to inform the compiler that -the path following the label is unlikely to be executed. This attribute -is used in cases where @code{__builtin_expect} cannot be used, for instance -with computed goto or @code{asm goto}. - -The @code{cold} attribute on labels is not implemented in GCC versions -earlier than 4.8. - @item no_sanitize_address @itemx no_address_safety_analysis @cindex @code{no_sanitize_address} function attribute @@ -4527,6 +4511,65 @@ attachment of attributes to their corresponding declarations, whereas @code{#pragma GCC} is of use for constructs that do not naturally form part of the grammar. @xref{Pragmas,,Pragmas Accepted by GCC}. +@node Label Attributes +@section Label Attributes +@cindex Label Attributes + +GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for +details of the exact syntax for using attributes. Other attributes are +available for functions (@pxref{Function Attributes}), variables +(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). + +This example uses the @code{cold} label attribute to indicate the +@code{ErrorHandling} branch is unlikely to be taken and that the +@code{ErrorHandling} label is unused: + +@smallexample + + asm goto ("some asm" : : : : NoError); + +/* This branch (the fallthru from the asm) is less commonly used */ +ErrorHandling: + __attribute__((cold, unused)); /* Semi-colon is required here */ + printf("error\n"); + return 0; + +NoError: + printf("no error\n"); + return 1; +@end smallexample + +@table @code +@item unused +@cindex @code{unused} label attribute +This feature is intended for program-generated code that may contain +unused labels, but which is compiled with @option{-Wall}. It is +not normally appropriate to use in it human-written code, though it +could be useful in cases where the code that jumps to the label is +contained within an @code{#ifdef} conditional. + +@item hot +@cindex @code{hot} label attribute +The @code{hot} attribute on a label is used to inform the compiler that +the path following the label is more likely than paths that are not so +annotated. This attribute is used in cases where @code{__builtin_expect} +cannot be used, for instance with computed goto or @code{asm goto}. + +The @code{hot} attribute on labels is not implemented in GCC versions +earlier than 4.8. + +@item cold +@cindex @code{cold} label attribute +The @code{cold} attribute on labels is used to inform the compiler that +the path following the label is unlikely to be executed. This attribute +is used in cases where @code{__builtin_expect} cannot be used, for instance +with computed goto or @code{asm goto}. + +The @code{cold} attribute on labels is not implemented in GCC versions +earlier than 4.8. + +@end table + @node Attribute Syntax @section Attribute Syntax @cindex attribute syntax @@ -4550,6 +4593,8 @@ applying to functions. @xref{Variable Attributes}, for details of the semantics of attributes applying to variables. @xref{Type Attributes}, for details of the semantics of attributes applying to structure, union and enumerated types. +@xref{Label Attributes}, for details of the semantics of attributes +applying to labels. An @dfn{attribute specifier} is of the form @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} @@ -4587,14 +4632,10 @@ with the list being a single string constant. An @dfn{attribute specifier list} is a sequence of one or more attribute specifiers, not separated by any other tokens. +@subsubheading Label Attributes + In GNU C, an attribute specifier list may appear after the colon following a -label, other than a @code{case} or @code{default} label. The only -attribute it makes sense to use after a label is @code{unused}. This -feature is intended for program-generated code that may contain unused labels, -but which is compiled with @option{-Wall}. It is -not normally appropriate to use in it human-written code, though it -could be useful in cases where the code that jumps to the label is -contained within an @code{#ifdef} conditional. GNU C++ only permits +label, other than a @code{case} or @code{default} label. GNU C++ only permits attributes on labels if the attribute specifier is immediately followed by a semicolon (i.e., the label applies to an empty statement). If the semicolon is missing, C++ label attributes are @@ -4602,6 +4643,8 @@ ambiguous, as it is permissible for a declaration, which could begin with an attribute list, to be labelled in C++. Declarations cannot be labelled in C90 or C99, so the ambiguity does not arise there. +@subsubheading Type Attributes + An attribute specifier list may appear as part of a @code{struct}, @code{union} or @code{enum} specifier. It may go either immediately after the @code{struct}, @code{union} or @code{enum} keyword, or after @@ -4616,6 +4659,9 @@ defined is not complete until after the attribute specifiers. @c attributes could use sizeof for the structure, but the size could be @c changed later by "packed" attributes. + +@subsubheading All other attributes + Otherwise, an attribute specifier appears as part of a declaration, counting declarations of unnamed parameters and type names, and relates to that declaration (which may be nested in another declaration, for @@ -4856,7 +4902,8 @@ by an attribute specification inside double parentheses. Some attributes are currently defined generically for variables. Other attributes are defined for variables on particular target systems. Other attributes are available for functions -(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}). +(@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for +types (@pxref{Type Attributes}). Other front ends might define more attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). @@ -5512,8 +5559,8 @@ inside double parentheses. Seven attributes are currently defined for types: @code{aligned}, @code{packed}, @code{transparent_union}, @code{unused}, @code{deprecated}, @code{visibility}, and @code{may_alias}. Other attributes are defined for functions -(@pxref{Function Attributes}) and for variables (@pxref{Variable -Attributes}). +(@pxref{Function Attributes}), labels (@pxref{Label +Attributes}) and for variables (@pxref{Variable Attributes}). You may also specify any one of these attributes with @samp{__} preceding and following its keyword. This allows you to use these @@ -6935,7 +6982,9 @@ GotoLabels section in an @code{asm goto} statement contains a comma-separated list of all C labels to which the assembler code may jump. GCC assumes that @code{asm} execution falls through to the next statement (if this is not the case, consider using the @code{__builtin_unreachable} intrinsic after the -@code{asm} statement). The total number of input + output + goto operands has +@code{asm} statement). Optimization of @code{asm goto} may be improved by +using the @code{hot} and @code{cold} label attributes (@pxref{Label +Attributes}). The total number of input + output + goto operands has a limit of 30. An @code{asm goto} statement can not have outputs (which means that the -- 2.7.4