вівторок, 29 грудня 2015 р.

Reporting Bugs

Your bug reports play an essential role in making GCC reliable.
When you encounter a problem, the first thing to do is to see if it is already known. See Trouble. If it isn't known, then you should report the problem.

Extracting the Function Pointer from a Bound Pointer to Member Function

In C++, pointer to member functions (PMFs) are implemented using a wide pointer of sorts to handle all the possible call mechanisms; the PMF needs to store information about how to adjust the ‘this’ pointer, and if the function pointed to is virtual, where to find the vtable, and where in the vtable to look for the member function. If you are using PMFs in an inner loop, you should really reconsider that decision. If that is not an option, you can extract the pointer to the function that would be called for a given object/PMF pair and call it directly inside the inner loop, to save a bit of time.
Note that you still pay the penalty for the call through a function pointer; on most modern architectures, such a call defeats the branch prediction features of the CPU. This is also true of normal virtual function calls.
The syntax for this extension is

extern A a;


extern int (A::*fp)();


typedef int (*fptr)(A *);


fptr p = (fptr)(a.*fp);

For PMF constants (i.e. expressions of the form ‘&Klasse::Member’), no object is needed to obtain the address of the function. They can be converted to function pointers directly:
     fptr p1 = (fptr)(&A::foo);

You must specify -Wno-pmf-conversions to use this extension.     

Have You Found a Bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the compiler gets a fatal signal, for any input whatever, that is a compiler bug. Reliable compilers never crash.
  • If the compiler produces invalid assembly code, for any input whatever (except an asm statement), that is a compiler bug, unless the compiler reports errors (not just warnings) which would ordinarily prevent the assembler from being run.
  • If the compiler produces valid assembly code that does not correctly execute the input source code, that is a compiler bug.
    However, you must double-check to make sure, because you may have a program whose behavior is undefined, which happened by chance to give the desired results with another C or C++ compiler.
    For example, in many nonoptimizing compilers, you can write ‘x;’ at the end of a function instead of ‘return x;’, with the same results. But the value of the function is undefined if returnis omitted; it is not a bug when GCC produces different results.
    Problems often result from expressions with two increment operators, as in f (*p++, *p++). Your previous compiler might have interpreted that expression the way you intended; GCC might interpret it another way. Neither compiler is wrong. The bug is in your code.

    After you have localized the error to a single source line, it should be easy to check for these things. If your program is correct and well defined, you have found a compiler bug.
  • If the compiler produces an error message for valid input, that is a compiler bug.
  • If the compiler does not produce an error message for invalid input, that is a compiler bug. However, you should note that your idea of “invalid input” might be someone else's idea of “an extension” or “support for traditional practice”.
  • If you are an experienced user of one of the languages GCC supports, your suggestions for improvement of GCC are welcome in any case.  

Blackfin Options

-mcpu=cpu[-sirevision]

Specifies the name of the target Blackfin processor. Currently, cpucan be one of ‘bf512’, ‘bf514’, ‘bf516’, ‘bf518’, ‘bf522’, ‘bf523’, ‘bf524’, ‘bf525’, ‘bf526’, ‘bf527’, ‘bf531’, ‘bf532’, ‘bf533’, ‘bf534’, ‘bf536’, ‘bf537’, ‘bf538’, ‘bf539’, ‘bf542’, ‘bf544’, ‘bf547’, ‘bf548’, ‘bf549’, ‘bf542m’, ‘bf544m’, ‘bf547m’, ‘bf548m’, ‘bf549m’, ‘bf561’, ‘bf592’.
The optional sirevision specifies the silicon revision of the target Blackfin processor. Any workarounds available for the targeted silicon revision are enabled. If sirevision is ‘none’, no workarounds are enabled. If sirevision is ‘any’, all workarounds for the targeted processor are enabled. The __SILICON_REVISION__ macro is defined to two hexadecimal digits representing the major and minor numbers in the silicon revision. If sirevision is ‘none’, the __SILICON_REVISION__is not defined. If sirevision is ‘any’, the __SILICON_REVISION__ is defined to be 0xffff. If this optional sirevision is not used, GCC assumes the latest known silicon revision of the targeted Blackfin processor.

GCC defines a preprocessor macro for the specified cpu. For the ‘bfin-elf’ toolchain, this option causes the hardware BSP provided by libgloss to be linked in if -msim is not given.
Without this option, ‘bf532’ is used as the processor by default.
Note that support for ‘bf561’ is incomplete. For ‘bf561’, only the preprocessor macro is defined.
-msim
Specifies that the program will be run on the simulator. This causes the simulator BSP provided by libgloss to be linked in. This option has effect only for ‘bfin-elf’ toolchain. Certain other options, such as -mid-shared-library and -mfdpic, imply -msim.
-momit-leaf-frame-pointer
Don't keep the frame pointer in a register for leaf functions. This avoids the instructions to save, set up and restore frame pointers and makes an extra register available in leaf functions. The option -fomit-frame-pointer removes the frame pointer for all functions, which might make debugging harder.
-mspecld-anomaly
When enabled, the compiler ensures that the generated code does not contain speculative loads after jump instructions. If this option is used, __WORKAROUND_SPECULATIVE_LOADS is defined.
-mno-specld-anomaly
Don't generate extra code to prevent speculative loads from occurring.
-mcsync-anomaly
When enabled, the compiler ensures that the generated code does not contain CSYNC or SSYNC instructions too soon after conditional branches. If this option is used, __WORKAROUND_SPECULATIVE_SYNCS is defined.
-mno-csync-anomaly
Don't generate extra code to prevent CSYNC or SSYNC instructions from occurring too soon after a conditional branch.
-mlow-64k
When enabled, the compiler is free to take advantage of the knowledge that the entire program fits into the low 64k of memory.
-mno-low-64k
Assume that the program is arbitrarily large. This is the default.
-mstack-check-l1
Do stack checking using information placed into L1 scratchpad memory by the uClinux kernel.
-mid-shared-library
Generate code that supports shared libraries via the library ID method. This allows for execute in place and shared libraries in an environment without virtual memory management. This option implies -fPIC. With a ‘bfin-elf’ target, this option implies -msim.
-mno-id-shared-library
Generate code that doesn't assume ID-based shared libraries are being used. This is the default.
-mleaf-id-shared-library
Generate code that supports shared libraries via the library ID method, but assumes that this library or executable won't link against any other ID shared libraries. That allows the compiler to use faster code for jumps and calls.
-mno-leaf-id-shared-library
Do not assume that the code being compiled won't link against any ID shared libraries. Slower code is generated for jump and call insns.
-mshared-library-id=n
Specifies the identification number of the ID-based shared library being compiled. Specifying a value of 0 generates more compact code; specifying other values forces the allocation of that number to the current library but is no more space- or time-efficient than omitting this option.
-msep-data
Generate code that allows the data segment to be located in a different area of memory from the text segment. This allows for execute in place in an environment without virtual memory management by eliminating relocations against the text section.
-mno-sep-data
Generate code that assumes that the data segment follows the text segment. This is the default.
-mlong-calls
-mno-long-calls
Tells the compiler to perform function calls by first loading the address of the function into a register and then performing a subroutine call on this register. This switch is needed if the target function lies outside of the 24-bit addressing range of the offset-based version of subroutine call instruction.
This feature is not enabled by default. Specifying -mno-long-calls restores the default behavior. Note these switches have no effect on how the compiler generates code to handle function calls via function pointers.
-mfast-fp
Link with the fast floating-point library. This library relaxes some of the IEEE floating-point standard's rules for checking inputs against Not-a-Number (NAN), in the interest of performance.
-minline-plt
Enable inlining of PLT entries in function calls to functions that are not known to bind locally. It has no effect without -mfdpic.
-mmulticore
Build a standalone application for multicore Blackfin processors. This option causes proper start files and link scripts supporting multicore to be used, and defines the macro __BFIN_MULTICORE. It can only be used with -mcpu=bf561[-sirevision].
This option can be used with -mcorea or -mcoreb, which selects the one-application-per-core programming model. Without -mcorea or -mcoreb, the single-application/dual-core programming model is used. In this model, the main function of Core B should be named as coreb_main.
If this option is not used, the single-core application programming model is used.
-mcorea
Build a standalone application for Core A of BF561 when using the one-application-per-core programming model. Proper start files and link scripts are used to support Core A, and the macro __BFIN_COREA is defined. This option can only be used in conjunction with -mmulticore.
-mcoreb
Build a standalone application for Core B of BF561 when using the one-application-per-core programming model. Proper start files and link scripts are used to support Core B, and the macro __BFIN_COREB is defined. When this option is used, coreb_mainshould be used instead of main. This option can only be used in conjunction with -mmulticore.
-msdram
Build a standalone application for SDRAM. Proper start files and link scripts are used to put the application into SDRAM, and the macro __BFIN_SDRAM is defined. The loader should initialize SDRAM before loading the application.
-micplb
Assume that ICPLBs are enabled at run time. This has an effect on certain anomaly workarounds. For Linux targets, the default is to assume ICPLBs are enabled; for standalone applications the default is off.  

Blackfin Built-in Functions

Currently, there are two Blackfin-specific built-in functions. These are used for generating CSYNC and SSYNC machine insns without using inline assembly; by using these built-in functions the compiler can automatically add workarounds for hardware errata involving these instructions. These functions are named as follows:



void __builtin_bfin_csync (void)


void __builtin_bfin_ssync (void)

Binary Constants using the ‘0b’ Prefix

Integer constants can be written as binary constants, consisting of a sequence of ‘0’ and ‘1’ digits, prefixed by ‘0b’ or ‘0B’. This is particularly useful in environments that operate a lot on the bit level (like microcontrollers).
The following statements are identical:

i = 42;

i = 0x2a;

i = 0b101010;


i = 052;


The type of these constants follows the same rules as for octal or hexadecimal integer constants, so suffixes like ‘L’ or ‘UL’ can be applied.     

Basic Asm — Assembler Instructions Without Operands

A basic asm statement has the following syntax:

     asm [ volatile ] ( AssemblerInstructions )
The asm keyword is a GNU extension. When writing code that can be compiled with -ansi and the various -std options, use __asm__ instead of asm (see Alternate Keywords).
Qualifiers
volatile
The optional volatile qualifier has no effect. All basic asm blocks are implicitly volatile.
Parameters
AssemblerInstructions
This is a literal string that specifies the assembler code. The string can contain any instructions recognized by the assembler, including directives. GCC does not parse the assembler instructions themselves and does not know what they mean or even whether they are valid assembler input.
You may place multiple assembler instructions together in a single asmstring, separated by the characters normally used in assembly code for the system. A combination that works in most places is a newline to break the line, plus a tab character (written as ‘\n\t’). Some assemblers allow semicolons as a line separator. However, note that some assembler dialects use semicolons to start a comment.
Remarks
Using extended asm typically produces smaller, safer, and more efficient code, and in most cases it is a better solution than basic asm. However, there are two situations where only basic asmcan be used:
  • Extended asm statements have to be inside a C function, so to write inline assembly language at file scope (“top-level”), outside of C functions, you must use basic asm. You can use this technique to emit assembler directives, define assembly language macros that can be invoked elsewhere in the file, or write entire functions in assembly language.
  • Functions declared with the naked attribute also require basic asm(see Function Attributes).
Safely accessing C data and calling functions from basic asm is more complex than it may appear. To access C data, it is better to use extended asm.
Do not expect a sequence of asm statements to remain perfectly consecutive after compilation. If certain instructions need to remain consecutive in the output, put them in a single multi-instruction asmstatement. Note that GCC's optimizers can move asm statements relative to other code, including across jumps.
asm statements may not perform jumps into other asm statements. GCC does not know about these jumps, and therefore cannot take account of them when deciding how to optimize. Jumps from asm to C labels are only supported in extended asm.
Under certain circumstances, GCC may duplicate (or remove duplicates of) your assembly code when optimizing. This can lead to unexpected duplicate symbol errors during compilation if your assembly code defines symbols or labels.
Since GCC does not parse the AssemblerInstructions, it has no visibility of any symbols it references. This may result in GCC discarding those symbols as unreferenced.
The compiler copies the assembler instructions in a basic asmverbatim to the assembly language output file, without processing dialects or any of the ‘%’ operators that are available with extended asm. This results in minor differences between basic asm strings and extended asm templates. For example, to refer to registers you might use ‘%eax’ in basic asm and ‘%%eax’ in extended asm.
On targets such as x86 that support multiple assembler dialects, all basic asm blocks use the assembler dialect specified by the -masm command-line option (see x86 Options). Basic asm provides no mechanism to provide different assembler strings for different dialects.
Here is an example of basic asm for i386:


/* Note that this code will not compile with -masm=intel */


#define DebugBreak() asm("int $3")

Backwards Compatibility

Now that there is a definitive ISO standard C++, G++ has a specification to adhere to. The C++ language evolved over time, and features that used to be acceptable in previous drafts of the standard, such as the ARM [Annotated C++ Reference Manual], are no longer accepted. In order to allow compilation of C++ written to such drafts, G++ contains some backwards compatibilities. All such backwards compatibility features are liable to disappear in future versions of G++. They should be considered deprecated. See Deprecated Features.

For scope
If a variable is declared at for scope, it used to remain in scope until the end of the scope that contained the for statement (rather than just within the for scope). G++ retains this, but issues a warning, if such a variable is accessed outside the for scope.
Implicit C language
Old C system header files did not contain an extern "C" {...}scope to set the language. On such systems, all header files are implicitly scoped inside a C language scope. Also, an empty prototype () is treated as an unspecified number of arguments, rather than no arguments, as C++ demands.  

понеділок, 28 грудня 2015 р.

Specifying Attributes of Variables

The keyword __attribute__ 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 Function Attributes), labels (see Label Attributes) and for types (see Type Attributes). Other front ends might define more attributes (see Extensions to the C++ Language).
You may also specify attributes with ‘__’ 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 __aligned__ instead of aligned.
See Attribute Syntax, for details of the exact syntax for using attributes.
aligned (alignment)
This attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:
          int x __attribute__ ((aligned (16))) = 0;
causes the compiler to allocate the global variable x on a 16-byte boundary. On a 68040, this could be used in conjunction with an asm expression to access the move16 instruction which requires 16-byte aligned operands.
You can also specify the alignment of structure fields. For example, to create a double-word aligned int pair, you could write:
          struct foo { int x[2] __attribute__ ((aligned (8))); };
This is an alternative to creating a union with a double member, which forces the union to be double-word aligned.
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.
GCC also provides a target specific macro __BIGGEST_ALIGNMENT__, which is the largest alignment ever used for any data type on the target machine you are compiling for. For example, you could write:
          short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
The compiler automatically sets the alignment for the declared variable or field to __BIGGEST_ALIGNMENT__. 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 __BIGGEST_ALIGNMENT__may change depending on command-line options.
When used on a struct, or struct member, the aligned attribute can only increase the alignment; in order to decrease it, the packedattribute must be specified as well. When used as part of a typedef, the aligned attribute can both increase and decrease alignment, and specifying the packed attribute generates a warning.
Note that the effectiveness of aligned 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 aligned(16)in an __attribute__ still only provides you with 8-byte alignment. See your linker documentation for further information.
The aligned attribute can also be used for functions (see Function Attributes.)
cleanup (cleanup_function)
The cleanup 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.
If -fexceptions is enabled, then cleanup_functionis run during the stack unwinding that happens during the processing of the exception. Note that the cleanup attribute does not allow the exception to be caught, only to perform an action. It is undefined what happens if cleanup_function does not return normally.
common
nocommon
The common attribute requests GCC to place a variable in “common” storage. The nocommon attribute requests the opposite—to allocate space for it directly.
These attributes override the default chosen by the -fno-common and -fcommon flags respectively.
deprecated
deprecated (msg)
The deprecated 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:

extern int old_var __attribute__ ((deprecated));

extern int old_var;

int new_fn () { return old_var; }

results in a warning on line 3 but not line 2. The optional msgargument, which must be a string, is printed in the warning if present.
The deprecated attribute can also be used for functions and types (see Function Attributes, see Type Attributes.)
mode (mode)
This attribute specifies the data type for the declaration—whichever type corresponds to the mode mode. This in effect lets you request an integer or floating-point type according to its width.
You may also specify a mode of byte or __byte__ to indicate the mode corresponding to a one-byte integer, word or __word__ for the mode of a one-word integer, and pointeror __pointer__ for the mode used to represent pointers.
packed
The packed 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 aligned attribute.
Here is a structure in which the field x is packed, so that it immediately follows a:

struct foo

{

int x[2] __attribute__ ((packed));

char a;

};

Note: The 4.1, 4.2 and 4.3 series of GCC ignore the packed attribute on bit-fields of type char. This has been fixed in GCC 4.4 but the change can lead to differences in the structure layout. See the documentation of -Wpacked-bitfield-compat for more information.
section ("section-name")
Normally, the compiler places the objects it generates in sections like data and bss. 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 sectionattribute specifies that a variable (or function) lives in a particular section. For example, this small program uses several specific section names:

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()
{

/* Initialize stack pointer */


init_sp (stack + sizeof (stack));


/* Initialize initialized data */


memcpy (&init_data, &data, &edata - &data);


/* Turn on the serial ports */


init_duart (&a);

init_duart (&b);

}

Use the section attribute with global variables and not local variables, as shown in the example.
You may use the section 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 common (or bss) section and can be multiply “defined”. Using the section 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 -fno-common flag or the nocommon attribute.
Some file formats do not support arbitrary sections so the sectionattribute 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.
shared
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 shared and marking the section shareable:

int foo __attribute__((section ("shared"), shared)) = 0;

int
main()
{

/* Read and write foo. All running


copies see the same value. */


return 0;


}

You may only use the shared attribute along with sectionattribute with a fully-initialized global definition because of the way linkers work. See section attribute for more information.
The shared attribute is only available on Microsoft Windows.
tls_model ("tls_model")
The tls_model attribute sets thread-local storage model (see Thread-Local) of a particular __thread variable, overriding -ftls-model= command-line switch on a per-variable basis. The tls_model argument should be one of global-dynamic, local-dynamic, initial-exec or local-exec.
Not all targets support this attribute.
unused
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.
used
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.
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.
vector_size (bytes)
This attribute specifies the vector size for the variable, measured in bytes. For example, the declaration:
          int foo __attribute__ ((vector_size (16)));
causes the compiler to set the mode for foo, to be 16 bytes, divided into int sized units. Assuming a 32-bit int (a vector of 4 units of 4 bytes), the corresponding mode of foo is V4SI.
This attribute is only applicable to integral and float scalars, although arrays, pointers, and function return values are allowed in conjunction with this construct.
Aggregates with this attribute are invalid, even if they are of the same size as a corresponding scalar. For example, the declaration:

struct S { int a; };


struct S __attribute__ ((vector_size (16))) foo;

is invalid even if the size of the structure is the same as the size of the int.
selectany
The 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 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 selectany attribute is only available on Microsoft Windows targets. You can use __declspec (selectany) as a synonym for __attribute__ ((selectany)) for compatibility with other compilers.
weak
The weak attribute is described in Function Attributes.
dllimport
The dllimport attribute is described in Function Attributes.
dllexport
The dllexport attribute is described in Function Attributes.

6.38.1 AVR Variable Attributes

progmem
The progmem attribute is used on the AVR to place read-only data in the non-volatile program memory (flash). The progmemattribute accomplishes this by putting respective variables into a section whose name starts with .progmem.
This attribute works similar to the section attribute but adds additional checking. Notice that just like the section attribute, progmem affects the location of the data but not how this data is accessed.
In order to read data located with the progmem attribute (inline) assembler must be used.

/* Use custom macros from AVR-LibC */


#include


/* Locate var in flash memory */

const int var[2] PROGMEM = { 1, 2 };

/* Access var[] by accessor macro from avr/pgmspace.h */

int read_var (int i)
{

}


return (int) pgm_read_word (& var[i]);

AVR is a Harvard architecture processor and data and read-only data normally resides in the data memory (RAM).
See also the AVR Named Address Spaces section for an alternate way to locate and access data in flash memory.
io
io (addr)
Variables with the io 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:
          volatile int porta __attribute__((io (0x22)));
The address specified in the address in the data address range.
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:
          extern volatile int porta __attribute__((io));

io_low
io_low (addr)
This is like the io attribute, but additionally it informs the compiler that the object lies in the lower half of the I/O area, allowing the use of cbi, sbi, sbic and sbisinstructions.
address
address (addr)
Variables with the address attribute are used to address memory-mapped peripherals that may lie outside the io address range.
          volatile int porta __attribute__((address (0x600)));

6.38.2 Blackfin Variable Attributes

Three attributes are currently defined for the Blackfin.
l1_data
l1_data_A
l1_data_B
Use these attributes on the Blackfin to place the variable into L1 Data SRAM. Variables with l1_data attribute are put into the specific section named .l1.data. Those with l1_data_A attribute are put into the specific section named .l1.data.A. Those with l1_data_Battribute are put into the specific section named .l1.data.B.
l2
Use this attribute on the Blackfin to place the variable into L2 SRAM. Variables with l2 attribute are put into the specific section named .l2.data.

6.38.3 H8/300 Variable Attributes

These variable attributes are available for H8/300 targets:
eightbit_data
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.
You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly.
tiny_data
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.

6.38.4 IA-64 Variable Attributes

The IA-64 back end supports the following variable attribute:
model (model-name)
On IA-64, use this attribute to set the addressability of an object. At present, the only supported identifier for model-name is small, indicating addressability via “small” (22-bit) addresses (so that their addresses can be loaded with the addlinstruction). Caveat: such addressing is by definition not position independent and hence this attribute must not be used for objects defined by shared libraries.

