Skip to content

R
riscv-gcc-1
Commit 90eb63a3 by Sandra Loosemore Committed by Sandra Loosemore
Options

extend.texi (Variable Attributes): Add menu and proper @nodes to subsections. 

2015-05-01  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/extend.texi (Variable Attributes): Add menu and proper
	@nodes to subsections.  Move Microsoft Windows attributes to
	their own subsection.
	(Type Attributes): Reorganize introduction to remove duplicate
	list of attributes.  Add menu and proper @nodes to subsections.
	Alphabetize the main table of common attributes.

From-SVN: r222714
parent 9c0717ed
Showing with 248 additions and 191 deletions
gcc/ChangeLog
2015-05-01 Sandra Loosemore <sandra@codesourcery.com>
* doc/extend.texi (Variable Attributes): Add menu and proper
@nodes to subsections. Move Microsoft Windows attributes to
their own subsection.
(Type Attributes): Reorganize introduction to remove duplicate
list of attributes. Add menu and proper @nodes to subsections.
Alphabetize the main table of common attributes.
2015-05-01 Rasmus Villemoes <rv@rasmusvillemoes.dk>
* match.pd: New simplification patterns.
......
gcc/doc/extend.texi
......@@ -5400,6 +5400,26 @@ Other front ends might define more attributes
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
@menu
* Common Variable Attributes::
* AVR Variable Attributes::
* Blackfin Variable Attributes::
* H8/300 Variable Attributes::
* IA-64 Variable Attributes::
* M32R/D Variable Attributes::
* MeP Variable Attributes::
* Microsoft Windows Variable Attributes::
* PowerPC Variable Attributes::
* SPU Variable Attributes::
* x86 Variable Attributes::
* Xstormy16 Variable Attributes::
@end menu
@node Common Variable Attributes
@subsection Common Variable Attributes
The following attributes are supported on most targets.
@table @code
@cindex @code{aligned} variable attribute
@item aligned (@var{alignment})
......@@ -5522,7 +5542,8 @@ argument, which must be a string, is printed in the warning if
present.
The @code{deprecated} attribute can also be used for functions and
types (@pxref{Common Function Attributes}, @pxref{Type Attributes}).
types (@pxref{Common Function Attributes},
@pxref{Common Type Attributes}).
@item mode (@var{mode})
@cindex @code{mode} variable attribute
......@@ -5608,33 +5629,6 @@ attribute is not available on all platforms.
If you need to map the entire contents of a module to a particular
section, consider using the facilities of the linker instead.
@item shared
@cindex @code{shared} variable attribute
On Microsoft Windows, in addition to putting variable definitions in a named
section, the section can also be shared among all running copies of an
executable or DLL@. For example, this small program defines shared data
by putting it in a named section @code{shared} and marking the section
shareable:
@smallexample
int foo __attribute__((section ("shared"), shared)) = 0;
int
main()
@{
/* @r{Read and write foo. All running
copies see the same value.} */
return 0;
@}
@end smallexample
@noindent
You may only use the @code{shared} attribute along with @code{section}
attribute with a fully-initialized global definition because of the way
linkers work. See @code{section} attribute for more information.
The @code{shared} attribute is only available on Microsoft Windows@.
@item tls_model ("@var{tls_model}")
@cindex @code{tls_model} variable attribute
The @code{tls_model} attribute sets thread-local storage model
......@@ -5692,45 +5686,14 @@ struct S __attribute__ ((vector_size (16))) foo;
is invalid even if the size of the structure is the same as the size of
the @code{int}.
@item selectany
@cindex @code{selectany} variable attribute
The @code{selectany} attribute causes an initialized global variable to
have link-once semantics. When multiple definitions of the variable are
encountered by the linker, the first is selected and the remainder are
discarded. Following usage by the Microsoft compiler, the linker is told
@emph{not} to warn about size or content differences of the multiple
definitions.
Although the primary usage of this attribute is for POD types, the
attribute can also be applied to global C++ objects that are initialized
by a constructor. In this case, the static initialization and destruction
code for the object is emitted in each translation defining the object,
but the calls to the constructor and destructor are protected by a
link-once guard variable.
The @code{selectany} attribute is only available on Microsoft Windows
targets. You can use @code{__declspec (selectany)} as a synonym for
@code{__attribute__ ((selectany))} for compatibility with other
compilers.
@item weak
@cindex @code{weak} variable attribute
The @code{weak} attribute is described in
@ref{Common Function Attributes}.
@item dllimport
@cindex @code{dllimport} variable attribute
The @code{dllimport} attribute is described in
@ref{Microsoft Windows Function Attributes}.
@item dllexport
@cindex @code{dllexport} variable attribute
The @code{dllexport} attribute is described in
@ref{Microsoft Windows Function Attributes}.
@end table
@anchor{AVR Variable Attributes}
@node AVR Variable Attributes
@subsection AVR Variable Attributes
@table @code
......@@ -5813,6 +5776,7 @@ volatile int porta __attribute__((address (0x600)));
@end table
@node Blackfin Variable Attributes
@subsection Blackfin Variable Attributes
Three attributes are currently defined for the Blackfin.
......@@ -5837,6 +5801,7 @@ Variables with @code{l2} attribute are put into the specific section
named @code{.l2.data}.
@end table
@node H8/300 Variable Attributes
@subsection H8/300 Variable Attributes
These variable attributes are available for H8/300 targets:
......@@ -5865,6 +5830,7 @@ slightly under 32KB of data.
@end table
@node IA-64 Variable Attributes
@subsection IA-64 Variable Attributes
The IA-64 back end supports the following variable attribute:
......@@ -5883,6 +5849,7 @@ defined by shared libraries.
@end table
@node M32R/D Variable Attributes
@subsection M32R/D Variable Attributes
One attribute is currently defined for the M32R/D@.
......@@ -5903,7 +5870,7 @@ Medium and large model objects may live anywhere in the 32-bit address space
addresses).
@end table
@anchor{MeP Variable Attributes}
@node MeP Variable Attributes
@subsection MeP Variable Attributes
The MeP target has a number of addressing modes and busses. The
......@@ -5967,6 +5934,72 @@ int cpu_clock __attribute__((cb(0x123)));
@end table
@node Microsoft Windows Variable Attributes
@subsection Microsoft Windows Variable Attributes
You can use these attributes on Microsoft Windows targets.
@ref{x86 Variable Attributes} for additional Windows compatibility
attributes available on all x86 targets.
@table @code
@item dllimport
@itemx dllexport
@cindex @code{dllimport} variable attribute
@cindex @code{dllexport} variable attribute
The @code{dllimport} and @code{dllexport} attributes are described in
@ref{Microsoft Windows Function Attributes}.
@item selectany
@cindex @code{selectany} variable attribute
The @code{selectany} attribute causes an initialized global variable to
have link-once semantics. When multiple definitions of the variable are
encountered by the linker, the first is selected and the remainder are
discarded. Following usage by the Microsoft compiler, the linker is told
@emph{not} to warn about size or content differences of the multiple
definitions.
Although the primary usage of this attribute is for POD types, the
attribute can also be applied to global C++ objects that are initialized
by a constructor. In this case, the static initialization and destruction
code for the object is emitted in each translation defining the object,
but the calls to the constructor and destructor are protected by a
link-once guard variable.
The @code{selectany} attribute is only available on Microsoft Windows
targets. You can use @code{__declspec (selectany)} as a synonym for
@code{__attribute__ ((selectany))} for compatibility with other
compilers.
@item shared
@cindex @code{shared} variable attribute
On Microsoft Windows, in addition to putting variable definitions in a named
section, the section can also be shared among all running copies of an
executable or DLL@. For example, this small program defines shared data
by putting it in a named section @code{shared} and marking the section
shareable:
@smallexample
int foo __attribute__((section ("shared"), shared)) = 0;
int
main()
@{
/* @r{Read and write foo. All running
copies see the same value.} */
return 0;
@}
@end smallexample
@noindent
You may only use the @code{shared} attribute along with @code{section}
attribute with a fully-initialized global definition because of the way
linkers work. See @code{section} attribute for more information.
The @code{shared} attribute is only available on Microsoft Windows@.
@end table
@node PowerPC Variable Attributes
@subsection PowerPC Variable Attributes
Three attributes currently are defined for PowerPC configurations:
......@@ -5981,6 +6014,7 @@ documentation in @ref{x86 Variable Attributes}.
For documentation of @code{altivec} attribute please see the
documentation in @ref{PowerPC Type Attributes}.
@node SPU Variable Attributes
@subsection SPU Variable Attributes
@cindex @code{spu_vector} variable attribute, SPU
......@@ -5988,7 +6022,7 @@ The SPU supports the @code{spu_vector} attribute for variables. For
documentation of this attribute please see the documentation in
@ref{SPU Type Attributes}.
@anchor{x86 Variable Attributes}
@node x86 Variable Attributes
@subsection x86 Variable Attributes
Two attributes are currently defined for x86 configurations:
......@@ -6126,6 +6160,7 @@ Here, @code{t5} takes up 2 bytes.
@end enumerate
@end table
@node Xstormy16 Variable Attributes
@subsection Xstormy16 Variable Attributes
One attribute is currently defined for xstormy16 configurations:
......@@ -6149,27 +6184,39 @@ placed in either the @code{.bss_below100} section or the
@cindex type attributes
The keyword @code{__attribute__} allows you to specify special
attributes of @code{struct} and @code{union} types when you define
such types. This keyword is followed by an attribute specification
inside double parentheses. Eight attributes are currently defined for
types: @code{aligned}, @code{packed}, @code{transparent_union},
@code{unused}, @code{deprecated}, @code{visibility}, @code{may_alias}
and @code{bnd_variable_size}. Other attributes are defined for
attributes of types. Some type attributes apply only to @code{struct}
and @code{union} types, while others can apply to any type defined
via a @code{typedef} declaration. Other attributes are defined for
functions (@pxref{Function Attributes}), labels (@pxref{Label
Attributes}) and for variables (@pxref{Variable Attributes}).
You may specify type attributes in an enum, struct or union type
declaration or definition, or for other types in a @code{typedef}
declaration.
The @code{__attribute__} keyword is followed by an attribute specification
inside double parentheses.
For an enum, struct or union type, you may specify attributes either
between the enum, struct or union tag and the name of the type, or
just past the closing curly brace of the @emph{definition}. The
former syntax is preferred.
You may specify type attributes in an enum, struct or union type
declaration or definition by placing them immediately after the
@code{struct}, @code{union} or @code{enum} keyword. A less preferred
syntax is to place them just past the closing curly brace of the
definition.
You can also include type attributes in a @code{typedef} declaration.
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
@menu
* Common Type Attributes::
* ARM Type Attributes::
* MeP Type Attributes::
* PowerPC Type Attributes::
* SPU Type Attributes::
* x86 Type Attributes::
@end menu
@node Common Type Attributes
@subsection Common Type Attributes
The following type attributes are supported on most targets.
@table @code
@cindex @code{aligned} type attribute
@item aligned (@var{alignment})
......@@ -6250,14 +6297,6 @@ up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
in an @code{__attribute__} still only provides you with 8-byte
alignment. See your linker documentation for further information.
@item packed
@cindex @code{packed} type attribute
This attribute, attached to @code{struct} or @code{union} type
definition, specifies that each member (other than zero-width bit-fields)
of the structure or union is placed to minimize the memory required. When
attached to an @code{enum} definition, it indicates that the smallest
integral type should be used.
@opindex fshort-enums
Specifying this attribute for @code{struct} and @code{union} types is
equivalent to specifying the @code{packed} attribute on each of the
......@@ -6289,78 +6328,38 @@ You may only specify this attribute on the definition of an @code{enum},
@code{struct} or @code{union}, not on a @code{typedef} that does not
also define the enumerated type, structure or union.
@item transparent_union
@cindex @code{transparent_union} type attribute
This attribute, attached to a @code{union} type definition, indicates
that any function parameter having that union type causes calls to that
function to be treated in a special way.
First, the argument corresponding to a transparent union type can be of
any type in the union; no cast is required. Also, if the union contains
a pointer type, the corresponding argument can be a null pointer
constant or a void pointer expression; and if the union contains a void
pointer type, the corresponding argument can be any pointer expression.
If the union member type is a pointer, qualifiers like @code{const} on
the referenced type must be respected, just as with normal pointer
conversions.
Second, the argument is passed to the function using the calling
conventions of the first member of the transparent union, not the calling
conventions of the union itself. All members of the union must have the
same machine representation; this is necessary for this argument passing
to work properly.
Transparent unions are designed for library functions that have multiple
interfaces for compatibility reasons. For example, suppose the
@code{wait} function must accept either a value of type @code{int *} to
comply with POSIX, or a value of type @code{union wait *} to comply with
the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
@code{wait} would accept both kinds of arguments, but it would also
accept any other pointer type and this would make argument type checking
less useful. Instead, @code{<sys/wait.h>} might define the interface
as follows:
@smallexample
typedef union __attribute__ ((__transparent_union__))
@{
int *__ip;
union wait *__up;
@} wait_status_ptr_t;
pid_t wait (wait_status_ptr_t);
@end smallexample
@noindent
This interface allows either @code{int *} or @code{union wait *}
arguments to be passed, using the @code{int *} calling convention.
The program can call @code{wait} with arguments of either type:
@item bnd_variable_size
@cindex @code{bnd_variable_size} type attribute
@cindex Pointer Bounds Checker attributes
When applied to a structure field, this attribute tells Pointer
Bounds Checker that the size of this field should not be computed
using static type information. It may be used to mark variably-sized
static array fields placed at the end of a structure.
@smallexample
int w1 () @{ int w; return wait (&w); @}
int w2 () @{ union wait w; return wait (&w); @}
struct S
@{
int size;
char data[1];
@}
S *p = (S *)malloc (sizeof(S) + 100);
p->data[10] = 0; //Bounds violation
@end smallexample
@noindent
With this interface, @code{wait}'s implementation might look like this:
By using an attribute for the field we may avoid unwanted bound
violation checks:
@smallexample
pid_t wait (wait_status_ptr_t p)
struct S
@{
return waitpid (-1, p.__ip, 0);
int size;
char data[1] __attribute__((bnd_variable_size));
@}
S *p = (S *)malloc (sizeof(S) + 100);
p->data[10] = 0; //OK
@end smallexample
@item unused
@cindex @code{unused} type attribute
When attached to a type (including a @code{union} or a @code{struct}),
this attribute means that variables of that type are meant to appear
possibly unused. GCC does not produce a warning for any variables of
that type, even if the variable appears to do nothing. This is often
the case with lock or thread classes, which are usually defined and then
not referenced, but contain constructors and destructors that have
nontrivial bookkeeping functions.
@item deprecated
@itemx deprecated (@var{msg})
@cindex @code{deprecated} type attribute
......@@ -6394,6 +6393,18 @@ present.
The @code{deprecated} attribute can also be used for functions and
variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
@item designated_init
@cindex @code{designated_init} type attribute
This attribute may only be applied to structure types. It indicates
that any initialization of an object of this type must use designated
initializers rather than positional initializers. The intent of this
attribute is to allow the programmer to indicate that a structure's
layout may change, and that therefore relying on positional
initialization will result in future breakage.
GCC emits warnings based on this attribute by default; use
@option{-Wno-designated-init} to suppress them.
@item may_alias
@cindex @code{may_alias} type attribute
Accesses through pointers to types with this attribute are not subject
......@@ -6435,70 +6446,107 @@ declaration, the above program would abort when compiled with
@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
above.
@item visibility
@cindex @code{visibility} type attribute
In C++, attribute visibility (@pxref{Function Attributes}) can also be
applied to class, struct, union and enum types. Unlike other type
attributes, the attribute must appear between the initial keyword and
the name of the type; it cannot appear after the body of the type.
@item packed
@cindex @code{packed} type attribute
This attribute, attached to @code{struct} or @code{union} type
definition, specifies that each member (other than zero-width bit-fields)
of the structure or union is placed to minimize the memory required. When
attached to an @code{enum} definition, it indicates that the smallest
integral type should be used.
Note that the type visibility is applied to vague linkage entities
associated with the class (vtable, typeinfo node, etc.). In
particular, if a class is thrown as an exception in one shared object
and caught in another, the class must have default visibility.
Otherwise the two shared objects are unable to use the same
typeinfo node and exception handling will break.
@item transparent_union
@cindex @code{transparent_union} type attribute
@item designated_init
@cindex @code{designated_init} type attribute
This attribute may only be applied to structure types. It indicates
that any initialization of an object of this type must use designated
initializers rather than positional initializers. The intent of this
attribute is to allow the programmer to indicate that a structure's
layout may change, and that therefore relying on positional
initialization will result in future breakage.
This attribute, attached to a @code{union} type definition, indicates
that any function parameter having that union type causes calls to that
function to be treated in a special way.
GCC emits warnings based on this attribute by default; use
@option{-Wno-designated-init} to suppress them.
First, the argument corresponding to a transparent union type can be of
any type in the union; no cast is required. Also, if the union contains
a pointer type, the corresponding argument can be a null pointer
constant or a void pointer expression; and if the union contains a void
pointer type, the corresponding argument can be any pointer expression.
If the union member type is a pointer, qualifiers like @code{const} on
the referenced type must be respected, just as with normal pointer
conversions.
@item bnd_variable_size
@cindex @code{bnd_variable_size} type attribute
@cindex Pointer Bounds Checker attributes
When applied to a structure field, this attribute tells Pointer
Bounds Checker that the size of this field should not be computed
using static type information. It may be used to mark variably-sized
static array fields placed at the end of a structure.
Second, the argument is passed to the function using the calling
conventions of the first member of the transparent union, not the calling
conventions of the union itself. All members of the union must have the
same machine representation; this is necessary for this argument passing
to work properly.
Transparent unions are designed for library functions that have multiple
interfaces for compatibility reasons. For example, suppose the
@code{wait} function must accept either a value of type @code{int *} to
comply with POSIX, or a value of type @code{union wait *} to comply with
the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
@code{wait} would accept both kinds of arguments, but it would also
accept any other pointer type and this would make argument type checking
less useful. Instead, @code{<sys/wait.h>} might define the interface
as follows:
@smallexample
struct S
@{
int size;
char data[1];
@}
S *p = (S *)malloc (sizeof(S) + 100);
p->data[10] = 0; //Bounds violation
typedef union __attribute__ ((__transparent_union__))
@{
int *__ip;
union wait *__up;
@} wait_status_ptr_t;
pid_t wait (wait_status_ptr_t);
@end smallexample
@noindent
By using an attribute for the field we may avoid unwanted bound
violation checks:
This interface allows either @code{int *} or @code{union wait *}
arguments to be passed, using the @code{int *} calling convention.
The program can call @code{wait} with arguments of either type:
@smallexample
struct S
int w1 () @{ int w; return wait (&w); @}
int w2 () @{ union wait w; return wait (&w); @}
@end smallexample
@noindent
With this interface, @code{wait}'s implementation might look like this:
@smallexample
pid_t wait (wait_status_ptr_t p)
@{
int size;
char data[1] __attribute__((bnd_variable_size));
return waitpid (-1, p.__ip, 0);
@}
S *p = (S *)malloc (sizeof(S) + 100);
p->data[10] = 0; //OK
@end smallexample
@item unused
@cindex @code{unused} type attribute
When attached to a type (including a @code{union} or a @code{struct}),
this attribute means that variables of that type are meant to appear
possibly unused. GCC does not produce a warning for any variables of
that type, even if the variable appears to do nothing. This is often
the case with lock or thread classes, which are usually defined and then
not referenced, but contain constructors and destructors that have
nontrivial bookkeeping functions.
@item visibility
@cindex @code{visibility} type attribute
In C++, attribute visibility (@pxref{Function Attributes}) can also be
applied to class, struct, union and enum types. Unlike other type
attributes, the attribute must appear between the initial keyword and
the name of the type; it cannot appear after the body of the type.
Note that the type visibility is applied to vague linkage entities
associated with the class (vtable, typeinfo node, etc.). In
particular, if a class is thrown as an exception in one shared object
and caught in another, the class must have default visibility.
Otherwise the two shared objects are unable to use the same
typeinfo node and exception handling will break.
@end table
To specify multiple attributes, separate them by commas within the
double parentheses: for example, @samp{__attribute__ ((aligned (16),
packed))}.
@node ARM Type Attributes
@subsection ARM Type Attributes
@cindex @code{notshared} type attribute, ARM
......@@ -6524,7 +6572,7 @@ virtual table for @code{C} is not exported. (You can use
@code{__attribute__} instead of @code{__declspec} if you prefer, but
most Symbian OS code uses @code{__declspec}.)
@anchor{MeP Type Attributes}
@node MeP Type Attributes
@subsection MeP Type Attributes
@cindex @code{based} type attribute, MeP
......@@ -6536,7 +6584,7 @@ Specifically, the @code{based}, @code{tiny}, @code{near}, and
@code{far} attributes may be applied to either. The @code{io} and
@code{cb} attributes may not be applied to types.
@anchor{PowerPC Type Attributes}
@node PowerPC Type Attributes
@subsection PowerPC Type Attributes
Three attributes currently are defined for PowerPC configurations:
......@@ -6563,7 +6611,7 @@ __attribute__((altivec(bool__))) unsigned
These attributes mainly are intended to support the @code{__vector},
@code{__pixel}, and @code{__bool} AltiVec keywords.
@anchor{SPU Type Attributes}
@node SPU Type Attributes
@subsection SPU Type Attributes
@cindex @code{spu_vector} type attribute, SPU
......@@ -6572,7 +6620,7 @@ allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
Language Extensions Specification. It is intended to support the
@code{__vector} keyword.
@anchor{x86 Type Attributes}
@node x86 Type Attributes
@subsection x86 Type Attributes
Two attributes are currently defined for x86 configurations:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment