You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
744 lines
40 KiB
HTML
744 lines
40 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Variable Attributes - Using the GNU Compiler Collection (GCC)</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC)">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions">
|
|
<link rel="prev" href="Character-Escapes.html#Character-Escapes" title="Character Escapes">
|
|
<link rel="next" href="Type-Attributes.html#Type-Attributes" title="Type Attributes">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2015 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``Funding Free Software'', the Front-Cover
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
|
(see below). A copy of the license is included in the section entitled
|
|
``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Variable-Attributes"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="Type-Attributes.html#Type-Attributes">Type Attributes</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Character-Escapes.html#Character-Escapes">Character Escapes</a>,
|
|
Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">6.38 Specifying Attributes of Variables</h3>
|
|
|
|
<p><a name="index-attribute-of-variables-3322"></a><a name="index-variable-attributes-3323"></a>
|
|
The keyword <code>__attribute__</code> allows you to specify special
|
|
attributes of variables or structure fields. This keyword is followed
|
|
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
|
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>), labels (see <a href="Label-Attributes.html#Label-Attributes">Label Attributes</a>) and for
|
|
types (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>).
|
|
Other front ends might define more attributes
|
|
(see <a href="C_002b_002b-Extensions.html#C_002b_002b-Extensions">Extensions to the C++ Language</a>).
|
|
|
|
<p>You may also specify attributes with ‘<samp><span class="samp">__</span></samp>’ preceding and following
|
|
each keyword. This allows you to use them in header files without
|
|
being concerned about a possible macro of the same name. For example,
|
|
you may use <code>__aligned__</code> instead of <code>aligned</code>.
|
|
|
|
<p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using
|
|
attributes.
|
|
|
|
|
|
<a name="index-g_t_0040code_007baligned_007d-variable-attribute-3324"></a>
|
|
<dl><dt><code>aligned (</code><var>alignment</var><code>)</code><dd>This attribute specifies a minimum alignment for the variable or
|
|
structure field, measured in bytes. For example, the declaration:
|
|
|
|
<pre class="smallexample"> int x __attribute__ ((aligned (16))) = 0;
|
|
</pre>
|
|
<p class="noindent">causes the compiler to allocate the global variable <code>x</code> on a
|
|
16-byte boundary. On a 68040, this could be used in conjunction with
|
|
an <code>asm</code> expression to access the <code>move16</code> instruction which
|
|
requires 16-byte aligned operands.
|
|
|
|
<p>You can also specify the alignment of structure fields. For example, to
|
|
create a double-word aligned <code>int</code> pair, you could write:
|
|
|
|
<pre class="smallexample"> struct foo { int x[2] __attribute__ ((aligned (8))); };
|
|
</pre>
|
|
<p class="noindent">This is an alternative to creating a union with a <code>double</code> member,
|
|
which forces the union to be double-word aligned.
|
|
|
|
<p>As in the preceding examples, you can explicitly specify the alignment
|
|
(in bytes) that you wish the compiler to use for a given variable or
|
|
structure field. Alternatively, you can leave out the alignment factor
|
|
and just ask the compiler to align a variable or field to the
|
|
default alignment for the target architecture you are compiling for.
|
|
The default alignment is sufficient for all scalar types, but may not be
|
|
enough for all vector types on a target that supports vector operations.
|
|
The default alignment is fixed for a particular target ABI.
|
|
|
|
<p>GCC also provides a target specific macro <code>__BIGGEST_ALIGNMENT__</code>,
|
|
which is the largest alignment ever used for any data type on the
|
|
target machine you are compiling for. For example, you could write:
|
|
|
|
<pre class="smallexample"> short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
|
|
</pre>
|
|
<p>The compiler automatically sets the alignment for the declared
|
|
variable or field to <code>__BIGGEST_ALIGNMENT__</code>. Doing this can
|
|
often make copy operations more efficient, because the compiler can
|
|
use whatever instructions copy the biggest chunks of memory when
|
|
performing copies to or from the variables or fields that you have
|
|
aligned this way. Note that the value of <code>__BIGGEST_ALIGNMENT__</code>
|
|
may change depending on command-line options.
|
|
|
|
<p>When used on a struct, or struct member, the <code>aligned</code> attribute can
|
|
only increase the alignment; in order to decrease it, the <code>packed</code>
|
|
attribute must be specified as well. When used as part of a typedef, the
|
|
<code>aligned</code> attribute can both increase and decrease alignment, and
|
|
specifying the <code>packed</code> attribute generates a warning.
|
|
|
|
<p>Note that the effectiveness of <code>aligned</code> attributes may be limited
|
|
by inherent limitations in your linker. On many systems, the linker is
|
|
only able to arrange for variables to be aligned up to a certain maximum
|
|
alignment. (For some linkers, the maximum supported alignment may
|
|
be very very small.) If your linker is only able to align variables
|
|
up to a maximum of 8-byte alignment, then specifying <code>aligned(16)</code>
|
|
in an <code>__attribute__</code> still only provides you with 8-byte
|
|
alignment. See your linker documentation for further information.
|
|
|
|
<p>The <code>aligned</code> attribute can also be used for functions
|
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.)
|
|
|
|
<br><dt><code>cleanup (</code><var>cleanup_function</var><code>)</code><dd><a name="index-g_t_0040code_007bcleanup_007d-variable-attribute-3325"></a>The <code>cleanup</code> attribute runs a function when the variable goes
|
|
out of scope. This attribute can only be applied to auto function
|
|
scope variables; it may not be applied to parameters or variables
|
|
with static storage duration. The function must take one parameter,
|
|
a pointer to a type compatible with the variable. The return value
|
|
of the function (if any) is ignored.
|
|
|
|
<p>If <samp><span class="option">-fexceptions</span></samp> is enabled, then <var>cleanup_function</var>
|
|
is run during the stack unwinding that happens during the
|
|
processing of the exception. Note that the <code>cleanup</code> attribute
|
|
does not allow the exception to be caught, only to perform an action.
|
|
It is undefined what happens if <var>cleanup_function</var> does not
|
|
return normally.
|
|
|
|
<br><dt><code>common</code><dt><code>nocommon</code><dd><a name="index-g_t_0040code_007bcommon_007d-variable-attribute-3326"></a><a name="index-g_t_0040code_007bnocommon_007d-variable-attribute-3327"></a><a name="index-fcommon-3328"></a><a name="index-fno_002dcommon-3329"></a>The <code>common</code> attribute requests GCC to place a variable in
|
|
“common” storage. The <code>nocommon</code> attribute requests the
|
|
opposite—to allocate space for it directly.
|
|
|
|
<p>These attributes override the default chosen by the
|
|
<samp><span class="option">-fno-common</span></samp> and <samp><span class="option">-fcommon</span></samp> flags respectively.
|
|
|
|
<br><dt><code>deprecated</code><dt><code>deprecated (</code><var>msg</var><code>)</code><dd><a name="index-g_t_0040code_007bdeprecated_007d-variable-attribute-3330"></a>The <code>deprecated</code> attribute results in a warning if the variable
|
|
is used anywhere in the source file. This is useful when identifying
|
|
variables that are expected to be removed in a future version of a
|
|
program. The warning also includes the location of the declaration
|
|
of the deprecated variable, to enable users to easily find further
|
|
information about why the variable is deprecated, or what they should
|
|
do instead. Note that the warning only occurs for uses:
|
|
|
|
<pre class="smallexample"> extern int old_var __attribute__ ((deprecated));
|
|
extern int old_var;
|
|
int new_fn () { return old_var; }
|
|
</pre>
|
|
<p class="noindent">results in a warning on line 3 but not line 2. The optional <var>msg</var>
|
|
argument, which must be a string, is printed in the warning if
|
|
present.
|
|
|
|
<p>The <code>deprecated</code> attribute can also be used for functions and
|
|
types (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.)
|
|
|
|
<br><dt><code>mode (</code><var>mode</var><code>)</code><dd><a name="index-g_t_0040code_007bmode_007d-variable-attribute-3331"></a>This attribute specifies the data type for the declaration—whichever
|
|
type corresponds to the mode <var>mode</var>. This in effect lets you
|
|
request an integer or floating-point type according to its width.
|
|
|
|
<p>You may also specify a mode of <code>byte</code> or <code>__byte__</code> to
|
|
indicate the mode corresponding to a one-byte integer, <code>word</code> or
|
|
<code>__word__</code> for the mode of a one-word integer, and <code>pointer</code>
|
|
or <code>__pointer__</code> for the mode used to represent pointers.
|
|
|
|
<br><dt><code>packed</code><dd><a name="index-g_t_0040code_007bpacked_007d-variable-attribute-3332"></a>The <code>packed</code> attribute specifies that a variable or structure field
|
|
should have the smallest possible alignment—one byte for a variable,
|
|
and one bit for a field, unless you specify a larger value with the
|
|
<code>aligned</code> attribute.
|
|
|
|
<p>Here is a structure in which the field <code>x</code> is packed, so that it
|
|
immediately follows <code>a</code>:
|
|
|
|
<pre class="smallexample"> struct foo
|
|
{
|
|
char a;
|
|
int x[2] __attribute__ ((packed));
|
|
};
|
|
</pre>
|
|
<p><em>Note:</em> The 4.1, 4.2 and 4.3 series of GCC ignore the
|
|
<code>packed</code> attribute on bit-fields of type <code>char</code>. This has
|
|
been fixed in GCC 4.4 but the change can lead to differences in the
|
|
structure layout. See the documentation of
|
|
<samp><span class="option">-Wpacked-bitfield-compat</span></samp> for more information.
|
|
|
|
<br><dt><code>section ("</code><var>section-name</var><code>")</code><dd><a name="index-g_t_0040code_007bsection_007d-variable-attribute-3333"></a>Normally, the compiler places the objects it generates in sections like
|
|
<code>data</code> and <code>bss</code>. Sometimes, however, you need additional sections,
|
|
or you need certain particular variables to appear in special sections,
|
|
for example to map to special hardware. The <code>section</code>
|
|
attribute specifies that a variable (or function) lives in a particular
|
|
section. For example, this small program uses several specific section names:
|
|
|
|
<pre class="smallexample"> struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
|
|
struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
|
|
char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
|
|
int init_data __attribute__ ((section ("INITDATA")));
|
|
|
|
main()
|
|
{
|
|
/* <span class="roman">Initialize stack pointer</span> */
|
|
init_sp (stack + sizeof (stack));
|
|
|
|
/* <span class="roman">Initialize initialized data</span> */
|
|
memcpy (&init_data, &data, &edata - &data);
|
|
|
|
/* <span class="roman">Turn on the serial ports</span> */
|
|
init_duart (&a);
|
|
init_duart (&b);
|
|
}
|
|
</pre>
|
|
<p class="noindent">Use the <code>section</code> attribute with
|
|
<em>global</em> variables and not <em>local</em> variables,
|
|
as shown in the example.
|
|
|
|
<p>You may use the <code>section</code> attribute with initialized or
|
|
uninitialized global variables but the linker requires
|
|
each object be defined once, with the exception that uninitialized
|
|
variables tentatively go in the <code>common</code> (or <code>bss</code>) section
|
|
and can be multiply “defined”. Using the <code>section</code> attribute
|
|
changes what section the variable goes into and may cause the
|
|
linker to issue an error if an uninitialized variable has multiple
|
|
definitions. You can force a variable to be initialized with the
|
|
<samp><span class="option">-fno-common</span></samp> flag or the <code>nocommon</code> attribute.
|
|
|
|
<p>Some file formats do not support arbitrary sections so the <code>section</code>
|
|
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.
|
|
|
|
<br><dt><code>shared</code><dd><a name="index-g_t_0040code_007bshared_007d-variable-attribute-3334"></a>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</code> and marking the section
|
|
shareable:
|
|
|
|
<pre class="smallexample"> int foo __attribute__((section ("shared"), shared)) = 0;
|
|
|
|
int
|
|
main()
|
|
{
|
|
/* <span class="roman">Read and write foo. All running
|
|
copies see the same value.</span> */
|
|
return 0;
|
|
}
|
|
</pre>
|
|
<p class="noindent">You may only use the <code>shared</code> attribute along with <code>section</code>
|
|
attribute with a fully-initialized global definition because of the way
|
|
linkers work. See <code>section</code> attribute for more information.
|
|
|
|
<p>The <code>shared</code> attribute is only available on Microsoft Windows.
|
|
|
|
<br><dt><code>tls_model ("</code><var>tls_model</var><code>")</code><dd><a name="index-g_t_0040code_007btls_005fmodel_007d-variable-attribute-3335"></a>The <code>tls_model</code> attribute sets thread-local storage model
|
|
(see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>) of a particular <code>__thread</code> variable,
|
|
overriding <samp><span class="option">-ftls-model=</span></samp> command-line switch on a per-variable
|
|
basis.
|
|
The <var>tls_model</var> argument should be one of <code>global-dynamic</code>,
|
|
<code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>.
|
|
|
|
<p>Not all targets support this attribute.
|
|
|
|
<br><dt><code>unused</code><dd><a name="index-g_t_0040code_007bunused_007d-variable-attribute-3336"></a>This attribute, attached to a variable, means that the variable is meant
|
|
to be possibly unused. GCC does not produce a warning for this
|
|
variable.
|
|
|
|
<br><dt><code>used</code><dd><a name="index-g_t_0040code_007bused_007d-variable-attribute-3337"></a>This attribute, attached to a variable with static storage, means that
|
|
the variable must be emitted even if it appears that the variable is not
|
|
referenced.
|
|
|
|
<p>When applied to a static data member of a C++ class template, the
|
|
attribute also means that the member is instantiated if the
|
|
class itself is instantiated.
|
|
|
|
<br><dt><code>vector_size (</code><var>bytes</var><code>)</code><dd><a name="index-g_t_0040code_007bvector_005fsize_007d-variable-attribute-3338"></a>This attribute specifies the vector size for the variable, measured in
|
|
bytes. For example, the declaration:
|
|
|
|
<pre class="smallexample"> int foo __attribute__ ((vector_size (16)));
|
|
</pre>
|
|
<p class="noindent">causes the compiler to set the mode for <code>foo</code>, to be 16 bytes,
|
|
divided into <code>int</code> sized units. Assuming a 32-bit int (a vector of
|
|
4 units of 4 bytes), the corresponding mode of <code>foo</code> is V4SI.
|
|
|
|
<p>This attribute is only applicable to integral and float scalars,
|
|
although arrays, pointers, and function return values are allowed in
|
|
conjunction with this construct.
|
|
|
|
<p>Aggregates with this attribute are invalid, even if they are of the same
|
|
size as a corresponding scalar. For example, the declaration:
|
|
|
|
<pre class="smallexample"> struct S { int a; };
|
|
struct S __attribute__ ((vector_size (16))) foo;
|
|
</pre>
|
|
<p class="noindent">is invalid even if the size of the structure is the same as the size of
|
|
the <code>int</code>.
|
|
|
|
<br><dt><code>selectany</code><dd><a name="index-g_t_0040code_007bselectany_007d-variable-attribute-3339"></a>The <code>selectany</code> 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
|
|
<em>not</em> to warn about size or content differences of the multiple
|
|
definitions.
|
|
|
|
<p>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.
|
|
|
|
<p>The <code>selectany</code> attribute is only available on Microsoft Windows
|
|
targets. You can use <code>__declspec (selectany)</code> as a synonym for
|
|
<code>__attribute__ ((selectany))</code> for compatibility with other
|
|
compilers.
|
|
|
|
<br><dt><code>weak</code><dd><a name="index-g_t_0040code_007bweak_007d-variable-attribute-3340"></a>The <code>weak</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
|
|
|
|
<br><dt><code>dllimport</code><dd><a name="index-g_t_0040code_007bdllimport_007d-variable-attribute-3341"></a>The <code>dllimport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
|
|
|
|
<br><dt><code>dllexport</code><dd><a name="index-g_t_0040code_007bdllexport_007d-variable-attribute-3342"></a>The <code>dllexport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
|
|
|
|
</dl>
|
|
|
|
<p><a name="AVR-Variable-Attributes"></a>
|
|
|
|
<h4 class="subsection">6.38.1 AVR Variable Attributes</h4>
|
|
|
|
<dl>
|
|
<dt><code>progmem</code><dd><a name="index-g_t_0040code_007bprogmem_007d-variable-attribute_002c-AVR-3343"></a>The <code>progmem</code> attribute is used on the AVR to place read-only
|
|
data in the non-volatile program memory (flash). The <code>progmem</code>
|
|
attribute accomplishes this by putting respective variables into a
|
|
section whose name starts with <code>.progmem</code>.
|
|
|
|
<p>This attribute works similar to the <code>section</code> attribute
|
|
but adds additional checking.
|
|
|
|
<dl>
|
|
<dt>• Ordinary AVR cores with 32 general purpose registers:<dd><code>progmem</code> affects the location
|
|
of the data but not how this data is accessed.
|
|
In order to read data located with the <code>progmem</code> attribute
|
|
(inline) assembler must be used.
|
|
<pre class="smallexample"> /* Use custom macros from <a href="http://nongnu.org/avr-libc/user-manual/">AVR-LibC</a><!-- /@w --> */
|
|
#include <avr/pgmspace.h>
|
|
|
|
/* Locate var in flash memory */
|
|
const int var[2] PROGMEM = { 1, 2 };
|
|
|
|
int read_var (int i)
|
|
{
|
|
/* Access var[] by accessor macro from avr/pgmspace.h */
|
|
return (int) pgm_read_word (& var[i]);
|
|
}
|
|
</pre>
|
|
<p>AVR is a Harvard architecture processor and data and read-only data
|
|
normally resides in the data memory (RAM).
|
|
|
|
<p>See also the <a href="AVR-Named-Address-Spaces.html#AVR-Named-Address-Spaces">AVR Named Address Spaces</a> section for
|
|
an alternate way to locate and access data in flash memory.
|
|
|
|
<br><dt>• AVR cores with flash memory visible in the RAM address range:<dd>On such devices, there is no need for attribute <code>progmem</code> or
|
|
<a href="AVR-Named-Address-Spaces.html#AVR-Named-Address-Spaces"><code>__flash</code></a> qualifier at all.
|
|
Just use standard C / C++. The compiler will generate <code>LD*</code>
|
|
instructions. As flash memory is visible in the RAM address range,
|
|
and the default linker script does <em>not</em> locate <code>.rodata</code> in
|
|
RAM, no special features are needed in order not to waste RAM for
|
|
read-only data or to read from flash. You might even get slightly better
|
|
performance by
|
|
avoiding <code>progmem</code> and <code>__flash</code>. This applies to devices from
|
|
families <code>avrtiny</code> and <code>avrxmega3</code>, see <a href="AVR-Options.html#AVR-Options">AVR Options</a> for
|
|
an overview.
|
|
|
|
<br><dt>• Reduced AVR Tiny cores like ATtiny40:<dd>The compiler adds <code>0x4000</code>
|
|
to the addresses of objects and declarations in <code>progmem</code> and locates
|
|
the objects in flash memory, namely in section <code>.progmem.data</code>.
|
|
The offset is needed because the flash memory is visible in the RAM
|
|
address space starting at address <code>0x4000</code>.
|
|
|
|
<p>Data in <code>progmem</code> can be accessed by means of ordinary C code,
|
|
no special functions or macros are needed.
|
|
|
|
<pre class="smallexample"> /* var is located in flash memory */
|
|
extern const int var[2] __attribute__((progmem));
|
|
|
|
int read_var (int i)
|
|
{
|
|
return var[i];
|
|
}
|
|
</pre>
|
|
<p>Please notice that on these devices, there is no need for <code>progmem</code>
|
|
at all.
|
|
|
|
</dl>
|
|
|
|
<br><dt><code>io</code><dt><code>io (</code><var>addr</var><code>)</code><dd><a name="index-g_t_0040code_007bio_007d-variable-attribute_002c-AVR-3344"></a>Variables with the <code>io</code> attribute are used to address
|
|
memory-mapped peripherals in the io address range.
|
|
If an address is specified, the variable
|
|
is assigned that address, and the value is interpreted as an
|
|
address in the data address space.
|
|
Example:
|
|
|
|
<br><dt><code>io</code><dt><code>io (</code><var>addr</var><code>)</code><dd><a name="index-g_t_0040code_007bio_007d-variable-attribute_002c-AVR-3345"></a>Variables with the <code>io</code> attribute are used to address
|
|
memory-mapped peripherals in the io address range.
|
|
If an address is specified, the variable
|
|
is assigned that address, and the value is interpreted as an
|
|
address in the data address space.
|
|
Example:
|
|
|
|
<pre class="smallexample"> volatile int porta __attribute__((io (0x22)));
|
|
</pre>
|
|
<p>The address specified in the address in the data address range.
|
|
|
|
<p>Otherwise, the variable it is not assigned an address, but the
|
|
compiler will still use in/out instructions where applicable,
|
|
assuming some other module assigns an address in the io address range.
|
|
Example:
|
|
|
|
<pre class="smallexample"> extern volatile int porta __attribute__((io));
|
|
</pre>
|
|
<br><dt><code>io_low</code><dt><code>io_low (</code><var>addr</var><code>)</code><dd><a name="index-g_t_0040code_007bio_005flow_007d-variable-attribute_002c-AVR-3346"></a>This is like the <code>io</code> attribute, but additionally it informs the
|
|
compiler that the object lies in the lower half of the I/O area,
|
|
allowing the use of <code>cbi</code>, <code>sbi</code>, <code>sbic</code> and <code>sbis</code>
|
|
instructions.
|
|
|
|
<br><dt><code>address</code><dt><code>address (</code><var>addr</var><code>)</code><dd><a name="index-g_t_0040code_007baddress_007d-variable-attribute_002c-AVR-3347"></a>Variables with the <code>address</code> attribute are used to address
|
|
memory-mapped peripherals that may lie outside the io address range.
|
|
|
|
<pre class="smallexample"> volatile int porta __attribute__((address (0x600)));
|
|
</pre>
|
|
<br><dt><code>absdata</code><dd><a name="index-g_t_0040code_007babsdata_007d-variable-attribute_002c-AVR-3348"></a>Variables in static storage and with the <code>absdata</code> attribute can
|
|
be accessed by the <code>LDS</code> and <code>STS</code> instructions which take
|
|
absolute addresses.
|
|
|
|
<ul>
|
|
<li>This attribute is only supported for the reduced AVR Tiny core
|
|
like ATtiny40.
|
|
|
|
<li>You must make sure that respective data is located in the
|
|
address range <code>0x40</code><small class="dots">...</small><code>0xbf</code> accessible by
|
|
<code>LDS</code> and <code>STS</code>. One way to achieve this as an
|
|
appropriate linker description file.
|
|
|
|
<li>If the location does not fit the address range of <code>LDS</code>
|
|
and <code>STS</code>, there is currently (Binutils 2.26) just an unspecific
|
|
warning like
|
|
<blockquote>
|
|
<code>module.c:(.text+0x1c): warning: internal error: out of range error</code>
|
|
</blockquote>
|
|
|
|
</ul>
|
|
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.2 Blackfin Variable Attributes</h4>
|
|
|
|
<p>Three attributes are currently defined for the Blackfin.
|
|
|
|
<dl>
|
|
<dt><code>l1_data</code><dt><code>l1_data_A</code><dt><code>l1_data_B</code><dd><a name="index-g_t_0040code_007bl1_005fdata_007d-variable-attribute_002c-Blackfin-3349"></a><a name="index-g_t_0040code_007bl1_005fdata_005fA_007d-variable-attribute_002c-Blackfin-3350"></a><a name="index-g_t_0040code_007bl1_005fdata_005fB_007d-variable-attribute_002c-Blackfin-3351"></a>Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
|
|
Variables with <code>l1_data</code> attribute are put into the specific section
|
|
named <code>.l1.data</code>. Those with <code>l1_data_A</code> attribute are put into
|
|
the specific section named <code>.l1.data.A</code>. Those with <code>l1_data_B</code>
|
|
attribute are put into the specific section named <code>.l1.data.B</code>.
|
|
|
|
<br><dt><code>l2</code><dd><a name="index-g_t_0040code_007bl2_007d-variable-attribute_002c-Blackfin-3352"></a>Use this attribute on the Blackfin to place the variable into L2 SRAM.
|
|
Variables with <code>l2</code> attribute are put into the specific section
|
|
named <code>.l2.data</code>.
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.3 H8/300 Variable Attributes</h4>
|
|
|
|
<p>These variable attributes are available for H8/300 targets:
|
|
|
|
<dl>
|
|
<dt><code>eightbit_data</code><dd><a name="index-g_t_0040code_007beightbit_005fdata_007d-variable-attribute_002c-H8_002f300-3353"></a><a name="index-eight_002dbit-data-on-the-H8_002f300_002c-H8_002f300H_002c-and-H8S-3354"></a>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
|
|
variable should be placed into the eight-bit data section.
|
|
The compiler generates more efficient code for certain operations
|
|
on data in the eight-bit data area. Note the eight-bit data area is limited to
|
|
256 bytes of data.
|
|
|
|
<p>You must use GAS and GLD from GNU binutils version 2.7 or later for
|
|
this attribute to work correctly.
|
|
|
|
<br><dt><code>tiny_data</code><dd><a name="index-g_t_0040code_007btiny_005fdata_007d-variable-attribute_002c-H8_002f300-3355"></a><a name="index-tiny-data-section-on-the-H8_002f300H-and-H8S-3356"></a>Use this attribute on the H8/300H and H8S to indicate that the specified
|
|
variable should be placed into the tiny data section.
|
|
The compiler generates more efficient code for loads and stores
|
|
on data in the tiny data section. Note the tiny data area is limited to
|
|
slightly under 32KB of data.
|
|
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.4 IA-64 Variable Attributes</h4>
|
|
|
|
<p>The IA-64 back end supports the following variable attribute:
|
|
|
|
<dl>
|
|
<dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-g_t_0040code_007bmodel_007d-variable-attribute_002c-IA_002d64-3357"></a>
|
|
On IA-64, use this attribute to set the addressability of an object.
|
|
At present, the only supported identifier for <var>model-name</var> is
|
|
<code>small</code>, indicating addressability via “small” (22-bit)
|
|
addresses (so that their addresses can be loaded with the <code>addl</code>
|
|
instruction). Caveat: such addressing is by definition not position
|
|
independent and hence this attribute must not be used for objects
|
|
defined by shared libraries.
|
|
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.5 M32R/D Variable Attributes</h4>
|
|
|
|
<p>One attribute is currently defined for the M32R/D.
|
|
|
|
<dl>
|
|
<dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-g_t_0040code_007bmodel_002dname_007d-variable-attribute_002c-M32R_002fD-3358"></a><a name="index-variable-addressability-on-the-M32R_002fD-3359"></a>Use this attribute on the M32R/D to set the addressability of an object.
|
|
The identifier <var>model-name</var> is one of <code>small</code>, <code>medium</code>,
|
|
or <code>large</code>, representing each of the code models.
|
|
|
|
<p>Small model objects live in the lower 16MB of memory (so that their
|
|
addresses can be loaded with the <code>ld24</code> instruction).
|
|
|
|
<p>Medium and large model objects may live anywhere in the 32-bit address space
|
|
(the compiler generates <code>seth/add3</code> instructions to load their
|
|
addresses).
|
|
</dl>
|
|
|
|
<p><a name="MeP-Variable-Attributes"></a>
|
|
|
|
<h4 class="subsection">6.38.6 MeP Variable Attributes</h4>
|
|
|
|
<p>The MeP target has a number of addressing modes and busses. The
|
|
<code>near</code> space spans the standard memory space's first 16 megabytes
|
|
(24 bits). The <code>far</code> space spans the entire 32-bit memory space.
|
|
The <code>based</code> space is a 128-byte region in the memory space that
|
|
is addressed relative to the <code>$tp</code> register. The <code>tiny</code>
|
|
space is a 65536-byte region relative to the <code>$gp</code> register. In
|
|
addition to these memory regions, the MeP target has a separate 16-bit
|
|
control bus which is specified with <code>cb</code> attributes.
|
|
|
|
<dl>
|
|
<dt><code>based</code><dd><a name="index-g_t_0040code_007bbased_007d-variable-attribute_002c-MeP-3360"></a>Any variable with the <code>based</code> attribute is assigned to the
|
|
<code>.based</code> section, and is accessed with relative to the
|
|
<code>$tp</code> register.
|
|
|
|
<br><dt><code>tiny</code><dd><a name="index-g_t_0040code_007btiny_007d-variable-attribute_002c-MeP-3361"></a>Likewise, the <code>tiny</code> attribute assigned variables to the
|
|
<code>.tiny</code> section, relative to the <code>$gp</code> register.
|
|
|
|
<br><dt><code>near</code><dd><a name="index-g_t_0040code_007bnear_007d-variable-attribute_002c-MeP-3362"></a>Variables with the <code>near</code> attribute are assumed to have addresses
|
|
that fit in a 24-bit addressing mode. This is the default for large
|
|
variables (<code>-mtiny=4</code> is the default) but this attribute can
|
|
override <code>-mtiny=</code> for small variables, or override <code>-ml</code>.
|
|
|
|
<br><dt><code>far</code><dd><a name="index-g_t_0040code_007bfar_007d-variable-attribute_002c-MeP-3363"></a>Variables with the <code>far</code> attribute are addressed using a full
|
|
32-bit address. Since this covers the entire memory space, this
|
|
allows modules to make no assumptions about where variables might be
|
|
stored.
|
|
|
|
<br><dt><code>io</code><dd><a name="index-g_t_0040code_007bio_007d-variable-attribute_002c-MeP-3364"></a><dt><code>io (</code><var>addr</var><code>)</code><dd>Variables with the <code>io</code> attribute are used to address
|
|
memory-mapped peripherals. If an address is specified, the variable
|
|
is assigned that address, else it is not assigned an address (it is
|
|
assumed some other module assigns an address). Example:
|
|
|
|
<pre class="smallexample"> int timer_count __attribute__((io(0x123)));
|
|
</pre>
|
|
<br><dt><code>cb</code><dt><code>cb (</code><var>addr</var><code>)</code><dd><a name="index-g_t_0040code_007bcb_007d-variable-attribute_002c-MeP-3365"></a>Variables with the <code>cb</code> attribute are used to access the control
|
|
bus, using special instructions. <code>addr</code> indicates the control bus
|
|
address. Example:
|
|
|
|
<pre class="smallexample"> int cpu_clock __attribute__((cb(0x123)));
|
|
</pre>
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.7 PowerPC Variable Attributes</h4>
|
|
|
|
<p>Three attributes currently are defined for PowerPC configurations:
|
|
<code>altivec</code>, <code>ms_struct</code> and <code>gcc_struct</code>.
|
|
|
|
<p><a name="index-g_t_0040code_007bms_005fstruct_007d-variable-attribute_002c-PowerPC-3366"></a><a name="index-g_t_0040code_007bgcc_005fstruct_007d-variable-attribute_002c-PowerPC-3367"></a>For full documentation of the struct attributes please see the
|
|
documentation in <a href="x86-Variable-Attributes.html#x86-Variable-Attributes">x86 Variable Attributes</a>.
|
|
|
|
<p><a name="index-g_t_0040code_007baltivec_007d-variable-attribute_002c-PowerPC-3368"></a>For documentation of <code>altivec</code> attribute please see the
|
|
documentation in <a href="PowerPC-Type-Attributes.html#PowerPC-Type-Attributes">PowerPC Type Attributes</a>.
|
|
|
|
<h4 class="subsection">6.38.8 SPU Variable Attributes</h4>
|
|
|
|
<p><a name="index-g_t_0040code_007bspu_005fvector_007d-variable-attribute_002c-SPU-3369"></a>The SPU supports the <code>spu_vector</code> attribute for variables. For
|
|
documentation of this attribute please see the documentation in
|
|
<a href="SPU-Type-Attributes.html#SPU-Type-Attributes">SPU Type Attributes</a>.
|
|
|
|
<p><a name="x86-Variable-Attributes"></a>
|
|
|
|
<h4 class="subsection">6.38.9 x86 Variable Attributes</h4>
|
|
|
|
<p>Two attributes are currently defined for x86 configurations:
|
|
<code>ms_struct</code> and <code>gcc_struct</code>.
|
|
|
|
<dl>
|
|
<dt><code>ms_struct</code><dt><code>gcc_struct</code><dd><a name="index-g_t_0040code_007bms_005fstruct_007d-variable-attribute_002c-x86-3370"></a><a name="index-g_t_0040code_007bgcc_005fstruct_007d-variable-attribute_002c-x86-3371"></a>
|
|
If <code>packed</code> is used on a structure, or if bit-fields are used,
|
|
it may be that the Microsoft ABI lays out the structure differently
|
|
than the way GCC normally does. Particularly when moving packed
|
|
data between functions compiled with GCC and the native Microsoft compiler
|
|
(either via function call or as data in a file), it may be necessary to access
|
|
either format.
|
|
|
|
<p>Currently <samp><span class="option">-m[no-]ms-bitfields</span></samp> is provided for the Microsoft Windows x86
|
|
compilers to match the native Microsoft compiler.
|
|
|
|
<p>The Microsoft structure layout algorithm is fairly simple with the exception
|
|
of the bit-field packing.
|
|
The padding and alignment of members of structures and whether a bit-field
|
|
can straddle a storage-unit boundary are determine by these rules:
|
|
|
|
<ol type=1 start=1>
|
|
<li>Structure members are stored sequentially in the order in which they are
|
|
declared: the first member has the lowest memory address and the last member
|
|
the highest.
|
|
|
|
<li>Every data object has an alignment requirement. The alignment requirement
|
|
for all data except structures, unions, and arrays is either the size of the
|
|
object or the current packing size (specified with either the
|
|
<code>aligned</code> attribute or the <code>pack</code> pragma),
|
|
whichever is less. For structures, unions, and arrays,
|
|
the alignment requirement is the largest alignment requirement of its members.
|
|
Every object is allocated an offset so that:
|
|
|
|
<pre class="smallexample"> offset % alignment_requirement == 0
|
|
</pre>
|
|
<li>Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation
|
|
unit if the integral types are the same size and if the next bit-field fits
|
|
into the current allocation unit without crossing the boundary imposed by the
|
|
common alignment requirements of the bit-fields.
|
|
</ol>
|
|
|
|
<p>MSVC interprets zero-length bit-fields in the following ways:
|
|
|
|
<ol type=1 start=1>
|
|
<li>If a zero-length bit-field is inserted between two bit-fields that
|
|
are normally coalesced, the bit-fields are not coalesced.
|
|
|
|
<p>For example:
|
|
|
|
<pre class="smallexample"> struct
|
|
{
|
|
unsigned long bf_1 : 12;
|
|
unsigned long : 0;
|
|
unsigned long bf_2 : 12;
|
|
} t1;
|
|
</pre>
|
|
<p class="noindent">The size of <code>t1</code> is 8 bytes with the zero-length bit-field. If the
|
|
zero-length bit-field were removed, <code>t1</code>'s size would be 4 bytes.
|
|
|
|
<li>If a zero-length bit-field is inserted after a bit-field, <code>foo</code>, and the
|
|
alignment of the zero-length bit-field is greater than the member that follows it,
|
|
<code>bar</code>, <code>bar</code> is aligned as the type of the zero-length bit-field.
|
|
|
|
<p>For example:
|
|
|
|
<pre class="smallexample"> struct
|
|
{
|
|
char foo : 4;
|
|
short : 0;
|
|
char bar;
|
|
} t2;
|
|
|
|
struct
|
|
{
|
|
char foo : 4;
|
|
short : 0;
|
|
double bar;
|
|
} t3;
|
|
</pre>
|
|
<p class="noindent">For <code>t2</code>, <code>bar</code> is placed at offset 2, rather than offset 1.
|
|
Accordingly, the size of <code>t2</code> is 4. For <code>t3</code>, the zero-length
|
|
bit-field does not affect the alignment of <code>bar</code> or, as a result, the size
|
|
of the structure.
|
|
|
|
<p>Taking this into account, it is important to note the following:
|
|
|
|
<ol type=1 start=1>
|
|
<li>If a zero-length bit-field follows a normal bit-field, the type of the
|
|
zero-length bit-field may affect the alignment of the structure as whole. For
|
|
example, <code>t2</code> has a size of 4 bytes, since the zero-length bit-field follows a
|
|
normal bit-field, and is of type short.
|
|
|
|
<li>Even if a zero-length bit-field is not followed by a normal bit-field, it may
|
|
still affect the alignment of the structure:
|
|
|
|
<pre class="smallexample"> struct
|
|
{
|
|
char foo : 6;
|
|
long : 0;
|
|
} t4;
|
|
</pre>
|
|
<p class="noindent">Here, <code>t4</code> takes up 4 bytes.
|
|
</ol>
|
|
|
|
<li>Zero-length bit-fields following non-bit-field members are ignored:
|
|
|
|
<pre class="smallexample"> struct
|
|
{
|
|
char foo;
|
|
long : 0;
|
|
char bar;
|
|
} t5;
|
|
</pre>
|
|
<p class="noindent">Here, <code>t5</code> takes up 2 bytes.
|
|
</ol>
|
|
</dl>
|
|
|
|
<h4 class="subsection">6.38.10 Xstormy16 Variable Attributes</h4>
|
|
|
|
<p>One attribute is currently defined for xstormy16 configurations:
|
|
<code>below100</code>.
|
|
|
|
<dl>
|
|
<dt><code>below100</code><dd><a name="index-g_t_0040code_007bbelow100_007d-variable-attribute_002c-Xstormy16-3372"></a>
|
|
If a variable has the <code>below100</code> attribute (<code>BELOW100</code> is
|
|
allowed also), GCC places the variable in the first 0x100 bytes of
|
|
memory and use special opcodes to access it. Such variables are
|
|
placed in either the <code>.bss_below100</code> section or the
|
|
<code>.data_below100</code> section.
|
|
|
|
</dl>
|
|
|
|
</body></html>
|
|
|