This is
/es/build/frv-050408/1/frv550-uclinux/X-tools-build/gcc/doc/gcc.info,
produced by makeinfo version 4.0 from
/es/build/frv-050408/1/frv550-uclinux/sources/tools-src/gcc/doc/gcc.texi.

START-INFO-DIR-ENTRY
* usegcc: (usegcc).			Using the GNU C compiler.
END-INFO-DIR-ENTRY

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 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.2 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.
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

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

_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

    `C'
          Specifies constant that can be easily constructed in SSE
          register without loading it from memory.

    `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

_Intel IA-64--`ia64.h'_

    `a'
          General register `r0' to `r3' for `addl' instruction

    `b'
          Branch register

    `c'
          Predicate register (`c' as in "conditional")

    `d'
          Application register residing in M-unit

    `e'
          Application register residing in I-unit

    `f'
          Floating-point register

    `m'
          Memory operand.  Remember that `m' allows postincrement and
          postdecrement which require printing with `%Pn' on IA-64.
          Use `S' to disallow postincrement and postdecrement.

    `G'
          Floating-point constant 0.0 or 1.0

    `I'
          14-bit signed integer constant

    `J'
          22-bit signed integer constant

    `K'
          8-bit signed integer constant for logical instructions

    `L'
          8-bit adjusted signed integer constant for compare pseudo-ops

    `M'
          6-bit unsigned integer constant for shift counts

    `N'
          9-bit signed integer constant for load and store
          postincrements

    `O'
          The constant zero

    `P'
          0 or -1 for `dep' instruction

    `Q'
          Non-volatile memory for floating-point loads and stores

    `R'
          Integer constant in the range 1 to 4 for `shladd' instruction

    `S'
          Memory operand except postincrement and postdecrement

_FRV--`frv.h'_

    `a'
          Register in the class `ACC_REGS' (`acc0' to `acc7').

    `b'
          Register in the class `EVEN_ACC_REGS' (`acc0' to `acc7').

    `c'
          Register in the class `CC_REGS' (`fcc0' to `fcc3' and `icc0'
          to `icc3').

    `d'
          Register in the class `GPR_REGS' (`gr0' to `gr63').

    `e'
          Register in the class `EVEN_REGS' (`gr0' to `gr63').  Odd
          registers are excluded not in the class but through the use
          of a machine mode larger than 4 bytes.

    `f'
          Register in the class `FPR_REGS' (`fr0' to `fr63').

    `h'
          Register in the class `FEVEN_REGS' (`fr0' to `fr63').  Odd
          registers are excluded not in the class but through the use
          of a machine mode larger than 4 bytes.

    `l'
          Register in the class `LR_REG' (the `lr' register).

    `q'
          Register in the class `QUAD_REGS' (`gr2' to `gr63').
          Register numbers not divisible by 4 are excluded not in the
          class but through the use of a machine mode larger than 8
          bytes.

    `t'
          Register in the class `ICC_REGS' (`icc0' to `icc3').

    `u'
          Register in the class `FCC_REGS' (`fcc0' to `fcc3').

    `v'
          Register in the class `ICR_REGS' (`cc4' to `cc7').

    `w'
          Register in the class `FCR_REGS' (`cc0' to `cc3').

    `x'
          Register in the class `QUAD_FPR_REGS' (`fr0' to `fr63').
          Register numbers not divisible by 4 are excluded not in the
          class but through the use of a machine mode larger than 8
          bytes.

    `z'
          Register in the class `SPR_REGS' (`lcr' and `lr').

    `A'
          Register in the class `QUAD_ACC_REGS' (`acc0' to `acc7').

    `B'
          Register in the class `ACCG_REGS' (`accg0' to `accg7').

    `C'
          Register in the class `CR_REGS' (`cc0' to `cc7').

    `G'
          Floating point constant zero

    `I'
          6-bit signed integer constant

    `J'
          10-bit signed integer constant

    `L'
          16-bit signed integer constant

    `M'
          16-bit unsigned integer constant

    `N'
          12-bit signed integer constant that is negative--i.e. in the
          range of -2048 to -1

    `O'
          Constant zero

    `P'
          12-bit signed integer constant that is greater than
          zero--i.e. in the range of 1 to 2047.

_IP2K--`ip2k.h'_

    `a'
          `DP' or `IP' registers (general address)

    `f'
          `IP' register

    `j'
          `IPL' register

    `k'
          `IPH' register

    `b'
          `DP' register

    `y'
          `DPH' register

    `z'
          `DPL' register

    `q'
          `SP' register

    `c'
          `DP' or `SP' registers (offsettable address)

    `d'
          Non-pointer registers (not `SP', `DP', `IP')

    `u'
          Non-SP registers (everything except `SP')

    `R'
          Indirect thru `IP' - Avoid this except for `QImode', since we
          can't access extra bytes

    `S'
          Indirect thru `SP' or `DP' with short displacement (0..127)

    `T'
          Data-section immediate value

    `I'
          Integers from -255 to -1

    `J'
          Integers from 0 to 7--valid bit number in a register

    `K'
          Integers from 0 to 127--valid displacement for addressing mode

    `L'
          Integers from 1 to 127

    `M'
          Integer -1

    `N'
          Integer 1

    `O'
          Zero

    `P'
          Integers from 0 to 255

_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

    `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

_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 on the SPARC-V8 architecture and
          lower floating-point register on the SPARC-V9 architecture.

    `e'
          Floating-point register. It is equivalent to `f' on the
          SPARC-V8 architecture and contains both lower and upper
          floating-point registers on the SPARC-V9 architecture.

    `c'
          Floating-point condition code register.

    `d'
          Lower floating-point register. It is only valid on the
          SPARC-V9 architecture when the Visual Instruction Set is
          available.

    `b'
          Floating-point register. It is only valid on the SPARC-V9
          architecture when the Visual Instruction Set is available.

    `h'
          64-bit global or out register for the SPARC-V8+ architecture.

    `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'

    `O'
          The constant 4096

    `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 a 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.

    `Z'
          The constant 0.

_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


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.


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::


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.


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.


File: gcc.info,  Node: Alternate Keywords,  Next: Incomplete Enums,  Prev: Explicit Reg Vars,  Up: C Extensions

Alternate Keywords
==================

   `-ansi' and the various `-std' options disable certain keywords.
This causes trouble when you want to use GNU C extensions, or a
general-purpose header file that should be usable by all programs,
including ISO C programs.  The keywords `asm', `typeof' and `inline'
are not available in programs compiled with `-ansi' or `-std' (although
`inline' can be used in a program compiled with `-std=c99').  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', 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.


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++.


File: gcc.info,  Node: Function Names,  Next: Return Address,  Prev: Incomplete Enums,  Up: C Extensions

Function Names as Strings
=========================

   GCC provides three magic variables which hold the name of the current
function, as a string.  The first of these is `__func__', which is part
of the C99 standard:

     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.

   `__FUNCTION__' is another name for `__func__'.  Older versions of
GCC recognize only this name.  However, it is not standardized.  For
maximum portability, we recommend you use `__func__', but provide a
fallback definition with the preprocessor:

     #if __STDC_VERSION__ < 199901L
     # if __GNUC__ >= 2
     #  define __func__ __FUNCTION__
     # else
     #  define __func__ "<unknown>"
     # endif
     #endif

   In C, `__PRETTY_FUNCTION__' is yet another name for `__func__'.
However, in C++, `__PRETTY_FUNCTION__' contains the type signature of
the function as well as its bare name.  For example, this program:

     extern "C" {
     extern int printf (char *, ...);
     }
     
     class a {
      public:
       void 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__ = void a::sub(int)

   These identifiers are not preprocessor macros.  In GCC 3.3 and
earlier, in C only, `__FUNCTION__' and `__PRETTY_FUNCTION__' were
treated as string literals; they could be used to initialize `char'
arrays, and they could be concatenated with other string literals.  GCC
3.4 and later treat them as variables, like `__func__'.  In C++,
`__FUNCTION__' and `__PRETTY_FUNCTION__' have always been variables.


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. When
     inlining the expected behavior is that the function will return
     the address of the function that will be returned to.  To work
     around this behavior use the `noinline' function attribute.

     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.


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.

   Specifying a combination that is not valid for the current
architecture will cause gcc to synthesize the instructions using a
narrower mode.  For example, if you specify a variable of type `V4SI'
and your architecture does not allow for this specific SIMD type, gcc
will produce code that uses 4 `SIs'.

   The types defined in this manner can be used with a subset of normal
C operations.  Currently, gcc will allow using the following operators
on these types: `+, -, *, /, unary minus'.

   The operations behave like C++ `valarrays'.  Addition is defined as
the addition of the corresponding elements of the operands.  For
example, in the code below, each of the 4 elements in A will be added
to the corresponding 4 elements in B and the resulting vector will be
stored in C.

     typedef int v4si __attribute__ ((mode(V4SI)));
     
     v4si a, b, c;
     
     c = a + b;

   Subtraction, multiplication, and division operate in a similar
manner.  Likewise, the result of using the unary minus operator on a
vector type is a vector whose elements are the negative value of the
corresponding elements in the operand.

   You can declare variables and use them in function calls and
returns, as well as in assignments and some casts.  You can specify a
vector type as a return type for a function.  Vector types can also be
used as function arguments.  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).

   You cannot operate between vectors of different lengths or different
signedness without a cast.

   A port that supports hardware vector operations, usually 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);
     }