6.38.5 M32R/D Variable Attributes

One attribute is currently defined for the M32R/D.
model (model-name)
Use this attribute on the M32R/D to set the addressability of an object. The identifier model-name is one of small, medium, or large, representing each of the code models.
Small model objects live in the lower 16MB of memory (so that their addresses can be loaded with the ld24 instruction).
Medium and large model objects may live anywhere in the 32-bit address space (the compiler generates seth/add3 instructions to load their addresses).

6.38.6 MeP Variable Attributes

The MeP target has a number of addressing modes and busses. The near space spans the standard memory space's first 16 megabytes (24 bits). The far space spans the entire 32-bit memory space. The based space is a 128-byte region in the memory space that is addressed relative to the $tp register. The tinyspace is a 65536-byte region relative to the $gp register. In addition to these memory regions, the MeP target has a separate 16-bit control bus which is specified with cb attributes.
based
Any variable with the based attribute is assigned to the .based section, and is accessed with relative to the $tp register.
tiny
Likewise, the tiny attribute assigned variables to the .tiny section, relative to the $gp register.
near
Variables with the near attribute are assumed to have addresses that fit in a 24-bit addressing mode. This is the default for large variables (-mtiny=4 is the default) but this attribute can override -mtiny= for small variables, or override -ml.
far
Variables with the far 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.
io
io (addr)
Variables with the io 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:
          int timer_count __attribute__((io(0x123)));

cb
cb (addr)
Variables with the cb attribute are used to access the control bus, using special instructions. addr indicates the control bus address. Example:
          int cpu_clock __attribute__((cb(0x123)));

6.38.7 PowerPC Variable Attributes

Three attributes currently are defined for PowerPC configurations: altivec, ms_struct and gcc_struct.
For full documentation of the struct attributes please see the documentation in x86 Variable Attributes.
For documentation of altivec attribute please see the documentation in PowerPC Type Attributes.

6.38.8 SPU Variable Attributes

The SPU supports the spu_vector attribute for variables. For documentation of this attribute please see the documentation in SPU Type Attributes.

6.38.9 x86 Variable Attributes

Two attributes are currently defined for x86 configurations: ms_struct and gcc_struct.
ms_struct
gcc_struct
If packed 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.
Currently -m[no-]ms-bitfields is provided for the Microsoft Windows x86 compilers to match the native Microsoft compiler.
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:
  1. 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.
  2. 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 aligned attribute or the pack 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:
                   offset % alignment_requirement == 0
  3. 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.
MSVC interprets zero-length bit-fields in the following ways:
  1. If a zero-length bit-field is inserted between two bit-fields that are normally coalesced, the bit-fields are not coalesced.
    For example:

    struct

    {

    unsigned long bf_1 : 12;

    unsigned long : 0;

    } t1;


    unsigned long bf_2 : 12;

    The size of t1 is 8 bytes with the zero-length bit-field. If the zero-length bit-field were removed, t1's size would be 4 bytes.
  2. If a zero-length bit-field is inserted after a bit-field, foo, and the alignment of the zero-length bit-field is greater than the member that follows it, bar, bar is aligned as the type of the zero-length bit-field.
    For example:

    struct

    {

    char foo : 4;

    short : 0;


    char bar;
    } t2;

    char foo : 4;

    struct
    {
    short : 0;

    } t3;


    double bar;

    For t2, bar is placed at offset 2, rather than offset 1. Accordingly, the size of t2 is 4. For t3, the zero-length bit-field does not affect the alignment of bar or, as a result, the size of the structure.
    Taking this into account, it is important to note the following:
    1. 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, t2 has a size of 4 bytes, since the zero-length bit-field follows a normal bit-field, and is of type short.
    2. Even if a zero-length bit-field is not followed by a normal bit-field, it may still affect the alignment of the structure:

      struct

      {

      char foo : 6;

      long : 0;

      } t4;

      Here, t4 takes up 4 bytes.
  3. Zero-length bit-fields following non-bit-field members are ignored:

    struct

    {

    char foo;

    long : 0;

    } t5;


    char bar;

    Here, t5 takes up 2 bytes.

6.38.10 Xstormy16 Variable Attributes

One attribute is currently defined for xstormy16 configurations: below100.

