+++ /dev/null
-This is doc/gcc.info, produced by makeinfo version 4.5 from
-doc/gcc.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gcc: (gcc). The GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the use of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 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.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "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.
-
-\1f
-File: gcc.info, Node: Machine Constraints, Prev: Modifiers, Up: Constraints
-
-Constraints for Particular Machines
------------------------------------
-
- Whenever possible, you should use the general-purpose constraint
-letters in `asm' arguments, since they will convey meaning more readily
-to people reading your code. Failing that, use the constraint letters
-that usually have very similar meanings across architectures. The most
-commonly used constraints are `m' and `r' (for memory and
-general-purpose registers respectively; *note Simple Constraints::), and
-`I', usually the letter indicating the most common immediate-constant
-format.
-
- For each machine architecture, the `config/MACHINE/MACHINE.h' file
-defines additional constraints. These constraints are used by the
-compiler itself for instruction generation, as well as for `asm'
-statements; therefore, some of the constraints are not particularly
-interesting for `asm'. The constraints are defined through these
-macros:
-
-`REG_CLASS_FROM_LETTER'
- Register class constraints (usually lower case).
-
-`CONST_OK_FOR_LETTER_P'
- Immediate constant constraints, for non-floating point constants of
- word size or smaller precision (usually upper case).
-
-`CONST_DOUBLE_OK_FOR_LETTER_P'
- Immediate constant constraints, for all floating point constants
- and for constants of greater than word size precision (usually
- upper case).
-
-`EXTRA_CONSTRAINT'
- Special cases of registers or memory. This macro is not required,
- and is only defined for some machines.
-
- Inspecting these macro definitions in the compiler source for your
-machine is the best way to be certain you have the right constraints.
-However, here is a summary of the machine-dependent constraints
-available on some particular machines.
-
-_ARM family--`arm.h'_
-
- `f'
- Floating-point register
-
- `F'
- One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0,
- 4.0, 5.0 or 10.0
-
- `G'
- Floating-point constant that would satisfy the constraint `F'
- if it were negated
-
- `I'
- Integer that is valid as an immediate operand in a data
- processing instruction. That is, an integer in the range 0
- to 255 rotated by a multiple of 2
-
- `J'
- Integer in the range -4095 to 4095
-
- `K'
- Integer that satisfies constraint `I' when inverted (ones
- complement)
-
- `L'
- Integer that satisfies constraint `I' when negated (twos
- complement)
-
- `M'
- Integer in the range 0 to 32
-
- `Q'
- A memory reference where the exact address is in a single
- register (``m'' is preferable for `asm' statements)
-
- `R'
- An item in the constant pool
-
- `S'
- A symbol in the text segment of the current file
-
-_AMD 29000 family--`a29k.h'_
-
- `l'
- Local register 0
-
- `b'
- Byte Pointer (`BP') register
-
- `q'
- `Q' register
-
- `h'
- Special purpose register
-
- `A'
- First accumulator register
-
- `a'
- Other accumulator register
-
- `f'
- Floating point register
-
- `I'
- Constant greater than 0, less than 0x100
-
- `J'
- Constant greater than 0, less than 0x10000
-
- `K'
- Constant whose high 24 bits are on (1)
-
- `L'
- 16-bit constant whose high 8 bits are on (1)
-
- `M'
- 32-bit constant whose high 16 bits are on (1)
-
- `N'
- 32-bit negative constant that fits in 8 bits
-
- `O'
- The constant 0x80000000 or, on the 29050, any 32-bit constant
- whose low 16 bits are 0.
-
- `P'
- 16-bit negative constant that fits in 8 bits
-
- `G'
- `H'
- A floating point constant (in `asm' statements, use the
- machine independent `E' or `F' instead)
-
-_AVR family--`avr.h'_
-
- `l'
- Registers from r0 to r15
-
- `a'
- Registers from r16 to r23
-
- `d'
- Registers from r16 to r31
-
- `w'
- Registers from r24 to r31. These registers can be used in
- `adiw' command
-
- `e'
- Pointer register (r26-r31)
-
- `b'
- Base pointer register (r28-r31)
-
- `q'
- Stack pointer register (SPH:SPL)
-
- `t'
- Temporary register r0
-
- `x'
- Register pair X (r27:r26)
-
- `y'
- Register pair Y (r29:r28)
-
- `z'
- Register pair Z (r31:r30)
-
- `I'
- Constant greater than -1, less than 64
-
- `J'
- Constant greater than -64, less than 1
-
- `K'
- Constant integer 2
-
- `L'
- Constant integer 0
-
- `M'
- Constant that fits in 8 bits
-
- `N'
- Constant integer -1
-
- `O'
- Constant integer 8, 16, or 24
-
- `P'
- Constant integer 1
-
- `G'
- A floating point constant 0.0
-
-_IBM RS6000--`rs6000.h'_
-
- `b'
- Address base register
-
- `f'
- Floating point register
-
- `h'
- `MQ', `CTR', or `LINK' register
-
- `q'
- `MQ' register
-
- `c'
- `CTR' register
-
- `l'
- `LINK' register
-
- `x'
- `CR' register (condition register) number 0
-
- `y'
- `CR' register (condition register)
-
- `z'
- `FPMEM' stack memory for FPR-GPR transfers
-
- `I'
- Signed 16-bit constant
-
- `J'
- Unsigned 16-bit constant shifted left 16 bits (use `L'
- instead for `SImode' constants)
-
- `K'
- Unsigned 16-bit constant
-
- `L'
- Signed 16-bit constant shifted left 16 bits
-
- `M'
- Constant larger than 31
-
- `N'
- Exact power of 2
-
- `O'
- Zero
-
- `P'
- Constant whose negation is a signed 16-bit constant
-
- `G'
- Floating point constant that can be loaded into a register
- with one instruction per word
-
- `Q'
- Memory operand that is an offset from a register (`m' is
- preferable for `asm' statements)
-
- `R'
- AIX TOC entry
-
- `S'
- Constant suitable as a 64-bit mask operand
-
- `T'
- Constant suitable as a 32-bit mask operand
-
- `U'
- System V Release 4 small data area reference
-
-_Intel 386--`i386.h'_
-
- `q'
- `a', `b', `c', or `d' register for the i386. For x86-64 it
- is equivalent to `r' class. (for 8-bit instructions that do
- not use upper halves)
-
- `Q'
- `a', `b', `c', or `d' register. (for 8-bit instructions, that
- do use upper halves)
-
- `R'
- Legacy register--equivalent to `r' class in i386 mode. (for
- non-8-bit registers used together with 8-bit upper halves in
- a single instruction)
-
- `A'
- Specifies the `a' or `d' registers. This is primarily useful
- for 64-bit integer values (when in 32-bit mode) intended to
- be returned with the `d' register holding the most
- significant bits and the `a' register holding the least
- significant bits.
-
- `f'
- Floating point register
-
- `t'
- First (top of stack) floating point register
-
- `u'
- Second floating point register
-
- `a'
- `a' register
-
- `b'
- `b' register
-
- `c'
- `c' register
-
- `d'
- `d' register
-
- `D'
- `di' register
-
- `S'
- `si' register
-
- `x'
- `xmm' SSE register
-
- `y'
- MMX register
-
- `I'
- Constant in range 0 to 31 (for 32-bit shifts)
-
- `J'
- Constant in range 0 to 63 (for 64-bit shifts)
-
- `K'
- `0xff'
-
- `L'
- `0xffff'
-
- `M'
- 0, 1, 2, or 3 (shifts for `lea' instruction)
-
- `N'
- Constant in range 0 to 255 (for `out' instruction)
-
- `Z'
- Constant in range 0 to `0xffffffff' or symbolic reference
- known to fit specified range. (for using immediates in zero
- extending 32-bit to 64-bit x86-64 instructions)
-
- `e'
- Constant in range -2147483648 to 2147483647 or symbolic
- reference known to fit specified range. (for using
- immediates in 64-bit x86-64 instructions)
-
- `G'
- Standard 80387 floating point constant
-
-_Intel 960--`i960.h'_
-
- `f'
- Floating point register (`fp0' to `fp3')
-
- `l'
- Local register (`r0' to `r15')
-
- `b'
- Global register (`g0' to `g15')
-
- `d'
- Any local or global register
-
- `I'
- Integers from 0 to 31
-
- `J'
- 0
-
- `K'
- Integers from -31 to 0
-
- `G'
- Floating point 0
-
- `H'
- Floating point 1
-
-_MIPS--`mips.h'_
-
- `d'
- General-purpose integer register
-
- `f'
- Floating-point register (if available)
-
- `h'
- `Hi' register
-
- `l'
- `Lo' register
-
- `x'
- `Hi' or `Lo' register
-
- `y'
- General-purpose integer register
-
- `z'
- Floating-point status register
-
- `I'
- Signed 16-bit constant (for arithmetic instructions)
-
- `J'
- Zero
-
- `K'
- Zero-extended 16-bit constant (for logic instructions)
-
- `L'
- Constant with low 16 bits zero (can be loaded with `lui')
-
- `M'
- 32-bit constant which requires two instructions to load (a
- constant which is not `I', `K', or `L')
-
- `N'
- Negative 16-bit constant
-
- `O'
- Exact power of two
-
- `P'
- Positive 16-bit constant
-
- `G'
- Floating point zero
-
- `Q'
- Memory reference that can be loaded with more than one
- instruction (`m' is preferable for `asm' statements)
-
- `R'
- Memory reference that can be loaded with one instruction (`m'
- is preferable for `asm' statements)
-
- `S'
- Memory reference in external OSF/rose PIC format (`m' is
- preferable for `asm' statements)
-
-_Motorola 680x0--`m68k.h'_
-
- `a'
- Address register
-
- `d'
- Data register
-
- `f'
- 68881 floating-point register, if available
-
- `x'
- Sun FPA (floating-point) register, if available
-
- `y'
- First 16 Sun FPA registers, if available
-
- `I'
- Integer in the range 1 to 8
-
- `J'
- 16-bit signed number
-
- `K'
- Signed number whose magnitude is greater than 0x80
-
- `L'
- Integer in the range -8 to -1
-
- `M'
- Signed number whose magnitude is greater than 0x100
-
- `G'
- Floating point constant that is not a 68881 constant
-
- `H'
- Floating point constant that can be used by Sun FPA
-
-_Motorola 68HC11 & 68HC12 families--`m68hc11.h'_
-
- `a'
- Register 'a'
-
- `b'
- Register 'b'
-
- `d'
- Register 'd'
-
- `q'
- An 8-bit register
-
- `t'
- Temporary soft register _.tmp
-
- `u'
- A soft register _.d1 to _.d31
-
- `w'
- Stack pointer register
-
- `x'
- Register 'x'
-
- `y'
- Register 'y'
-
- `z'
- Pseudo register 'z' (replaced by 'x' or 'y' at the end)
-
- `A'
- An address register: x, y or z
-
- `B'
- An address register: x or y
-
- `D'
- Register pair (x:d) to form a 32-bit value
-
- `L'
- Constants in the range -65536 to 65535
-
- `M'
- Constants whose 16-bit low part is zero
-
- `N'
- Constant integer 1 or -1
-
- `O'
- Constant integer 16
-
- `P'
- Constants in the range -8 to 2
-
-
-_SPARC--`sparc.h'_
-
- `f'
- Floating-point register that can hold 32- or 64-bit values.
-
- `e'
- Floating-point register that can hold 64- or 128-bit values.
-
- `I'
- Signed 13-bit constant
-
- `J'
- Zero
-
- `K'
- 32-bit constant with the low 12 bits clear (a constant that
- can be loaded with the `sethi' instruction)
-
- `L'
- A constant in the range supported by `movcc' instructions
-
- `M'
- A constant in the range supported by `movrcc' instructions
-
- `N'
- Same as `K', except that it verifies that bits that are not
- in the lower 32-bit range are all zero. Must be used instead
- of `K' for modes wider than `SImode'
-
- `G'
- Floating-point zero
-
- `H'
- Signed 13-bit constant, sign-extended to 32 or 64 bits
-
- `Q'
- Floating-point constant whose integral representation can be
- moved into an integer register using a single sethi
- instruction
-
- `R'
- Floating-point constant whose integral representation can be
- moved into an integer register using a single mov instruction
-
- `S'
- Floating-point constant whose integral representation can be
- moved into an integer register using a high/lo_sum
- instruction sequence
-
- `T'
- Memory address aligned to an 8-byte boundary
-
- `U'
- Even register
-
- `W'
- Memory address for `e' constraint registers.
-
-
-_TMS320C3x/C4x--`c4x.h'_
-
- `a'
- Auxiliary (address) register (ar0-ar7)
-
- `b'
- Stack pointer register (sp)
-
- `c'
- Standard (32-bit) precision integer register
-
- `f'
- Extended (40-bit) precision register (r0-r11)
-
- `k'
- Block count register (bk)
-
- `q'
- Extended (40-bit) precision low register (r0-r7)
-
- `t'
- Extended (40-bit) precision register (r0-r1)
-
- `u'
- Extended (40-bit) precision register (r2-r3)
-
- `v'
- Repeat count register (rc)
-
- `x'
- Index register (ir0-ir1)
-
- `y'
- Status (condition code) register (st)
-
- `z'
- Data page register (dp)
-
- `G'
- Floating-point zero
-
- `H'
- Immediate 16-bit floating-point constant
-
- `I'
- Signed 16-bit constant
-
- `J'
- Signed 8-bit constant
-
- `K'
- Signed 5-bit constant
-
- `L'
- Unsigned 16-bit constant
-
- `M'
- Unsigned 8-bit constant
-
- `N'
- Ones complement of unsigned 16-bit constant
-
- `O'
- High 16-bit constant (32-bit constant with 16 LSBs zero)
-
- `Q'
- Indirect memory reference with signed 8-bit or index register
- displacement
-
- `R'
- Indirect memory reference with unsigned 5-bit displacement
-
- `S'
- Indirect memory reference with 1 bit or index register
- displacement
-
- `T'
- Direct memory reference
-
- `U'
- Symbolic address
-
-
-_S/390 and zSeries--`s390.h'_
-
- `a'
- Address register (general purpose register except r0)
-
- `d'
- Data register (arbitrary general purpose register)
-
- `f'
- Floating-point register
-
- `I'
- Unsigned 8-bit constant (0-255)
-
- `J'
- Unsigned 12-bit constant (0-4095)
-
- `K'
- Signed 16-bit constant (-32768-32767)
-
- `L'
- Unsigned 16-bit constant (0-65535)
-
- `Q'
- Memory reference without index register
-
- `S'
- Symbolic constant suitable for use with the `larl' instruction
-
-
-_Xstormy16--`stormy16.h'_
-
- `a'
- Register r0.
-
- `b'
- Register r1.
-
- `c'
- Register r2.
-
- `d'
- Register r8.
-
- `e'
- Registers r0 through r7.
-
- `t'
- Registers r0 and r1.
-
- `y'
- The carry register.
-
- `z'
- Registers r8 and r9.
-
- `I'
- A constant between 0 and 3 inclusive.
-
- `J'
- A constant that has exactly one bit set.
-
- `K'
- A constant that has exactly one bit clear.
-
- `L'
- A constant between 0 and 255 inclusive.
-
- `M'
- A constant between -255 and 0 inclusive.
-
- `N'
- A constant between -3 and 0 inclusive.
-
- `O'
- A constant between 1 and 4 inclusive.
-
- `P'
- A constant between -4 and -1 inclusive.
-
- `Q'
- A memory reference that is a stack push.
-
- `R'
- A memory reference that is a stack pop.
-
- `S'
- A memory reference that refers to an constant address of
- known value.
-
- `T'
- The register indicated by Rx (not implemented yet).
-
- `U'
- A constant that is not between 2 and 15 inclusive.
-
-
-_Xtensa--`xtensa.h'_
-
- `a'
- General-purpose 32-bit register
-
- `b'
- One-bit boolean register
-
- `A'
- MAC16 40-bit accumulator register
-
- `I'
- Signed 12-bit integer constant, for use in MOVI instructions
-
- `J'
- Signed 8-bit integer constant, for use in ADDI instructions
-
- `K'
- Integer constant valid for BccI instructions
-
- `L'
- Unsigned constant valid for BccUI instructions
-
-
-
-\1f
-File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Constraints, Up: C Extensions
-
-Controlling Names Used in Assembler Code
-========================================
-
- You can specify the name to be used in the assembler code for a C
-function or variable by writing the `asm' (or `__asm__') keyword after
-the declarator as follows:
-
- int foo asm ("myfoo") = 2;
-
-This specifies that the name to be used for the variable `foo' in the
-assembler code should be `myfoo' rather than the usual `_foo'.
-
- On systems where an underscore is normally prepended to the name of
-a C function or variable, this feature allows you to define names for
-the linker that do not start with an underscore.
-
- It does not make sense to use this feature with a non-static local
-variable since such variables do not have assembler names. If you are
-trying to put the variable in a particular register, see *Note Explicit
-Reg Vars::. GCC presently accepts such code with a warning, but will
-probably be changed to issue an error, rather than a warning, in the
-future.
-
- You cannot use `asm' in this way in a function _definition_; but you
-can get the same effect by writing a declaration for the function
-before its definition and putting `asm' there, like this:
-
- extern func () asm ("FUNC");
-
- func (x, y)
- int x, y;
- ...
-
- It is up to you to make sure that the assembler names you choose do
-not conflict with any other assembler symbols. Also, you must not use a
-register name; that would produce completely invalid assembler code.
-GCC does not as yet have the ability to store static variables in
-registers. Perhaps that will be added.
-
-\1f
-File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions
-
-Variables in Specified Registers
-================================
-
- GNU C allows you to put a few global variables into specified
-hardware registers. You can also specify the register in which an
-ordinary register variable should be allocated.
-
- * Global register variables reserve registers throughout the program.
- This may be useful in programs such as programming language
- interpreters which have a couple of global variables that are
- accessed very often.
-
- * Local register variables in specific registers do not reserve the
- registers. The compiler's data flow analysis is capable of
- determining where the specified registers contain live values, and
- where they are available for other uses. Stores into local
- register variables may be deleted when they appear to be dead
- according to dataflow analysis. References to local register
- variables may be deleted or moved or simplified.
-
- These local variables are sometimes convenient for use with the
- extended `asm' feature (*note Extended Asm::), if you want to
- write one output of the assembler instruction directly into a
- particular register. (This will work provided the register you
- specify fits the constraints specified for that operand in the
- `asm'.)
-
-* Menu:
-
-* Global Reg Vars::
-* Local Reg Vars::
-
-\1f
-File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars
-
-Defining Global Register Variables
-----------------------------------
-
- You can define a global register variable in GNU C like this:
-
- register int *foo asm ("a5");
-
-Here `a5' is the name of the register which should be used. Choose a
-register which is normally saved and restored by function calls on your
-machine, so that library routines will not clobber it.
-
- Naturally the register name is cpu-dependent, so you would need to
-conditionalize your program according to cpu type. The register `a5'
-would be a good choice on a 68000 for a variable of pointer type. On
-machines with register windows, be sure to choose a "global" register
-that is not affected magically by the function call mechanism.
-
- In addition, operating systems on one type of cpu may differ in how
-they name the registers; then you would need additional conditionals.
-For example, some 68000 operating systems call this register `%a5'.
-
- Eventually there may be a way of asking the compiler to choose a
-register automatically, but first we need to figure out how it should
-choose and how to enable you to guide the choice. No solution is
-evident.
-
- Defining a global register variable in a certain register reserves
-that register entirely for this use, at least within the current
-compilation. The register will not be allocated for any other purpose
-in the functions in the current compilation. The register will not be
-saved and restored by these functions. Stores into this register are
-never deleted even if they would appear to be dead, but references may
-be deleted or moved or simplified.
-
- It is not safe to access the global register variables from signal
-handlers, or from more than one thread of control, because the system
-library routines may temporarily use the register for other things
-(unless you recompile them specially for the task at hand).
-
- It is not safe for one function that uses a global register variable
-to call another such function `foo' by way of a third function `lose'
-that was compiled without knowledge of this variable (i.e. in a
-different source file in which the variable wasn't declared). This is
-because `lose' might save the register and put some other value there.
-For example, you can't expect a global register variable to be
-available in the comparison-function that you pass to `qsort', since
-`qsort' might have put something else in that register. (If you are
-prepared to recompile `qsort' with the same global register variable,
-you can solve this problem.)
-
- If you want to recompile `qsort' or other source files which do not
-actually use your global register variable, so that they will not use
-that register for any other purpose, then it suffices to specify the
-compiler option `-ffixed-REG'. You need not actually add a global
-register declaration to their source code.
-
- A function which can alter the value of a global register variable
-cannot safely be called from a function compiled without this variable,
-because it could clobber the value the caller expects to find there on
-return. Therefore, the function which is the entry point into the part
-of the program that uses the global register variable must explicitly
-save and restore the value which belongs to its caller.
-
- On most machines, `longjmp' will restore to each global register
-variable the value it had at the time of the `setjmp'. On some
-machines, however, `longjmp' will not change the value of global
-register variables. To be portable, the function that called `setjmp'
-should make other arrangements to save the values of the global register
-variables, and to restore them in a `longjmp'. This way, the same
-thing will happen regardless of what `longjmp' does.
-
- All global register variable declarations must precede all function
-definitions. If such a declaration could appear after function
-definitions, the declaration would be too late to prevent the register
-from being used for other purposes in the preceding functions.
-
- Global register variables may not have initial values, because an
-executable file has no means to supply initial contents for a register.
-
- On the Sparc, there are reports that g3 ... g7 are suitable
-registers, but certain library functions, such as `getwd', as well as
-the subroutines for division and remainder, modify g3 and g4. g1 and
-g2 are local temporaries.
-
- On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of
-course, it will not do to use more than a few of those.
-
-\1f
-File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
-
-Specifying Registers for Local Variables
-----------------------------------------
-
- You can define a local register variable with a specified register
-like this:
-
- register int *foo asm ("a5");
-
-Here `a5' is the name of the register which should be used. Note that
-this is the same syntax used for defining global register variables,
-but for a local variable it would appear within a function.
-
- Naturally the register name is cpu-dependent, but this is not a
-problem, since specific registers are most often useful with explicit
-assembler instructions (*note Extended Asm::). Both of these things
-generally require that you conditionalize your program according to cpu
-type.
-
- In addition, operating systems on one type of cpu may differ in how
-they name the registers; then you would need additional conditionals.
-For example, some 68000 operating systems call this register `%a5'.
-
- Defining such a register variable does not reserve the register; it
-remains available for other uses in places where flow control determines
-the variable's value is not live. However, these registers are made
-unavailable for use in the reload pass; excessive use of this feature
-leaves the compiler too few available registers to compile certain
-functions.
-
- This option does not guarantee that GCC will generate code that has
-this variable in the register you specify at all times. You may not
-code an explicit reference to this register in an `asm' statement and
-assume it will always refer to this variable.
-
- Stores into local register variables may be deleted when they appear
-to be dead according to dataflow analysis. References to local
-register variables may be deleted or moved or simplified.
-
-\1f
-File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions
-
-Alternate Keywords
-==================
-
- The option `-traditional' disables certain keywords; `-ansi' and the
-various `-std' options disable certain others. This causes trouble
-when you want to use GNU C extensions, or ISO C features, in a
-general-purpose header file that should be usable by all programs,
-including ISO C programs and traditional ones. The keywords `asm',
-`typeof' and `inline' cannot be used since they won't work in a program
-compiled with `-ansi' (although `inline' can be used in a program
-compiled with `-std=c99'), while the keywords `const', `volatile',
-`signed', `typeof' and `inline' won't work in a program compiled with
-`-traditional'. The ISO C99 keyword `restrict' is only available when
-`-std=gnu99' (which will eventually be the default) or `-std=c99' (or
-the equivalent `-std=iso9899:1999') is used.
-
- The way to solve these problems is to put `__' at the beginning and
-end of each problematical keyword. For example, use `__asm__' instead
-of `asm', `__const__' instead of `const', and `__inline__' instead of
-`inline'.
-
- Other C compilers won't accept these alternative keywords; if you
-want to compile with another compiler, you can define the alternate
-keywords as macros to replace them with the customary keywords. It
-looks like this:
-
- #ifndef __GNUC__
- #define __asm__ asm
- #endif
-
- `-pedantic' and other options cause warnings for many GNU C
-extensions. You can prevent such warnings within one expression by
-writing `__extension__' before the expression. `__extension__' has no
-effect aside from this.
-
-\1f
-File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions
-
-Incomplete `enum' Types
-=======================
-
- You can define an `enum' tag without specifying its possible values.
-This results in an incomplete type, much like what you get if you write
-`struct foo' without describing the elements. A later declaration
-which does specify the possible values completes the type.
-
- You can't allocate variables or storage using the type while it is
-incomplete. However, you can work with pointers to that type.
-
- This extension may not be very useful, but it makes the handling of
-`enum' more consistent with the way `struct' and `union' are handled.
-
- This extension is not supported by GNU C++.
-
-\1f
-File: gcc.info, Node: Function Names, Next: Return Address, Prev: Incomplete Enums, Up: C Extensions
-
-Function Names as Strings
-=========================
-
- GCC predefines two magic identifiers to hold the name of the current
-function. The identifier `__FUNCTION__' holds the name of the function
-as it appears in the source. The identifier `__PRETTY_FUNCTION__'
-holds the name of the function pretty printed in a language specific
-fashion.
-
- These names are always the same in a C function, but in a C++
-function they may be different. For example, this program:
-
- extern "C" {
- extern int printf (char *, ...);
- }
-
- class a {
- public:
- sub (int i)
- {
- printf ("__FUNCTION__ = %s\n", __FUNCTION__);
- printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
- }
- };
-
- int
- main (void)
- {
- a ax;
- ax.sub (0);
- return 0;
- }
-
-gives this output:
-
- __FUNCTION__ = sub
- __PRETTY_FUNCTION__ = int a::sub (int)
-
- The compiler automagically replaces the identifiers with a string
-literal containing the appropriate name. Thus, they are neither
-preprocessor macros, like `__FILE__' and `__LINE__', nor variables.
-This means that they catenate with other string literals, and that they
-can be used to initialize char arrays. For example
-
- char here[] = "Function " __FUNCTION__ " in " __FILE__;
-
- On the other hand, `#ifdef __FUNCTION__' does not have any special
-meaning inside a function, since the preprocessor does not do anything
-special with the identifier `__FUNCTION__'.
-
- Note that these semantics are deprecated, and that GCC 3.2 will
-handle `__FUNCTION__' and `__PRETTY_FUNCTION__' the same way as
-`__func__'. `__func__' is defined by the ISO standard C99:
-
- The identifier `__func__' is implicitly declared by the translator
- as if, immediately following the opening brace of each function
- definition, the declaration
- static const char __func__[] = "function-name";
-
- appeared, where function-name is the name of the lexically-enclosing
- function. This name is the unadorned name of the function.
-
- By this definition, `__func__' is a variable, not a string literal.
-In particular, `__func__' does not catenate with other string literals.
-
- In `C++', `__FUNCTION__' and `__PRETTY_FUNCTION__' are variables,
-declared in the same way as `__func__'.
-
-\1f
-File: gcc.info, Node: Return Address, Next: Vector Extensions, Prev: Function Names, Up: C Extensions
-
-Getting the Return or Frame Address of a Function
-=================================================
-
- These functions may be used to get information about the callers of a
-function.
-
- - Built-in Function: void * __builtin_return_address (unsigned int
- LEVEL)
- This function returns the return address of the current function,
- or of one of its callers. The LEVEL argument is number of frames
- to scan up the call stack. A value of `0' yields the return
- address of the current function, a value of `1' yields the return
- address of the caller of the current function, and so forth.
-
- The LEVEL argument must be a constant integer.
-
- On some machines it may be impossible to determine the return
- address of any function other than the current one; in such cases,
- or when the top of the stack has been reached, this function will
- return `0' or a random value. In addition,
- `__builtin_frame_address' may be used to determine if the top of
- the stack has been reached.
-
- This function should only be used with a nonzero argument for
- debugging purposes.
-
- - Built-in Function: void * __builtin_frame_address (unsigned int
- LEVEL)
- This function is similar to `__builtin_return_address', but it
- returns the address of the function frame rather than the return
- address of the function. Calling `__builtin_frame_address' with a
- value of `0' yields the frame address of the current function, a
- value of `1' yields the frame address of the caller of the current
- function, and so forth.
-
- The frame is the area on the stack which holds local variables and
- saved registers. The frame address is normally the address of the
- first word pushed on to the stack by the function. However, the
- exact definition depends upon the processor and the calling
- convention. If the processor has a dedicated frame pointer
- register, and the function has a frame, then
- `__builtin_frame_address' will return the value of the frame
- pointer register.
-
- On some machines it may be impossible to determine the frame
- address of any function other than the current one; in such cases,
- or when the top of the stack has been reached, this function will
- return `0' if the first frame pointer is properly initialized by
- the startup code.
-
- This function should only be used with a nonzero argument for
- debugging purposes.
-
-\1f
-File: gcc.info, Node: Vector Extensions, Next: Other Builtins, Prev: Return Address, Up: C Extensions
-
-Using vector instructions through built-in functions
-====================================================
-
- On some targets, the instruction set contains SIMD vector
-instructions that operate on multiple values contained in one large
-register at the same time. For example, on the i386 the MMX, 3Dnow!
-and SSE extensions can be used this way.
-
- The first step in using these extensions is to provide the necessary
-data types. This should be done using an appropriate `typedef':
-
- typedef int v4si __attribute__ ((mode(V4SI)));
-
- The base type `int' is effectively ignored by the compiler, the
-actual properties of the new type `v4si' are defined by the
-`__attribute__'. It defines the machine mode to be used; for vector
-types these have the form `VNB'; N should be the number of elements in
-the vector, and B should be the base mode of the individual elements.
-The following can be used as base modes:
-
-`QI'
- An integer that is as wide as the smallest addressable unit,
- usually 8 bits.
-
-`HI'
- An integer, twice as wide as a QI mode integer, usually 16 bits.
-
-`SI'
- An integer, four times as wide as a QI mode integer, usually 32
- bits.
-
-`DI'
- An integer, eight times as wide as a QI mode integer, usually 64
- bits.
-
-`SF'
- A floating point value, as wide as a SI mode integer, usually 32
- bits.
-
-`DF'
- A floating point value, as wide as a DI mode integer, usually 64
- bits.
-
- Not all base types or combinations are always valid; which modes can
-be used is determined by the target machine. For example, if
-targetting the i386 MMX extensions, only `V8QI', `V4HI' and `V2SI' are
-allowed modes.
-
- There are no `V1xx' vector modes - they would be identical to the
-corresponding base mode.
-
- There is no distinction between signed and unsigned vector modes.
-This distinction is made by the operations that perform on the vectors,
-not by the data type.
-
- The types defined in this manner are somewhat special, they cannot be
-used with most normal C operations (i.e., a vector addition can _not_
-be represented by a normal addition of two vector type variables). You
-can declare only variables and use them in function calls and returns,
-as well as in assignments and some casts. It is possible to cast from
-one vector type to another, provided they are of the same size (in
-fact, you can also cast vectors to and from other datatypes of the same
-size).
-
- A port that supports vector operations provides a set of built-in
-functions that can be used to operate on vectors. For example, a
-function to add two vectors and multiply the result by a third could
-look like this:
-
- v4si f (v4si a, v4si b, v4si c)
- {
- v4si tmp = __builtin_addv4si (a, b);
- return __builtin_mulv4si (tmp, c);
- }
-
-\1f
-File: gcc.info, Node: Other Builtins, Next: Target Builtins, Prev: Vector Extensions, Up: C Extensions
-
-Other built-in functions provided by GCC
-========================================
-
- GCC provides a large number of built-in functions other than the ones
-mentioned above. Some of these are for internal use in the processing
-of exceptions or variable-length argument lists and will not be
-documented here because they may change from time to time; we do not
-recommend general use of these functions.
-
- The remaining functions are provided for optimization purposes.
-
- GCC includes built-in versions of many of the functions in the
-standard C library. The versions prefixed with `__builtin_' will
-always be treated as having the same meaning as the C library function
-even if you specify the `-fno-builtin' option. (*note C Dialect
-Options::) Many of these functions are only optimized in certain cases;
-if they are not optimized in a particular case, a call to the library
-function will be emitted.
-
- The functions `abort', `exit', `_Exit' and `_exit' are recognized
-and presumed not to return, but otherwise are not built in. `_exit' is
-not recognized in strict ISO C mode (`-ansi', `-std=c89' or
-`-std=c99'). `_Exit' is not recognized in strict C89 mode (`-ansi' or
-`-std=c89').
-
- Outside strict ISO C mode, the functions `alloca', `bcmp', `bzero',
-`index', `rindex', `ffs', `fputs_unlocked', `printf_unlocked' and
-`fprintf_unlocked' may be handled as built-in functions. All these
-functions have corresponding versions prefixed with `__builtin_', which
-may be used even in strict C89 mode.
-
- The ISO C99 functions `conj', `conjf', `conjl', `creal', `crealf',
-`creall', `cimag', `cimagf', `cimagl', `llabs' and `imaxabs' are
-handled as built-in functions except in strict ISO C89 mode. There are
-also built-in versions of the ISO C99 functions `cosf', `cosl',
-`fabsf', `fabsl', `sinf', `sinl', `sqrtf', and `sqrtl', that are
-recognized in any mode since ISO C89 reserves these names for the
-purpose to which ISO C99 puts them. All these functions have
-corresponding versions prefixed with `__builtin_'.
-
- The ISO C89 functions `abs', `cos', `fabs', `fprintf', `fputs',
-`labs', `memcmp', `memcpy', `memset', `printf', `sin', `sqrt', `strcat',
-`strchr', `strcmp', `strcpy', `strcspn', `strlen', `strncat',
-`strncmp', `strncpy', `strpbrk', `strrchr', `strspn', and `strstr' are
-all recognized as built-in functions unless `-fno-builtin' is specified
-(or `-fno-builtin-FUNCTION' is specified for an individual function).
-All of these functions have corresponding versions prefixed with
-`__builtin_'.
-
- GCC provides built-in versions of the ISO C99 floating point
-comparison macros that avoid raising exceptions for unordered operands.
-They have the same names as the standard macros ( `isgreater',
-`isgreaterequal', `isless', `islessequal', `islessgreater', and
-`isunordered') , with `__builtin_' prefixed. We intend for a library
-implementor to be able to simply `#define' each standard macro to its
-built-in equivalent.
-
- - Built-in Function: int __builtin_types_compatible_p (TYPE1, TYPE2)
- You can use the built-in function `__builtin_types_compatible_p' to
- determine whether two types are the same.
-
- This built-in function returns 1 if the unqualified versions of the
- types TYPE1 and TYPE2 (which are types, not expressions) are
- compatible, 0 otherwise. The result of this built-in function can
- be used in integer constant expressions.
-
- This built-in function ignores top level qualifiers (e.g., `const',
- `volatile'). For example, `int' is equivalent to `const int'.
-
- The type `int[]' and `int[5]' are compatible. On the other hand,
- `int' and `char *' are not compatible, even if the size of their
- types, on the particular architecture are the same. Also, the
- amount of pointer indirection is taken into account when
- determining similarity. Consequently, `short *' is not similar to
- `short **'. Furthermore, two types that are typedefed are
- considered compatible if their underlying types are compatible.
-
- An `enum' type is considered to be compatible with another `enum'
- type. For example, `enum {foo, bar}' is similar to `enum {hot,
- dog}'.
-
- You would typically use this function in code whose execution
- varies depending on the arguments' types. For example:
-
- #define foo(x) \
- ({ \
- typeof (x) tmp; \
- if (__builtin_types_compatible_p (typeof (x), long double)) \
- tmp = foo_long_double (tmp); \
- else if (__builtin_types_compatible_p (typeof (x), double)) \
- tmp = foo_double (tmp); \
- else if (__builtin_types_compatible_p (typeof (x), float)) \
- tmp = foo_float (tmp); \
- else \
- abort (); \
- tmp; \
- })
-
- _Note:_ This construct is only available for C.
-
-
- - Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1, EXP2)
- You can use the built-in function `__builtin_choose_expr' to
- evaluate code depending on the value of a constant expression.
- This built-in function returns EXP1 if CONST_EXP, which is a
- constant expression that must be able to be determined at compile
- time, is nonzero. Otherwise it returns 0.
-
- This built-in function is analogous to the `? :' operator in C,
- except that the expression returned has its type unaltered by
- promotion rules. Also, the built-in function does not evaluate
- the expression that was not chosen. For example, if CONST_EXP
- evaluates to true, EXP2 is not evaluated even if it has
- side-effects.
-
- This built-in function can return an lvalue if the chosen argument
- is an lvalue.
-
- If EXP1 is returned, the return type is the same as EXP1's type.
- Similarly, if EXP2 is returned, its return type is the same as
- EXP2.
-
- Example:
-
- #define foo(x) \
- __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double), \
- foo_double (x), \
- __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \
- foo_float (x), \
- /* The void expression results in a compile-time error \
- when assigning the result to something. */ \
- (void)0))
-
- _Note:_ This construct is only available for C. Furthermore, the
- unused expression (EXP1 or EXP2 depending on the value of
- CONST_EXP) may still generate syntax errors. This may change in
- future revisions.
-
-
- - Built-in Function: int __builtin_constant_p (EXP)
- You can use the built-in function `__builtin_constant_p' to
- determine if a value is known to be constant at compile-time and
- hence that GCC can perform constant-folding on expressions
- involving that value. The argument of the function is the value
- to test. The function returns the integer 1 if the argument is
- known to be a compile-time constant and 0 if it is not known to be
- a compile-time constant. A return of 0 does not indicate that the
- value is _not_ a constant, but merely that GCC cannot prove it is
- a constant with the specified value of the `-O' option.
-
- You would typically use this function in an embedded application
- where memory was a critical resource. If you have some complex
- calculation, you may want it to be folded if it involves
- constants, but need to call a function if it does not. For
- example:
-
- #define Scale_Value(X) \
- (__builtin_constant_p (X) \
- ? ((X) * SCALE + OFFSET) : Scale (X))
-
- You may use this built-in function in either a macro or an inline
- function. However, if you use it in an inlined function and pass
- an argument of the function as the argument to the built-in, GCC
- will never return 1 when you call the inline function with a
- string constant or compound literal (*note Compound Literals::)
- and will not return 1 when you pass a constant numeric value to
- the inline function unless you specify the `-O' option.
-
- You may also use `__builtin_constant_p' in initializers for static
- data. For instance, you can write
-
- static const int table[] = {
- __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
- /* ... */
- };
-
- This is an acceptable initializer even if EXPRESSION is not a
- constant expression. GCC must be more conservative about
- evaluating the built-in in this case, because it has no
- opportunity to perform optimization.
-
- Previous versions of GCC did not accept this built-in in data
- initializers. The earliest version where it is completely safe is
- 3.0.1.
-
- - Built-in Function: long __builtin_expect (long EXP, long C)
- You may use `__builtin_expect' to provide the compiler with branch
- prediction information. In general, you should prefer to use
- actual profile feedback for this (`-fprofile-arcs'), as
- programmers are notoriously bad at predicting how their programs
- actually perform. However, there are applications in which this
- data is hard to collect.
-
- The return value is the value of EXP, which should be an integral
- expression. The value of C must be a compile-time constant. The
- semantics of the built-in are that it is expected that EXP == C.
- For example:
-
- if (__builtin_expect (x, 0))
- foo ();
-
- would indicate that we do not expect to call `foo', since we
- expect `x' to be zero. Since you are limited to integral
- expressions for EXP, you should use constructions such as
-
- if (__builtin_expect (ptr != NULL, 1))
- error ();
-
- when testing pointer or floating-point values.
-
- - Built-in Function: void __builtin_prefetch (const void *ADDR, ...)
- This function is used to minimize cache-miss latency by moving
- data into a cache before it is accessed. You can insert calls to
- `__builtin_prefetch' into code for which you know addresses of
- data in memory that is likely to be accessed soon. If the target
- supports them, data prefetch instructions will be generated. If
- the prefetch is done early enough before the access then the data
- will be in the cache by the time it is accessed.
-
- The value of ADDR is the address of the memory to prefetch. There
- are two optional arguments, RW and LOCALITY. The value of RW is a
- compile-time constant one or zero; one means that the prefetch is
- preparing for a write to the memory address and zero, the default,
- means that the prefetch is preparing for a read. The value
- LOCALITY must be a compile-time constant integer between zero and
- three. A value of zero means that the data has no temporal
- locality, so it need not be left in the cache after the access. A
- value of three means that the data has a high degree of temporal
- locality and should be left in all levels of cache possible.
- Values of one and two mean, respectively, a low or moderate degree
- of temporal locality. The default is three.
-
- for (i = 0; i < n; i++)
- {
- a[i] = a[i] + b[i];
- __builtin_prefetch (&a[i+j], 1, 1);
- __builtin_prefetch (&b[i+j], 0, 1);
- /* ... */
- }
-
- Data prefetch does not generate faults if ADDR is invalid, but the
- address expression itself must be valid. For example, a prefetch
- of `p->next' will not fault if `p->next' is not a valid address,
- but evaluation will fault if `p' is not a valid address.
-
- If the target does not support data prefetch, the address
- expression is evaluated if it includes side effects but no other
- code is generated and GCC does not issue a warning.
-
-\1f
-File: gcc.info, Node: Target Builtins, Next: Pragmas, Prev: Other Builtins, Up: C Extensions
-
-Built-in Functions Specific to Particular Target Machines
-=========================================================
-
- On some target machines, GCC supports many built-in functions
-specific to those machines. Generally these generate calls to specific
-machine instructions, but allow the compiler to schedule those calls.
-
-* Menu:
-
-* X86 Built-in Functions::
-* PowerPC AltiVec Built-in Functions::
-
projects / msp430-gcc.git / blobdiff