below100
If a variable has the below100 attribute (BELOW100 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 .bss_below100 section or the .data_below100 section.   

AVR Options

These options are defined for AVR implementations:

-mmcu=mcu
Specify Atmel AVR instruction set architectures (ISA) or MCU type.
The default for this option is ‘avr2’.
GCC supports the following AVR devices and ISAs:
avr2
“Classic” devices with up to 8 KiB of program memory. 
mcu = attiny22, attiny26, at90c8534, at90s2313, at90s2323, at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515, at90s8535
avr25
“Classic” devices with up to 8 KiB of program memory and with the MOVW instruction. 
mcu = ata5272, ata6616c, attiny13, attiny13a, attiny2313, attiny2313a, attiny24, attiny24a, attiny25, attiny261, attiny261a, attiny43u, attiny4313, attiny44, attiny44a, attiny441, attiny45, attiny461, attiny461a, attiny48, attiny828, attiny84, attiny84a, attiny841, attiny85, attiny861, attiny861a, attiny87, attiny88, at86rf401
avr3
“Classic” devices with 16 KiB up to 64 KiB of program memory. 
mcu = at43usb355, at76c711
avr31
“Classic” devices with 128 KiB of program memory. 
mcu = atmega103, at43usb320
avr35
“Classic” devices with 16 KiB up to 64 KiB of program memory and with the MOVW instruction. 
mcu = ata5505, ata6617c, ata664251, atmega16u2, atmega32u2, atmega8u2, attiny1634, attiny167, at90usb162, at90usb82
avr4
“Enhanced” devices with up to 8 KiB of program memory. 
mcu = ata6285, ata6286, ata6289, ata6612c, atmega48, atmega48a, atmega48p, atmega48pa, atmega8, atmega8a, atmega8hva, atmega8515, atmega8535, atmega88, atmega88a, atmega88p, atmega88pa, at90pwm1, at90pwm2, at90pwm2b, at90pwm3, at90pwm3b, at90pwm81
avr5
“Enhanced” devices with 16 KiB up to 64 KiB of program memory. 
mcu = ata5702m322, ata5782, ata5790, ata5790n, ata5795, ata5831, ata6613c, ata6614q, atmega16, atmega16a, atmega16hva, atmega16hva2, atmega16hvb, atmega16hvbrevb, atmega16m1, atmega16u4, atmega161, atmega162, atmega163, atmega164a, atmega164p, atmega164pa, atmega165, atmega165a, atmega165p, atmega165pa, atmega168, atmega168a, atmega168p, atmega168pa, atmega169, atmega169a, atmega169p, atmega169pa, atmega32, atmega32a, atmega32c1, atmega32hvb, atmega32hvbrevb, atmega32m1, atmega32u4, atmega32u6, atmega323, atmega324a, atmega324p, atmega324pa, atmega325, atmega325a, atmega325p, atmega325pa, atmega3250, atmega3250a, atmega3250p, atmega3250pa, atmega328, atmega328p, atmega329, atmega329a, atmega329p, atmega329pa, atmega3290, atmega3290a, atmega3290p, atmega3290pa, atmega406, atmega64, atmega64a, atmega64c1, atmega64hve, atmega64hve2, atmega64m1, atmega64rfr2, atmega640, atmega644, atmega644a, atmega644p, atmega644pa, atmega644rfr2, atmega645, atmega645a, atmega645p, atmega6450, atmega6450a, atmega6450p, atmega649, atmega649a, atmega649p, atmega6490, atmega6490a, atmega6490p, at90can32, at90can64, at90pwm161, at90pwm216, at90pwm316, at90scr100, at90usb646, at90usb647, at94k, m3000
avr51
“Enhanced” devices with 128 KiB of program memory. 
mcu = atmega128, atmega128a, atmega128rfa1, atmega128rfr2, atmega1280, atmega1281, atmega1284, atmega1284p, atmega1284rfr2, at90can128, at90usb1286, at90usb1287
avr6
“Enhanced” devices with 3-byte PC, i.e. with more than 128 KiB of program memory. 
mcu = atmega256rfr2, atmega2560, atmega2561, atmega2564rfr2
avrxmega2
“XMEGA” devices with more than 8 KiB and up to 64 KiB of program memory. 
mcu = atxmega16a4, atxmega16a4u, atxmega16c4, atxmega16d4, atxmega16e5, atxmega32a4, atxmega32a4u, atxmega32c3, atxmega32c4, atxmega32d3, atxmega32d4, atxmega32e5, atxmega8e5
avrxmega4
“XMEGA” devices with more than 64 KiB and up to 128 KiB of program memory. 
mcu = atxmega64a3, atxmega64a3u, atxmega64a4u, atxmega64b1, atxmega64b3, atxmega64c3, atxmega64d3, atxmega64d4
avrxmega5
“XMEGA” devices with more than 64 KiB and up to 128 KiB of program memory and more than 64 KiB of RAM. 
mcu = atxmega64a1, atxmega64a1u
avrxmega6
“XMEGA” devices with more than 128 KiB of program memory. 
mcu = atxmega128a3, atxmega128a3u, atxmega128b1, atxmega128b3, atxmega128c3, atxmega128d3, atxmega128d4, atxmega192a3, atxmega192a3u, atxmega192c3, atxmega192d3, atxmega256a3, atxmega256a3b, atxmega256a3bu, atxmega256a3u, atxmega256c3, atxmega256d3, atxmega384c3, atxmega384d3
avrxmega7
“XMEGA” devices with more than 128 KiB of program memory and more than 64 KiB of RAM. 
mcu = atxmega128a1, atxmega128a1u, atxmega128a4u
avrtiny
“TINY” Tiny core devices with 512 B up to 4 KiB of program memory. 
mcu = attiny10, attiny20, attiny4, attiny40, attiny5, attiny9
avr1
This ISA is implemented by the minimal AVR core and supported for assembler only. 
mcu = attiny11, attiny12, attiny15, attiny28, at90s1200.

-maccumulate-args
Accumulate outgoing function arguments and acquire/release the needed stack space for outgoing function arguments once in function prologue/epilogue. Without this option, outgoing arguments are pushed before calling a function and popped afterwards.
Popping the arguments after the function call can be expensive on AVR so that accumulating the stack space might lead to smaller executables because arguments need not to be removed from the stack after such a function call.
This option can lead to reduced code size for functions that perform several calls to functions that get their arguments on the stack like calls to printf-like functions.
-mbranch-cost=cost
Set the branch costs for conditional branch instructions to cost. Reasonable values for cost are small, non-negative integers. The default branch cost is 0.
-mcall-prologues
Functions prologues/epilogues are expanded as calls to appropriate subroutines. Code size is smaller.
-mint8
Assume int to be 8-bit integer. This affects the sizes of all types: a char is 1 byte, an int is 1 byte, a long is 2 bytes, and long long is 4 bytes. Please note that this option does not conform to the C standards, but it results in smaller code size.
-mn-flash=num
Assume that the flash memory has a size of num times 64 KiB.
-mno-interrupts
Generated code is not compatible with hardware interrupts. Code size is smaller.
-mrelax
Try to replace CALL resp. JMP instruction by the shorter RCALL resp. RJMP instruction if applicable. Setting -mrelax just adds the --mlink-relax option to the assembler's command line and the --relax option to the linker's command line.
Jump relaxing is performed by the linker because jump offsets are not known before code is located. Therefore, the assembler code generated by the compiler is the same, but the instructions in the executable may differ from instructions in the assembler code.
Relaxing must be turned on if linker stubs are needed, see the section on EIND and linker stubs below.
-mrmw
Assume that the device supports the Read-Modify-Write instructions XCH, LAC, LAS and LAT.
-msp8
Treat the stack pointer register as an 8-bit register, i.e. assume the high byte of the stack pointer is zero. In general, you don't need to set this option by hand.
This option is used internally by the compiler to select and build multilibs for architectures avr2 and avr25. These architectures mix devices with and without SPH. For any setting other than -mmcu=avr2 or -mmcu=avr25the compiler driver adds or removes this option from the compiler proper's command line, because the compiler then knows if the device or architecture has an 8-bit stack pointer and thus no SPHregister or not.
-mstrict-X
Use address register X in a way proposed by the hardware. This means that X is only used in indirect, post-increment or pre-decrement addressing.
Without this option, the X register may be used in the same way as Y or Z which then is emulated by additional instructions. For example, loading a value with X+const addressing with a small non-negative const < 64 to a register Rn is performed as

adiw r26, const ; X += const


ld Rn, X ; Rn = *X


sbiw r26, const ; X -= const


-mtiny-stack
Only change the lower 8 bits of the stack pointer.
-nodevicelib
Don't link against AVR-LibC's device specific library libdev.a.
-Waddr-space-convert
Warn about conversions between address spaces in the case where the resulting address space is not contained in the incoming address space.
3.17.5.1 EIND and Devices with More Than 128 Ki Bytes of Flash
Pointers in the implementation are 16 bits wide. The address of a function or label is represented as word address so that indirect jumps and calls can target any code address in the range of 64 Ki words.
In order to facilitate indirect jump on devices with more than 128 Ki bytes of program memory space, there is a special function register called EIND that serves as most significant part of the target address when EICALL or EIJMP instructions are used.
Indirect jumps and calls on these devices are handled as follows by the compiler and are subject to some limitations:
  • The compiler never sets EIND.
  • The compiler uses EIND implicitely in EICALL/EIJMPinstructions or might read EIND directly in order to emulate an indirect call/jump by means of a RET instruction.
  • The compiler assumes that EIND never changes during the startup code or during the application. In particular, EIND is not saved/restored in function or interrupt service routine prologue/epilogue.
  • For indirect calls to functions and computed goto, the linker generates stubs. Stubs are jump pads sometimes also called trampolines. Thus, the indirect call/jump jumps to such a stub. The stub contains a direct jump to the desired address.
  • Linker relaxation must be turned on so that the linker generates the stubs correctly in all situations. See the compiler option -mrelax and the linker option --relax. There are corner cases where the linker is supposed to generate stubs but aborts without relaxation and without a helpful error message.
  • The default linker script is arranged for code with EIND = 0. If code is supposed to work for a setup with EIND != 0, a custom linker script has to be used in order to place the sections whose name start with .trampolines into the segment where EINDpoints to.
  • The startup code from libgcc never sets EIND. Notice that startup code is a blend of code from libgcc and AVR-LibC. For the impact of AVR-LibC on EIND, see the AVR-LibC user manual.
  • It is legitimate for user-specific startup code to set up EINDearly, for example by means of initialization code located in section .init3. Such code runs prior to general startup code that initializes RAM and calls constructors, but after the bit of startup code from AVR-LibC that sets EIND to the segment where the vector table is located.

    #include


    __attribute__((section(".init3"),naked,used,no_instrument_function))

    static void

    {

    init3_set_eind (void)

    __asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"

    "out %i0,r24" :: "n" (&EIND) : "r24","memory");

    }

    The __trampolines_start symbol is defined in the linker script.
  • Stubs are generated automatically by the linker if the following two conditions are met:
    • The address of a label is taken by means of the gs modifier (short for generate stubs) like so:

      LDI r24, lo8(gs(func))


      LDI r25, hi8(gs(func))

    • The final location of that label is in a code segment outside the segment where the stubs are located.
  • The compiler emits such gs modifiers for code labels in the following situations:
    • Taking address of a function or code label.
    • Computed goto.
    • If prologue-save function is used, see -mcall-prologuescommand-line option.
    • Switch/case dispatch tables. If you do not want such dispatch tables you can specify the -fno-jump-tables command-line option.
    • C and C++ constructors/destructors called during startup/shutdown.
    • If the tools hit a gs() modifier explained above.
  • Jumping to non-symbolic addresses like so is not supported:

    int main (void)

    {

    /* Call function at word address 0x2 */

    return ((int(*)(void)) 0x2)();

    }

    Instead, a stub has to be set up, i.e. the function has to be called through a symbol (func_4 in the example):

    int main (void)

    {

    extern int func_4 (void);


    /* Call function at byte address 0x4 */

    return func_4();

    }

    and the application be linked with -Wl,--defsym,func_4=0x4. Alternatively, func_4 can be defined in the linker script.
3.17.5.2 Handling of the RAMPD, RAMPX, RAMPY and RAMPZ Special Function Registers
Some AVR devices support memories larger than the 64 KiB range that can be accessed with 16-bit pointers. To access memory locations outside this 64 KiB range, the contentent of a RAMPregister is used as high part of the address: The X, Y, Z address register is concatenated with the RAMPX, RAMPY, RAMPZ special function register, respectively, to get a wide address. Similarly, RAMPD is used together with direct addressing.
  • The startup code initializes the RAMP special function registers with zero.
  • If a named address space other than generic or __flash is used, then RAMPZ is set as needed before the operation.
  • If the device supports RAM larger than 64 KiB and the compiler needs to change RAMPZ to accomplish an operation, RAMPZis reset to zero after the operation.
  • If the device comes with a specific RAMP register, the ISR prologue/epilogue saves/restores that SFR and initializes it with zero in case the ISR code might (implicitly) use it.
  • RAM larger than 64 KiB is not supported by GCC for AVR targets. If you use inline assembler to read from locations outside the 16-bit address range and change one of the RAMP registers, you must reset it to zero after the access.
3.17.5.3 AVR Built-in Macros
GCC defines several built-in macros so that the user code can test for the presence or absence of features. Almost any of the following built-in macros are deduced from device capabilities and thus triggered by the -mmcu= command-line option.
For even more AVR-specific built-in macros see AVR Named Address Spaces and AVR Built-in Functions.

__AVR_ARCH__
Build-in macro that resolves to a decimal number that identifies the architecture and depends on the -mmcu=mcu option. Possible values are:
2, 25, 3, 31, 35, 4, 5, 51, 6
for mcu=avr2, avr25, avr3, avr31, avr35, avr4, avr5, avr51, avr6,
respectively and
100, 102, 104, 105, 106, 107
for mcu=avrtiny, avrxmega2, avrxmega4, avrxmega5, avrxmega6, avrxmega7, respectively. If mcu specifies a device, this built-in macro is set accordingly. For example, with -mmcu=atmega8 the macro is defined to 4.
__AVR_Device__
Setting -mmcu=device defines this built-in macro which reflects the device's name. For example, -mmcu=atmega8 defines the built-in macro __AVR_ATmega8__, -mmcu=attiny261a defines __AVR_ATtiny261A__, etc.
The built-in macros' names follow the scheme __AVR_Device__ where Device is the device name as from the AVR user manual. The difference between Device in the built-in macro and device in -mmcu=device is that the latter is always lowercase.
If device is not a device but only a core architecture like ‘avr51’, this macro is not defined.
__AVR_DEVICE_NAME__
Setting -mmcu=device defines this built-in macro to the device's name. For example, with -mmcu=atmega8 the macro is defined to atmega8.
If device is not a device but only a core architecture like ‘avr51’, this macro is not defined.
__AVR_XMEGA__
The device / architecture belongs to the XMEGA family of devices.
__AVR_HAVE_ELPM__
The device has the the ELPM instruction.
__AVR_HAVE_ELPMX__
The device has the ELPM Rn,Z and ELPM Rn,Z+ instructions.
__AVR_HAVE_MOVW__
The device has the MOVW instruction to perform 16-bit register-register moves.
__AVR_HAVE_LPMX__
The device has the LPM Rn,Z and LPM Rn,Z+ instructions.
__AVR_HAVE_MUL__
The device has a hardware multiplier.
__AVR_HAVE_JMP_CALL__
The device has the JMP and CALL instructions. This is the case for devices with at least 16 KiB of program memory.
__AVR_HAVE_EIJMP_EICALL__
__AVR_3_BYTE_PC__
The device has the EIJMP and EICALL instructions. This is the case for devices with more than 128 KiB of program memory. This also means that the program counter (PC) is 3 bytes wide.
__AVR_2_BYTE_PC__
The program counter (PC) is 2 bytes wide. This is the case for devices with up to 128 KiB of program memory.
__AVR_HAVE_8BIT_SP__
__AVR_HAVE_16BIT_SP__
The stack pointer (SP) register is treated as 8-bit respectively 16-bit register by the compiler. The definition of these macros is affected by -mtiny-stack.
__AVR_HAVE_SPH__
__AVR_SP8__
The device has the SPH (high part of stack pointer) special function register or has an 8-bit stack pointer, respectively. The definition of these macros is affected by -mmcu= and in the cases of -mmcu=avr2 and -mmcu=avr25 also by -msp8.
__AVR_HAVE_RAMPD__
__AVR_HAVE_RAMPX__
__AVR_HAVE_RAMPY__
__AVR_HAVE_RAMPZ__
The device has the RAMPD, RAMPX, RAMPY, RAMPZ special function register, respectively.
__NO_INTERRUPTS__
This macro reflects the -mno-interrupts command-line option.
__AVR_ERRATA_SKIP__
__AVR_ERRATA_SKIP_JMP_CALL__
Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit instructions because of a hardware erratum. Skip instructions are SBRS, SBRC, SBIS, SBIC and CPSE. The second macro is only defined if __AVR_HAVE_JMP_CALL__ is also set.
__AVR_ISA_RMW__
The device has Read-Modify-Write instructions (XCH, LAC, LAS and LAT).
__AVR_SFR_OFFSET__=offset
Instructions that can address I/O special function registers directly like IN, OUT, SBI, etc. may use a different address as if addressed by an instruction to access RAM like LDor STS. This offset depends on the device architecture and has to be subtracted from the RAM address in order to get the respective I/O address.
__WITH_AVRLIBC__
The compiler is configured to be used together with AVR-Libc. See the --with-avrlibc configure option.