path: root/gcc-1.40/gcc.texinfo

\input texinfo  @c -*-texinfo-*-

@settitle Using and Porting GNU CC
@setfilename gcc.info

@ifinfo
This file documents the use and the internals of the GNU compiler.

Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License'' and ``Protect Your
Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the
original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``GNU General Public License'' and
``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission
notice may be included in translations approved by the Free Software
Foundation instead of in the original English.
@end ifinfo

@setchapternewpage odd

@titlepage
@center @titlefont{Using and Porting GNU CC}
@sp 2
@center Richard M. Stallman
@sp 3
@center last updated 3 June 1991
@sp 1
@center for version 1.40
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License'' and ``Protect Your
Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the
original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``GNU General Public License'' and
``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission
notice may be included in translations approved by the Free Software
Foundation instead of in the original English.
@end titlepage
@page

@ifinfo
@node Top, Copying,, (DIR)
@ichapter Introduction

This manual documents how to run, install and port the GNU C compiler, as
well as its new features and incompatibilities, and how to report bugs.

@end ifinfo
@menu
* Copying::         GNU General Public License says
                     how you can copy and share GNU CC.
* Contributors::    People who have contributed to GNU CC.
* Boycott::	    Protect your freedom---fight ``look and feel''.
* Options::         Command options supported by @samp{gcc}.
* Installation::    How to configure, compile and install GNU CC.
* Trouble::         If you have trouble installing GNU CC.
* Service::         How to find suppliers of services for GNU CC users.
* Incompatibilities:: Incompatibilities of GNU CC.
* Extensions::      GNU extensions to the C language.
* Bugs::            How to report bugs (if you want to get them fixed).
* Portability::     Goals of GNU CC's portability features.
* Interface::       Function-call interface of GNU CC output.
* Passes::          Order of passes, what they do, and what each file is for.
* RTL::             The intermediate representation that most passes work on.
* Machine Desc::    How to write machine description instruction patterns.
* Machine Macros::  How to write the machine description C macros.
* Config::          Writing the @file{xm-@var{machine}.h} file.
@end menu

@node Copying, Contributors, Top, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 1, February 1989

@display
Copyright @copyright{} 1989 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The license agreements of most software companies try to keep users
at the mercy of those companies.  By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS
@end iftex
@ifinfo
@center TERMS AND CONDITIONS
@end ifinfo

@enumerate
@item
This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License.  The
``Program'', below, refers to any such program or work, and a ``work based
on the Program'' means either the Program or any work containing the
Program or a portion of it, either verbatim or with modifications.  Each
licensee is addressed as ``you''.

@item
You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
General Public License and to the absence of any warranty; and give any
other recipients of the Program a copy of this General Public License
along with the Program.  You may charge a fee for the physical act of
transferring a copy.

@item
You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
1 above, provided that you also do the following:

@itemize @bullet
@item
cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and

@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
with or without modifications, to be licensed at no charge to all
third parties under the terms of this General Public License (except
that you may choose to grant warranty protection to some or all
third parties, at your option).

@item
If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
announcement including an appropriate copyright notice and a notice
that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.

@item
You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
@end itemize

Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.

@item
You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms of
Paragraphs 1 and 2 above provided that you also do one of the following:

@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
@end itemize

Source code for a work means the preferred form of the work for making
modifications to it.  For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.

@item
You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
the Program is void, and will automatically terminate your rights to use
the Program under this License.  However, parties who have received
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.

@item
By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions.  You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of the license which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
@end smallexample

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items---whatever suits your
program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here a sample; alter the names:

@example
Yoyodyne, Inc., hereby disclaims all copyright interest in the
program `Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end example

That's all there is to it!

@node Contributors, Boycott, Copying, Top
@unnumbered Contributors to GNU CC

In addition to Richard Stallman, several people have written parts
of GNU CC.

@itemize @bullet
@item
The idea of using RTL and some of the optimization ideas came from the
U. of Arizona Portable Optimizer, written by Jack Davidson and
Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
857-866.

@item
Paul Rubin wrote most of the preprocessor.

@item
Leonard Tower wrote parts of the parser, RTL generator, and RTL
definitions, and of the Vax machine description.

@item
Ted Lemon wrote parts of the RTL reader and printer.

@item
Jim Wilson implemented loop strength reduction and some other
loop optimizations.

@item
Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
the support for the Sony NEWS machine.

@item
Charles LaBrec contributed the support for the Integrated Solutions
68020 system.

@item
Michael Tiemann of MCC wrote most of the description of the National
Semiconductor 32000 series cpu.  He also wrote the code for inline
function integration and for the SPARC cpu and Motorola 88000 cpu
and part of the Sun FPA support.

@item
Jan Stein of the Chalmers Computer Society provided support for
Genix, as well as part of the 32000 machine description.

@item
Randy Smith finished the Sun FPA support.

@item
Robert Brown implemented the support for Encore 32000 systems.

@item
David Kashtan of SRI adapted GNU CC to the Vomit-Making System.

@item
Alex Crain provided changes for the 3b1.

@item
Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
the 9000 series 300.

@item
William Schelter did most of the work on the Intel 80386 support.

@item
Christopher Smith did the port for Convex machines.

@item
Paul Petersen wrote the machine description for the Alliant FX/8.

@item
Alain Lichnewsky ported GNU CC to the Mips cpu.

@item
Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.

@item
Jonathan Stone wrote the machine description for the Pyramid computer.
@end itemize

@node Boycott, Options, Contributors, Top
@chapter Protect Your Freedom---Fight ``Look And Feel''

@quotation
@i{This section is a political message from the League for Programming
Freedom to the users of GNU CC.  It is included here as an expression
of support for the League on the part of the Free Software Foundation
and Richard Stallman.}
@end quotation

Ashton-Tate, Apple, Lotus and Xerox are trying to create a new form of
legal monopoly: a copyright on a class of user interfaces.  These
monopolies would cause serious problems for users and developers of
computer software and systems.

Until a few years ago, the law seemed clear: no one could restrict
others from using a user interface; programmers were free to implement
any interface they chose.  Imitating interfaces, sometimes with changes,
was standard practice in the computer field.  The interfaces we know
evolved gradually in this way; for example, the Macintosh user interface
drew ideas from the Xerox interface, which in turn drew on work done at
Stanford and SRI.  1-2-3 imitated VisiCalc, and dBase imitated a
database program from JPL.

Most computer companies, and nearly all computer users, were happy with
this state of affairs.  The companies that are suing say it does not
offer ``enough incentive'' to develop their products, but they must have
considered it ``enough'' when they made their decision to do so.  It
seems they are not satisfied with the opportunity to continue to compete
in the marketplace---not even with a head start.

If Xerox, Lotus, Apple and Ashton-Tate are permitted to make law through
the courts, the precedent will hobble the software industry:

@itemize @bullet
@item
Gratuitous incompatibilities will burden users.  Imagine if each
car manufacturer had to arrange the pedals in a different order.

@item
Software will become and remain more expensive.  Users will be
``locked in'' to proprietary interfaces, for which there is no real
competition.

@item
Large companies have an unfair advantage wherever lawsuits become
commonplace.  Since they can easily afford to sue, they can intimidate
small companies with threats even when they don't really have a case.

@item
User interface improvements will come slower, since incremental
evolution through creative imitation will no longer be permitted.

@item
Even Apple, etc., will find it harder to make improvements if
they can no longer adapt the good ideas that others introduce, for
fear of weakening their own legal positions.  Some users suggest that
this stagnation may already have started.

@item
If you use GNU software, you might find it of some concern that user
interface copyright will make it hard for the Free Software Foundation
to develop programs compatible with the interfaces that you already
know.
@end itemize

To protect our freedom from lawsuits like these, a group of programmers
and users have formed a new grass-roots political organization, the
League for Programming Freedom.

The purpose of the League is to oppose new monopolistic practices such
as user-interface copyright and software patents; it calls for a return
to the legal policies of the recent past, in which these practices were
not allowed.  The League is not concerned with free software as an
issue, and not affiliated with the Free Software Foundation.

The League's membership rolls include John McCarthy, inventor of Lisp,
Marvin Minsky, founder of the Artificial Intelligence lab, Guy L.
Steele, Jr., author of well-known books on Lisp and C, as well as
Richard Stallman, the developer of GNU CC.  Please join and add your
name to the list.  Membership dues in the League are $42 per year for
programmers, managers and professionals; $10.50 for students; $21 for
others.

The League needs both activist members and members who only pay their
dues.

To join, or for more information, phone (617) 492-0023 or write to:

@example
League for Programming Freedom
1 Kendall Square #143
P.O. Box 9171
Cambridge, MA 02139       league@@prep.ai.mit.edu
@end example

Here are some suggestions from the League for how you can protect your
freedom to write programs:

@itemize @bullet
@item
Don't buy from Xerox, Lotus, Apple or Ashton-Tate.  Buy from their
competitors or from the defendants they are suing.

@item
Don't develop software to work with the systems made by these companies.

@item
Port your existing software to competing systems, so that you encourage
users to switch.

@item
Write letters to company presidents to let them know their conduct
is unacceptable.

@item
Tell your friends and colleagues about this issue and how it threatens
to ruin the computer industry.

@item
Above all, don't work for the look-and-feel plaintiffs, and don't
accept contracts from them.

@item
Write to Congress to explain the importance of this issue.

@example
House Subcommittee on Intellectual Property
2137 Rayburn Bldg
Washington, DC 20515

Senate Subcommittee on Patents, Trademarks and Copyrights
United States Senate
Washington, DC 20510
@end example
@end itemize

Express your opinion!  You can make a difference.

@node Options, Installation, Boycott, Top
@chapter GNU CC Command Options

The GNU C compiler uses a command syntax much like the Unix C compiler.
The @code{gcc} program accepts options and file names as operands.
Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
very different from @w{@samp{-d -r}}.

When you invoke GNU CC, it normally does preprocessing, compilation,
assembly and linking.  File names which end in @samp{.c} are taken as C
source to be preprocessed and compiled; file names ending in @samp{.i}
are taken as preprocessor output to be compiled; compiler output files
plus any input files with names ending in @samp{.s} are assembled; then
the resulting object files, plus any other input files, are linked
together to produce an executable.

Command options allow you to stop this process at an intermediate stage.
For example, the @samp{-c} option says not to run the linker.  Then the
output consists of object files output by the assembler.

Other command options are passed on to one stage of processing.  Some
options control the preprocessor and others the compiler itself.  Yet
other options control the assembler and linker; these are not documented
here, but you rarely need to use any of them.

Here are the options to control the overall compilation process, including
those that say whether to link, whether to assemble, and so on.

@table @samp
@item -o @var{file}
Place output in file @var{file}.  This applies regardless to whatever
sort of output is being produced, whether it be an executable file,
an object file, an assembler file or preprocessed C code.

If @samp{-o} is not specified, the default is to put an executable file
in @file{a.out}, the object file @file{@var{source}.c} in
@file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
preprocessed C on standard output.@refill

@item -c
Compile or assemble the source files, but do not link.  Produce object
files with names made by replacing @samp{.c} or @samp{.s} with
@samp{.o} at the end of the input file names.  Do nothing at all for
object files specified as input.

@item -S
Compile into assembler code but do not assemble.  The assembler output
file name is made by replacing @samp{.c} with @samp{.s} at the end of
the input file name.  Do nothing at all for assembler source files or
object files specified as input.

@item -E
Run only the C preprocessor.  Preprocess all the C source files
specified and output the results to standard output.

@item -v
Compiler driver program prints the commands it executes as it runs
the preprocessor, compiler proper, assembler and linker.  Some of
these are directed to print their own version numbers.

@item -pipe
Use pipes rather than temporary files for communication between the
various stages of compilation.  This fails to work on some systems
where the assembler is unable to read from a pipe; but the GNU
assembler has no trouble.

@item -B@var{prefix}
Compiler driver program tries @var{prefix} as a prefix for each
program it tries to run.  These programs are @file{cpp}, @file{cc1},
@file{as} and @file{ld}.

For each subprogram to be run, the compiler driver first tries the
@samp{-B} prefix, if any.  If that name is not found, or if @samp{-B}
was not specified, the driver tries two standard prefixes, which are
@file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}.  If neither of
those results in a file name that is found, the unmodified program
name is searched for using the directories specified in your
@samp{PATH} environment variable.

The run-time support file @file{gnulib} is also searched for using
the @samp{-B} prefix, if needed.  If it is not found there, the two
standard prefixes above are tried, and that is all.  The file is left
out of the link if it is not found by those means.  Most of the time,
on most machines, you can do without it.

You can get a similar result from the environment variable;
@code{GCC_EXEC_PREFIX} if it is defined, its value is used as a prefix
in the same way.  If both the @samp{-B} option and the
@code{GCC_EXEC_PREFIX} variable are present, the @samp{-B} option is
used first and the environment variable value second.

@item -b@var{prefix}
The argument @var{prefix} is used as a second prefix for the compiler
executables and libraries.  This prefix is optional: the compiler tries
each file first with it, then without it.  This prefix follows the
prefix specified with @samp{-B} or the default prefixes.

Thus, @samp{-bvax- -Bcc/} in the presence of environment variable
@code{GCC_EXEC_PREFIX} with definition @file{/u/foo/} causes GNU CC to
try the following file names for the preprocessor executable:

@example
cc/vax-cpp
cc/cpp
/u/foo/vax-cpp
/u/foo/cpp
/usr/local/lib/gcc-vax-cpp
/usr/local/lib/gcc-cpp
/usr/lib/gcc-vax-cpp
/usr/lib/gcc-cpp
@end example
@end table

These options control the details of C compilation itself.

@table @samp
@item -ansi
Support all ANSI standard C programs.

This turns off certain features of GNU C that are incompatible with
ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
keywords, and predefined macros such as @code{unix} and @code{vax}
that identify the type of system you are using.  It also enables the
undesirable and rarely used ANSI trigraph feature.

The alternate keywords @code{__asm__}, @code{__inline__} and
@code{__typeof__} continue to work despite @samp{-ansi}.  You would not
want to use them in an ANSI C program, of course, but it useful to put
them in header files that might be included in compilations done with
@samp{-ansi}.  Alternate predefined macros such as @code{__unix__} and
@code{__vax__} are also available, with or without @samp{-ansi}.

The @samp{-ansi} option does not cause non-ANSI programs to be
rejected gratuitously.  For that, @samp{-pedantic} is required in
addition to @samp{-ansi}.

The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
option is used.  Some header files may notice this macro and refrain
from declaring certain functions or defining certain macros that the
ANSI standard doesn't call for; this is to avoid interfering with any
programs that might use these names for other things.

@item -traditional
Attempt to support some aspects of traditional C compilers.
Specifically:

@itemize @bullet
@item
All @code{extern} declarations take effect globally even if they
are written inside of a function definition.  This includes implicit
declarations of functions.

@item
The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
and @code{volatile} are not recognized.  (You can still use the alternative
keywords such as @code{__typeof__}, @code{__inline__}, and so on.)

@item
Comparisons between pointers and integers are always allowed.

@item
Integer types @code{unsigned short} and @code{unsigned char} promote
to @code{unsigned int}.

@item
Out-of-range floating point literals are not an error.

@item
String ``constants'' are not necessarily constant; they are stored in
writable space, and identical looking constants are allocated
separately.

@item
All automatic variables not declared @code{register} are preserved by
@code{longjmp}.  Ordinarily, GNU C follows ANSI C: automatic variables
not declared @code{volatile} may be clobbered.

@item
In the preprocessor, comments convert to nothing at all, rather than
to a space.  This allows traditional token concatenation.

@item
In the preprocessor, macro arguments are recognized within string
constants in a macro definition (and their values are stringified,
though without additional quote marks, when they appear in such a
context).  The preprocessor always considers a string constant to end
at a newline.

@item
The predefined macro @code{__STDC__} is not defined when you use
@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
which @code{__GNUC__} indicates are not affected by
@samp{-traditional}).  If you need to write header files that work
differently depending on whether @samp{-traditional} is in use, by
testing both of these predefined macros you can distinguish four
situations: GNU C, traditional GNU C, other ANSI C compilers, and
other old C compilers.
@end itemize

@item -O
Optimize.  Optimizing compilation takes somewhat more time, and a lot
more memory for a large function.

Without @samp{-O}, the compiler's goal is to reduce the cost of
compilation and to make debugging produce the expected results.
Statements are independent: if you stop the program with a breakpoint
between statements, you can then assign a new value to any variable or
change the program counter to any other statement in the function and
get exactly the results you would expect from the source code.

Without @samp{-O}, only variables declared @code{register} are
allocated in registers.  The resulting compiled code is a little worse
than produced by PCC without @samp{-O}.

With @samp{-O}, the compiler tries to reduce code size and execution
time.

Some of the @samp{-f} options described below turn specific kinds of
optimization on or off.

@item -g
Produce debugging information in the operating system's native format
(for DBX or SDB).  GDB also can work with this debugging information.

Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
@samp{-O}.  The shortcuts taken by optimized code may occasionally
produce surprising results: some variables you declared may not exist
at all; flow of control may briefly move where you did not expect it;
some statements may not be executed because they compute constant
results or their values were already at hand; some statements may
execute in different places because they were moved out of loops.
Nevertheless it proves possible to debug optimized output.  This makes
it reasonable to use the optimizer for programs that might have bugs.

@item -gg
Produce debugging information in the old GDB format.  This is obsolete.

@item -w
Inhibit all warning messages.

@item -W
Print extra warning messages for these events:

@itemize @bullet
@item
An automatic variable is used without first being initialized.

These warnings are possible only in optimizing compilation,
because they require data flow information that is computed only
when optimizing.  If you don't specify @samp{-O}, you simply won't
get these warnings.

These warnings occur only for variables that are candidates for
register allocation.  Therefore, they do not occur for a variable that
is declared @code{volatile}, or whose address is taken, or whose size
is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
structures, unions or arrays, even when they are in registers.

Note that there may be no warning about a variable that is used only
to compute a value that itself is never used, because such
computations may be deleted by data flow analysis before the warnings
are printed.

These warnings are made optional because GNU CC is not smart
enough to see all the reasons why the code might be correct
despite appearing to have an error.  Here is one example of how
this can happen:

@example
@{
  int x;
  switch (y)
    @{
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    @}
  foo (x);
@}
@end example

@noindent
If the value of @code{y} is always 1, 2 or 3, then @code{x} is
always initialized, but GNU CC doesn't know this.  Here is
another common case:

@example
@{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  @dots{}
  if (change_y) y = save_y;
@}
@end example

@noindent
This has no bug because @code{save_y} is used only if it is set.

Some spurious warnings can be avoided if you declare as
@code{volatile} all the functions you use that never return.
@xref{Function Attributes}.

@item
A nonvolatile automatic variable might be changed by a call to
@code{longjmp}.  These warnings as well are possible only in
optimizing compilation.

The compiler sees only the calls to @code{setjmp}.  It cannot know
where @code{longjmp} will be called; in fact, a signal handler could
call it at any point in the code.  As a result, you may get a warning
even when there is in fact no problem because @code{longjmp} cannot
in fact be called at the place which would cause a problem.

@item
A function can return either with or without a value.  (Falling
off the end of the function body is considered returning without
a value.)  For example, this function would evoke such a
warning:

@example
foo (a)
@{
  if (a > 0)
    return a;
@}
@end example

Spurious warnings can occur because GNU CC does not realize that
certain functions (including @code{abort} and @code{longjmp})
will never return.

@item
An expression-statement contains no side effects.
@end itemize

In the future, other useful warnings may also be enabled by this
option.

@item -Wimplicit
Warn whenever a function is implicitly declared.

@item -Wreturn-type
Warn whenever a function is defined with a return-type that defaults
to @code{int}.  Also warn about any @code{return} statement with no
return-value in a function whose return-type is not @code{void}.

@item -Wunused
Warn whenever a local variable is unused aside from its declaration,
whenever a function is declared static but never defined, and whenever
a statement computes a result that is explicitly not used.

@item -Wswitch
Warn whenever a @code{switch} statement has an index of enumeral type
and lacks a @code{case} for one or more of the named codes of that
enumeration.  (The presence of a @code{default} label prevents this
warning.)  @code{case} labels outside the enumeration range also
provoke warnings when this option is used.

@item -Wcomment
Warn whenever a comment-start sequence @samp{/*} appears in a comment.

@item -Wtrigraphs
Warn if any trigraphs are encountered (assuming they are enabled).

@item -Wall
All of the above @samp{-W} options combined.  These are all the
options which pertain to usage that we recommend avoiding and that we
believe is easy to avoid, even in conjunction with macros.

The other @samp{-W@dots{}} options below are not implied by @samp{-Wall}
because certain kinds of useful macros are almost impossible to write
without causing those warnings.

@item -Wshadow
Warn whenever a local variable shadows another local variable.

@item -Wid-clash-@var{len}
Warn whenever two distinct identifiers match in the first @var{len}
characters.  This may help you prepare a program that will compile
with certain obsolete, brain-damaged compilers.

@item -Wpointer-arith
Warn about anything that depends on the ``size of'' a function type or
of @code{void}.  GNU C assigns these types a size of 1, for
convenience in calculations with @code{void *} pointers and pointers
to functions.

@item -Wcast-qual
Warn whenever a pointer is cast so as to remove a type qualifier from
the target type.  For example, warn if a @code{const char *} is cast
to an ordinary @code{char *}.

@item -Wwrite-strings
Give string constants the type @code{const char[@var{length}]} so that
copying the address of one into a non-@code{const} @code{char *}
pointer will get a warning.  These warnings will help you find at
compile time code that can try to write into a string constant, but
only if you have been very careful about using @code{const} in
declarations and prototypes.  Otherwise, it will just be a nuisance;
this is why we did not make @samp{-Wall} request these warnings.

@item -p
Generate extra code to write profile information suitable for the
analysis program @code{prof}.

@item -pg
Generate extra code to write profile information suitable for the
analysis program @code{gprof}.

@item -a
Generate extra code to write profile information for basic blocks, which
will record the number of times each basic block is executed.  This data
could be analyzed by a program like @code{tcov}.  Note, however, that
the format of the data is not what @code{tcov} expects.  Eventually GNU
@code{gprof} should be extended to process this data.

@item -l@var{library}
Search a standard list of directories for a library named
@var{library}, which is actually a file named
@file{lib@var{library}.a}.  The linker uses this file as if it
had been specified precisely by name.

The directories searched include several standard system directories
plus any that you specify with @samp{-L}.

Normally the files found this way are library files---archive files
whose members are object files.  The linker handles an archive file by
scanning through it for members which define symbols that have so far
been referenced but not defined.  But if the file that is found is an
ordinary object file, it is linked in the usual fashion.  The only
difference between using an @samp{-l} option and specifying a file name
is that @samp{-l} searches several directories.

@item -L@var{dir}
Add directory @var{dir} to the list of directories to be searched
for @samp{-l}.

@item -nostdlib
Don't use the standard system libraries and startup files when linking.
Only the files you specify will be passed to the linker.

@item -m@var{machinespec}
Machine-dependent option specifying something about the type of target
machine.  These options are defined by the macro
@code{TARGET_SWITCHES} in the machine description.  The default for
the options is also defined by that macro, which enables you to change
the defaults.@refill

These are the @samp{-m} options defined in the 68000 machine
description:

@table @samp
@item -m68020
@itemx -mc68020
Generate output for a 68020 (rather than a 68000).  This is the
default if you use the unmodified sources.

@item -m68000
@item -mc68000
Generate output for a 68000 (rather than a 68020).

@item -m68881
Generate output containing 68881 instructions for floating point.
This is the default if you use the unmodified sources.

@item -mfpa
Generate output containing Sun FPA instructions for floating point.

@item -msoft-float
Generate output containing library calls for floating point.

@item -mshort
Consider type @code{int} to be 16 bits wide, like @code{short int}.

@item -mnobitfield
Do not use the bit-field instructions.  @samp{-m68000} implies
@samp{-mnobitfield}.

@item -mbitfield
Do use the bit-field instructions.  @samp{-m68020} implies
@samp{-mbitfield}.  This is the default if you use the unmodified
sources.

@item -mrtd
Use a different function-calling convention, in which functions
that take a fixed number of arguments return with the @code{rtd}
instruction, which pops their arguments while returning.  This
saves one instruction in the caller since there is no need to pop
the arguments there.

This calling convention is incompatible with the one normally
used on Unix, so you cannot use it if you need to call libraries
compiled with the Unix compiler.

Also, you must provide function prototypes for all functions that
take variable numbers of arguments (including @code{printf});
otherwise incorrect code will be generated for calls to those
functions.

In addition, seriously incorrect code will result if you call a
function with too many arguments.  (Normally, extra arguments are
harmlessly ignored.)

The @code{rtd} instruction is supported by the 68010 and 68020
processors, but not by the 68000.
@end table

These @samp{-m} options are defined in the Vax machine description:

@table @samp
@item -munix
Do not output certain jump instructions (@code{aobleq} and so on)
that the Unix assembler for the Vax cannot handle across long
ranges.

@item -mgnu
Do output those jump instructions, on the assumption that you
will assemble with the GNU assembler.

@item -mg
Output code for g-format floating point numbers instead of d-format.
@end table

These @samp{-m} switches are supported on the Sparc:

@table @samp
@item -mfpu
Generate output containing floating point instructions.  This is the
default if you use the unmodified sources.

@ignore
@item -msoft-float
Generate output containing library calls for floating point.

@end ignore
@item -mno-epilogue
Generate separate return instructions for @code{return} statements.
This has both advantages and disadvantages; I don't recall what they
are.
@end table

These @samp{-m} options are defined in the Convex machine description:

@table @samp
@item -mc1
Generate output for a C1.  This is the default when the compiler is
configured for a C1.

@item -mc2
Generate output for a C2.  This is the default when the compiler is
configured for a C2.

@item -margcount
Generate code which puts an argument count in the word preceding each
argument list.  Some nonportable Convex and Vax programs need this
word.  (Debuggers don't; this info is in the symbol table.)

@item -mnoargcount
Omit the argument count word.  This is the default if you use the
unmodified sources.
@end table

@item -f@var{flag}
Specify machine-independent flags.  Most flags have both positive and
negative forms; the negative form of @samp{-ffoo} would be
@samp{-fno-foo}.  In the table below, only one of the forms is
listed---the one which is not the default.  You can figure out the
other form by either removing @samp{no-} or adding it.

@table @samp
@item -fpcc-struct-return
Use the same convention for returning @code{struct} and @code{union}
values that is used by the usual C compiler on your system.  This
convention is less efficient for small structures, and on many
machines it fails to be reentrant; but it has the advantage of
allowing intercallability between GCC-compiled code and PCC-compiled
code.

@item -ffloat-store
Do not store floating-point variables in registers.  This
prevents undesirable excess precision on machines such as the
68000 where the floating registers (of the 68881) keep more
precision than a @code{double} is supposed to have.

For most programs, the excess precision does only good, but a few
programs rely on the precise definition of IEEE floating point.
Use @samp{-ffloat-store} for such programs.

@item -fno-asm
Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
keyword.  These words may then be used as identifiers.  You can
use @code{__asm__}, @code{__inline__} and @code{__typeof__} instead.

@item -fno-defer-pop
Always pop the arguments to each function call as soon as that
function returns.  Normally the compiler (when optimizing) lets
arguments accumulate on the stack for several function calls and
pops them all at once.

@item -fstrength-reduce
Perform the optimizations of loop strength reduction and
elimination of iteration variables.

@item -fcombine-regs
Allow the combine pass to combine an instruction that copies one
register into another.  This might or might not produce better
code when used in addition to @samp{-O}.  I am interested in
hearing about the difference this makes.

@item -fforce-mem
Force memory operands to be copied into registers before doing
arithmetic on them.  This may produce better code by making all
memory references potential common subexpressions.  When they are
not common subexpressions, instruction combination should
eliminate the separate register-load.  I am interested in hearing
about the difference this makes.

@item -fforce-addr
Force memory address constants to be copied into registers before
doing arithmetic on them.  This may produce better code just as
@samp{-fforce-mem} may.  I am interested in hearing about the
difference this makes.

@item -fomit-frame-pointer
Don't keep the frame pointer in a register for functions that
don't need one.  This avoids the instructions to save, set up and
restore frame pointers; it also makes an extra register available
in many functions.  @strong{It also makes debugging impossible.}

On some machines, such as the Vax, this flag has no effect,
because the standard calling sequence automatically handles the
frame pointer and nothing is saved by pretending it doesn't
exist.  The machine-description macro
@code{FRAME_POINTER_REQUIRED} controls whether a target machine
supports this flag.  @xref{Registers}.@refill

@item -finline-functions
Integrate all simple functions into their callers.  The compiler
heuristically decides which functions are simple enough to be
worth integrating in this way.

If all calls to a given function are integrated, and the function
is declared @code{static}, then the function is normally not
output as assembler code in its own right.

@item -fcaller-saves
Enable values to be allocated in registers that will be clobbered by
function calls, by emitting extra instructions to save and restore the
registers around such calls.  Such allocation is done only when it
seems to result in better code than would otherwise be produced.

This option is enabled by default on certain machines, usually those
which have no call-preserved registers to use instead.

@item -fkeep-inline-functions
Even if all calls to a given function are integrated, and the
function is declared @code{static}, nevertheless output a
separate run-time callable version of the function.

@item -fwritable-strings
Store string constants in the writable data segment and don't uniquize
them.  This is for compatibility with old programs which assume they can
write into string constants.  @samp{-traditional} also has this effect.

Writing into string constants is a very bad idea; ``constants'' should
be constant.

@item -fcond-mismatch
Allow conditional expressions with mismatched types in the second and
third arguments.  The value of such an expression is void.

@item -fno-function-cse
Do not put function addresses in registers; make each instruction
that calls a constant function contain the function's address
explicitly.

This option results in less efficient code, but some strange
hacks that alter the assembler output may be confused by the
optimizations performed when this option is not used.

@item -fvolatile
Consider all memory references through pointers to be volatile.

@item -fshared-data
Requests that the data and non-@code{const} variables of this
compilation be shared data rather than private data.  The distinction
makes sense only on certain operating systems, where shared data is
shared between processes running the same program, while private data
exists in one copy per process.

@item -funsigned-char
Let the type @code{char} be the unsigned, like @code{unsigned char}.

Each kind of machine has a default for what @code{char} should
be.  It is either like @code{unsigned char} by default or like
@code{signed char} by default.  (Actually, at present, the
default is always signed.)

The type @code{char} is always a distinct type from either
@code{signed char} or @code{unsigned char}, even though its
behavior is always just like one of those two.

Note that this is equivalent to @samp{-fno-signed-char}, which is the
negative form of @samp{-fsigned-char}.

@item -fsigned-char
Let the type @code{char} be signed, like @code{signed char}.

Note that this is equivalent to @samp{-fno-unsigned-char}, which is
the negative form of @samp{-funsigned-char}.

@item -fdelayed-branch
If supported for the target machine, attempt to reorder instructions
to exploit instruction slots available after delayed branch
instructions.

@item -ffixed-@var{reg}
Treat the register named @var{reg} as a fixed register; generated
code should never refer to it (except perhaps as a stack pointer,
frame pointer or in some other fixed role).

@var{reg} must be the name of a register.  The register names
accepted are machine-specific and are defined in the
@code{REGISTER_NAMES} macro in the machine description macro
file.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-used-@var{reg}
Treat the register named @var{reg} as an allocatable register
that is clobbered by function calls.  It may be allocated for
temporaries or variables that do not live across a call.
Functions compiled this way will not save and restore the
register @var{reg}.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-saved-@var{reg}
Treat the register named @var{reg} as an allocatable register
saved by functions.  It may be allocated even for temporaries or
variables that live across a call.  Functions compiled this way
will save and restore the register @var{reg} if they use it.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

A different sort of disaster will result from the use of this
flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a
three-way choice.
@end table

@item -d@var{letters}
Says to make debugging dumps at times specified by @var{letters}.
Here are the possible letters:

@table @samp
@item r
Dump after RTL generation.
@item j
Dump after first jump optimization.
@item s
Dump after CSE (including the jump optimization that sometimes
follows CSE).
@item L
Dump after loop optimization.
@item f
Dump after flow analysis.
@item c
Dump after instruction combination.
@item l
Dump after local register allocation.
@item g
Dump after global register allocation.
@item d
Dump after delayed branch scheduling.
@item J
Dump after last jump optimization.
@item m
Print statistics on memory usage, at the end of the run.
@end table

@item -pedantic
Issue all the warnings demanded by strict ANSI standard C; reject
all programs that use forbidden extensions.

Valid ANSI standard C programs should compile properly with or without
this option (though a rare few will require @samp{-ansi}).  However,
without this option, certain GNU extensions and traditional C features
are supported as well.  With this option, they are rejected.  There is
no reason to @i{use} this option; it exists only to satisfy pedants.

@samp{-pedantic} does not cause warning messages for use of the
alternate keywords whose names begin and end with @samp{__}.
@xref{Alternate Keywords}.

@item -static
On Suns running version 4, this prevents linking with the shared
libraries.  (@samp{-g} has the same effect.)
@end table

These options control the C preprocessor, which is run on each C source
file before actual compilation.  If you use the @samp{-E} option, nothing
is done except C preprocessing.  Some of these options make sense only
together with @samp{-E} because they request preprocessor output that is
not suitable for actual compilation.

@table @samp
@item -C
Tell the preprocessor not to discard comments.  Used with the
@samp{-E} option.

@item -I@var{dir}
Search directory @var{dir} for include files.

@item -I-
Any directories specified with @samp{-I} options before the @samp{-I-}
option are searched only for the case of @samp{#include "@var{file}"};
they are not searched for @samp{#include <@var{file}>}.

If additional directories are specified with @samp{-I} options after
the @samp{-I-}, these directories are searched for all @samp{#include}
directives.  (Ordinarily @emph{all} @samp{-I} directories are used
this way.)

In addition, the @samp{-I-} option inhibits the use of the current
directory (where the current input file came from) as the first search
directory for @samp{#include "@var{file}"}.  There is no way to override
this effect of @samp{-I-}.  With @samp{-I.} you can specify searching
the directory which was current when the compiler was invoked.  That is
not exactly the same as what the preprocessor does by default, but it is
often satisfactory.

@samp{-I-} does not inhibit the use of the standard system directories
for header files.  Thus, @samp{-I-} and @samp{-nostdinc} are
independent.

@item -i @var{file}
Process @var{file} as input, discarding the resulting output, before
processing the regular input file.  Because the output generated from
@var{file} is discarded, the only effect of @samp{-i @var{file}} is to
make the macros defined in @var{file} available for use in the main
input.

@item -nostdinc
Do not search the standard system directories for header files.  Only
the directories you have specified with @samp{-I} options (and the
current directory, if appropriate) are searched.

Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
directories from the search path except those you specify.

@item -M
Tell the preprocessor to output a rule suitable for @code{make}
describing the dependencies of each object file.  For each source
file, the preprocessor outputs one @code{make}-rule whose target is
the object file name for that source file and whose dependencies are
all the files @samp{#include}d in it.  This rule may be a single line
or may be continued with @samp{\}-newline if it is long.

@samp{-M} implies @samp{-E}.

@item -MM
Like @samp{-M} but the output mentions only the user-header files
included with @samp{#include "@var{file}"}.  System header files
included with @samp{#include <@var{file}>} are omitted.

@samp{-MM} implies @samp{-E}.

@item -D@var{macro}
Define macro @var{macro} with the  string @samp{1} as its definition.

@item -D@var{macro}=@var{defn}
Define macro @var{macro} as @var{defn}.

@item -U@var{macro}
Undefine macro @var{macro}.

@item -trigraphs
Support ANSI C trigraphs.  You don't want to know about this
brain-damage.  The @samp{-ansi} option also has this effect.
@end table

@node Installation, Trouble, Options, Top
@chapter Installing GNU CC

Here is the procedure for installing GNU CC on a Unix system.

@menu
* Other Dir::     Compiling in a separate directory (not where the source is).
* Sun Install::   See below for installation on the Sun.
* 3B1 Install::   See below for installation on the 3B1.
* SCO Install::   See below for installation on SCO System V 3.2.  (Or ESIX.)
* VMS Install::   See below for installation on VMS.
* HPUX Install::  See below for installation on HPUX.
* Tower Install:: See below for installation on an NCR Tower.
@end menu
@iftex
See below for VMS systems, and modified procedures needed on Sun
systems, 3b1 machines and HPUX.  The following section says how to
compile in a separate directory on Unix; here we assume you compile in
the same directory that contains the source files.
@end iftex

@enumerate
@item
Edit @file{Makefile}.  If you are using HPUX, or any form of system V,
you must make a few changes described in comments at the beginning of
the file.  Genix requires changes also, and so does the Pyramid.

@item
On a Sequent system, go to the Berkeley universe.

@item
Choose configuration files.  The easy way to do this is to run the
command file @file{config.gcc} with a single argument, which specifies
the type of machine (and in some cases which operating system).

Here is a list of the possible arguments:

@table @samp
@item vax
Vaxes running BSD.
@item vms
Vaxes running VMS.
@item vax-sysv
Vaxes running system V.
@item i386-sysv
Intel 386 PCs running system V.
@item i386-sysv-gas
Intel 386 PCs running system V, using the GNU assembler and GNU
linker.
@item sequent-i386
Sequent with Intel 386 processors.
@item i386-aix
Intel 386 PCs or PS/2s running AIX.
@item sun2
Sun 2 running system version 2 or 3.
@item sun3
Sun 3 running system version 4, with 68881.
Note there we do not provide a configuration file to use an FPA
by default, because programs that establish signal handlers for
floating point traps inherently cannot work with the FPA.
@item sun3-nfp
Sun 3 running system version 4, without 68881.
@item sun4
Sun 4 running system version 4.  @xref{Incompatibilities},
for calling convention incompatibilities on the Sun 4 (sparc).
@item sun2-os4
Sun 2 running system version 4.
@item sun3-os3
Sun 3 running system version 2 or 3, with 68881.
@item sun3-nfp-os3
Sun 3 running system version 2 or 3, without 68881.
@item sun4-os3
Sun 4 running system version 2 or 3.  @xref{Incompatibilities},
for calling convention incompatibilities on the Sun 4 (sparc).
@item sun386
Sun 386 (``roadrunner'').
@item alliant
Alliant FX/8 computer.  Note that the standard installed C compiler in
Concentrix 5.0 has a bug which prevent it from compiling GNU CC
correctly.  You can patch the compiler bug as follows:

@example
cp /bin/pcc ./pcc
adb -w ./pcc - << EOF
15f6?w 6610
EOF
@end example

Then you must use the @samp{-ip12} option when compiling GNU CC
with the patched compiler, as shown here:

@example
make CC="./pcc -ip12" CFLAGS=-w
@end example

Note also that Alliant's version of DBX does not manage to work with the
output from GNU CC.
@item tahoe
The tahoe computer (running BSD, and using DBX).
@item decstation
The DEC 3100 Mips machine (``pmax'').  Note that GNU CC cannot generate
debugging information in the unusual format used on the Mips.
@item mips-sysv
The Mips computer, RS series, with the System V environment as default.
Note that GNU CC cannot generate debugging information in the unusual
format used on the Mips.
@item mips-bsd43
The Mips computer, RS series, with the BSD 4.3 environment as default.
Note that GNU CC cannot generate debugging information in the unusual
format used on the Mips.
@item mips
The Mips computer, M series.  Note that GNU CC cannot generate debugging
information in the unusual format used on the Mips.
@item iris
Another variant of the Mips computer, the Silicon Graphics Iris 4D.
Note that GNU CC cannot generate debugging information in the unusual
format used on the Mips.
@item convex-c1
Convex C1 computer.  With operating system version 9, use @samp{cc -pcc}
as the compilation command when building stage 1 of GNU CC.
@item convex-c2
Convex C2 computer.  With operating system version 9, use @samp{cc -pcc}
as the compilation command when building stage 1 of GNU CC.
@item pyramid
Pyramid computer.
@item hp9k320
HP 9000 series 300 using HPUX assembler.  Note there is no
support in GNU CC for HP's debugger; thus, @samp{-g} is not
available in this configuration.
@item hp9k320-gas
HP 9000 series 300 using GNU assembler, linker and debugger.
This requires the HP-adapt package, which is available along with
the GNU linker as part of the ``binutils'' distribution.
This is on the GNU CC distribution tape.
@item hp9k320-old
HP 9000 series 300 using HPUX assembler, in operating system versions
older than 6.5.  Note there is no support in GNU CC for HP's debugger;
thus, @samp{-g} is not available in this configuration.
@item hp9k320-bsd
HP 9000 series 300 running BSD.
@item hp9k200-bsd
HP 9000 series 200 running BSD.  Note that the C compiler that comes
with this system cannot compile GNU CC; contact @code{law@@super.org} to
get binaries of GNU CC for bootstrapping.  Additionally, a minor patch
is necessary if you wish to build kernels with GNU CC; contact
@code{law@@super.org} to get a copy of the patch.
@item isi68
ISI 68000 or 68020 system with a 68881.
@item isi68-nfp
ISI 68000 or 68020 system without a 68881.
@item news800
Sony NEWS 68020 system.
@item next
NeXT system.
@item tower
NCR Tower 32 system.
@item altos
Altos 3068.  Note that you must use the GNU assembler, linker and
debugger, with COFF-encapsulation.  Also, you must fix a kernel
bug.  Details in the file @file{ALTOS-README}.
@item 3b1
AT&T 3b1, a.k.a. 7300 PC.  Note that special procedures are needed
to compile GNU CC with this machine's standard C compiler, due to
bugs in that compiler.  @xref{3b1 Install}.  You can bootstrap it
more easily with previous versions of GNU CC if you have them.
@item 3b1-gas
AT&T 3b1 using the GNU assembler.
@item sequent-ns32k
Sequent containing ns32000 processors.
@item encore
Encore ns32000 system.
@item genix
National Semiconductor ns32000 system.
@item 88000
Motorola 88000 processor.  This port is not finished.
@end table

Here we spell out what files need to be set up:

@itemize @bullet
@item
Make a symbolic link named @file{config.h} to the top-level
config file for the machine you are using (@pxref{Config}).  This
file is responsible for defining information about the host
machine.  It includes @file{tm.h}.

The file is located in the subdirectory @file{config}.  Its name
should be @file{xm-@var{machine}.h}, with these exceptions:

@table @file
@item xm-vms.h
for vaxen running VMS.
@item xm-vaxv.h
for vaxen running system V.
@item xm-i386v.h
for Intel 80386's running system V.
@item xm-sun386i.h
for Sun roadrunner running any version of the operating system.
@item xm-hp9k320.h
for the HP 9000 series 300.
@item xm-genix.h
for the ns32000 running Genix
@end table

If your system does not support symbolic links, you might want to
set up @file{config.h} to contain a @samp{#include} command which
refers to the appropriate file.

@item
Make a symbolic link named @file{tm.h} to the machine-description
macro file for your machine.  It should be in the subdirectory
@file{config} and its name should be @file{tm-@var{machine}.h}.

If your system is a 68000, don't use the file @file{tm-m68k.h}
directly.  Instead, use one of these files:

@table @file
@item tm-sun3.h
for Sun 3 machines with 68881.
@item tm-sun3-nfp.h
for Sun 3 machines with no hardware floating point.
@item tm-sun3os3.h
for Sun 3 machines with 68881, running Sunos version 3.
@item tm-sun3os3nf.h
for Sun 3 machines with no hardware floating point, running Sunos
version 3.
@item tm-sun2.h
for Sun 2 machines.
@item tm-3b1.h
for AT&T 3b1 (aka 7300 Unix PC).
@item tm-isi68.h
for Integrated Solutions systems.  This file assumes you
use the GNU assembler.
@item tm-isi68-nfp.h
for Integrated Solutions systems without a 68881.  This file assumes you
use the GNU assembler.
@item tm-news800.h
for Sony NEWS systems.
@item tm-hp9k320.h
for HPUX systems, if you are using GNU CC with the system's
assembler and linker.
@item tm-hp9k320g.h
for HPUX systems, if you are using the GNU assembler, linker and
other utilities.  Not all of the pieces of GNU software needed
for this mode of operation are as yet in distribution; full
instructions will appear here in the future.@refill
@item tm-tower-as.h
for NCR Tower 32 systems, using the standard system assembler.
@end table

For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on
system V, or @file{tm-vms.h} on VMS.@refill

For the Motorola 88000, use @file{tm-m88k.h}.  The support for the
88000 does not currently work; it requires extensive changes which
we hope to reconcile in version 2.

For the 80386, don't use @file{tm-i386.h} directly.  Use
@file{tm-i386v.h} if the target machine is running system V,
@file{tm-i386gas.h} if it is running system V but you are using the
GNU assembler and linker, @file{tm-seq386.h} for a Sequent 386 system,
or @file{tm-compaq.h} for a Compaq, or @file{tm-sun386i.h} for a Sun
386 system.

For the Mips computer, there are five choices: @file{tm-mips.h} for the
M series, @file{tm-mips-bsd.h} for the RS series with BSD,
@file{tm-mips-sysv.h} for the RS series with System V, @file{tm-iris.h}
for the Iris version of the machine, and @file{tm-decstatn.h} for the
Decstation.

For the 32000, use @file{tm-sequent.h} if you are using a Sequent
machine, or @file{tm-encore.h} for an Encore machine, or
@file{tm-genix.h} if you are using Genix version 3; otherwise, perhaps
@file{tm-ns32k.h} will work for you.

Note that Genix has bugs in @code{alloca} and @code{malloc}; you must
get the compiled versions of these from GNU Emacs and edit GNU CC's
@file{Makefile} to use them.

Note that Encore systems are supported only under BSD.

For Sparc (Sun 4) machines, use @file{tm-sparc.h} with operating system
version 4, and @file{tm-sun4os3.h} with system version 3.

For Convex systems before version 8.1, use @file{tm-conv1os7.h} or
@file{tm-conv2os7.h}.  For versions 8.1 and greater, use @file{tm-convex1.h}
or @file{tm-convex2.h}.  You should also bootstrap GCC with @code{pcc}
rather than @code{cc}; one way to do this is with the following commands.

@example
ln -s /bin/pcc ./cc
set path = (. $path)
@end example

@item
Make a symbolic link named @file{md} to the machine description
pattern file.  It should be in the @file{config} subdirectory and its
name should be @file{@var{machine}.md}; but @var{machine} is often not
the same as the name used in the @file{tm.h} file because the
@file{md} files are more general.

@item
Make a symbolic link named @file{aux-output.c} to the output
subroutine file for your machine.  It should be in the @file{config}
subdirectory and its name should be @file{out-@var{machine}.c}.
@end itemize

@item
Make sure the Bison parser generator is installed.  (This is
unnecessary if the Bison output files @file{c-parse.tab.c} and
@file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
and you do not plan to change the @samp{.y} files.)

Bison versions older than Sept 8, 1988 will produce incorrect output
for @file{c-parse.tab.c}.

@item
If you have a previous version of GCC installed, then chances are
you can compile the new version with that.  Do the following:

@example
make CC="gcc -O"
@end example

@noindent
Since this produces an optimized executable right away, there is no need
to bootstrap the result with itself except to test it.  Therefore, you can
skip directly to the @samp{make install} step below.

@item
Build the compiler.  Just type @samp{make} in the compiler directory.

Ignore any warnings you may see about ``statement not reached'' in the
@file{insn-emit.c}; they are normal.  Any other compilation errors may
represent bugs in the port to your machine or operating system, and
should be investigated and reported (@pxref{Bugs}).

Some commercial compilers fail to compile GNU CC because they have bugs
or limitations.  For example, the Microsoft compiler is said to run out
of macro space.  Some Ultrix compilers run out of expression space; then
you need to break up the statement where the problem happens.

@item
If you are using COFF-encapsulation, you must convert @file{gnulib} to
a GNU-format library at this point.  See the file @file{README-ENCAP}
in the directory containing the GNU binary file utilities, for
directions.

@item
Move the first-stage object files and executables into a subdirectory
with this command:

@example
make stage1
@end example

The files are moved into a subdirectory named @file{stage1}.
Once installation is complete, you may wish to delete these files
with @code{rm -r stage1}.

@item
Recompile the compiler with itself, with this command:

@example
make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
@end example

This is called making the stage 2 compiler.

On a 68000 or 68020 system lacking floating point hardware,
unless you have selected a @file{tm.h} file that expects by default
that there is no such hardware, do this instead:

@example
make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
@end example

@item
If you wish to test the compiler by compiling it with itself one more
time, do this (in C shell):

@example
make stage2
make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
foreach file (*.o)
cmp $file stage2/$file
end
@end example

@noindent
This is called making the stage 3 compiler.  Aside from the @samp{-B}
option, the options should be the same as when you made the stage 2
compiler.

The @code{foreach} command (written in C shell) will notify you if any of
these stage 3 object files differs from those of stage 2.  On BSD systems,
any difference, no matter how innocuous, indicates that the stage 2
compiler has compiled GNU CC incorrectly, and is therefore a potentially
serious bug which you should investigate and report (@pxref{Bugs}).

On systems that use COFF object files, bytes 5 to 8 will always be
different, since it is a timestamp.  On these systems, you can do the
comparison as follows (in Bourne shell):

@example
for file in *.o; do
echo $file
tail +10c $file > foo1
tail +10c stage2/$file > foo2
cmp foo1 foo2
done
@end example

On MIPS machines, you should use the shell script @file{ecoff-cmp}
to compare two object files.

@item
Install the compiler driver, the compiler's passes and run-time support.
You can use the following command:

@example
make install
@end example

@noindent
This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to
files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in
directory @file{/usr/local/lib}, which is where the compiler driver
program looks for them.  It also copies the driver program @file{gcc}
into the directory @file{/usr/local/bin}, so that it appears in typical
execution search paths.@refill

@strong{Warning: there is a bug in @code{alloca} in the Sun library.
To avoid this bug, install the binaries of GNU CC that were compiled
by GNU CC.  They use @code{alloca} as a built-in function and never
the one in the library.}

@strong{Warning: the GNU CPP may not work for @file{ioctl.h},
@file{ttychars.h} and other system header files unless the
@samp{-traditional} option is used.}  The bug is in the header files:
at least on some machines, they rely on behavior that is incompatible
with ANSI C.  This behavior consists of substituting for macro
argument names when they appear inside of character constants.  The
@samp{-traditional} option tells GNU CC to behave the way these
headers expect.

Because of this problem, you might prefer to configure GNU CC to use
the system's own C preprocessor.  To do so, make the file
@file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.

Alternatively, on Sun systems and 4.3BSD at least, you can correct the
include files by running the shell script @file{fixincludes}.  This
installs modified, corrected copies of the files @file{ioctl.h},
@file{ttychars.h} and many others, in a special directory where only
GNU CC will normally look for them.  This script will work on various
systems because it chooses the files by searching all the system
headers for the problem cases that we know about.

Use the following command to do this:

@example
make includes
@end example

@noindent
If you selected a different directory for GNU CC installation when you
installed it, by specifying the Make variable @code{prefix} or
@code{libdir}, specify it the same way in this command.

Note that some systems are starting to come with ANSI C system header
files.  On these systems, don't run @file{fixincludes}; it may not work,
and is certainly not necessary.

@strong{Warning:} @file{fixincludes} does not work on many MIPS systems,
because those systems come with circular symbolic links which cause
@samp{ls -lR} to go into an infinite loop.
@end enumerate

If you cannot install the compiler's passes and run-time support in
@file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
specify a prefix by which they may be found.  The compiler concatenates
the prefix with the names  @file{cpp}, @file{cc1} and @file{gnulib}.
Thus, you can put the files in a directory @file{/usr/foo/gcc} and
specify @samp{-B/usr/foo/gcc/} when you run GNU CC.

Also, you can specify an alternative default directory for these files
by setting the Make variable @code{libdir} when you make GNU CC.

@node Other Dir, Sun Install, Installation, Installation
@section Compilation in a Separate Directory

If you wish to build the object files and executables in a directory
other than the one containing the source files, here is what you must
do differently:

@enumerate
@item
Go to that directory before running @file{config.gcc}:

@example
mkdir gcc-sun3
cd gcc-sun3
@end example

On systems that do not support symbolic links, this directory must be
on the same file system as the source code directory.

@item
Specify where to find @file{config.gcc} when you run it:

@example
../gcc-1.36/config.gcc @dots{}
@end example

@item
Specify where to find the sources, as an argument to @file{config.gcc}:

@example
../gcc-1.36/config.gcc -srcdir=../gcc-1.36 sun3
@end example

The @samp{-srcdir=@var{dir}} option is not needed when the source
directory is the parent of the current directory, because
@file{config.gcc} detects that case automatically.
@end enumerate

Now, you can run @code{make} in that directory.  You need not repeat the
configuration steps shown above, when ordinary source files change.  You
must, however, run @code{config.gcc} again when the configuration files
change, if your system does not support symbolic links.

@node Sun Install, 3b1 Install, Other Dir, Installation
@section Installing GNU CC on the Sun

Make sure the environment variable @code{FLOAT_OPTION} is not set when
you compile @file{gnulib}.  If this option were set to @code{f68881}
when @file{gnulib} is compiled, the resulting code would demand to be
linked with a special startup file and would not link properly without
special pains.  

There is a bug in @code{alloca} in certain versions of the Sun library. 
To avoid this bug, install the binaries of GNU CC that were compiled by
GNU CC.  They use @code{alloca} as a built-in function and never the one
in the library.  

Some versions of the Sun compiler crash when compiling GNU CC, with a
segmentation fault in cpp.  This can sometimes be due to the bulk of
data in the environment variables.  You may be able to avoid it by using
the following command to compile GNU CC with Sun CC:

@example
make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
@end example

Another problem that often happens on Suns is that you get a crash when
building stage 2, when @code{genflags} is run.

One reason for such as crash is if you configured GNU CC for the wrong
version of SunOS.  Starting with version 1.38, configurations @code{sun3}
and @code{sun4} are for SunOS 4, so this problem should no longer happen.

Another cause of the same symptom is having installed the GNU linker
with an earlier version of SunOS.  The version that worked before
stopped working due to a change in the format of executables in SunOS
4.1.  Many sites have installed the GNU linker as
@file{/usr/local/lib/gcc-ld}, often as part of installing GNU C++.  So
if you get such crashes and you have used the proper configuration, try
deleting @file{/usr/local/lib/gcc-ld}.

The current version of the GNU linker, found in the current binutils
release, does work with SunOS 4.1.

@node 3b1 Install, SCO Install, Sun Install, Installation
@section Installing GNU CC on the 3b1

Installing GNU CC on the 3b1 is difficult if you do not already have
GNU CC running, due to bugs in the installed C compiler.  However,
the following procedure might work.  We are unable to test it.

@enumerate
@item
Comment out the @samp{#include "config.h"} line on line 37 of
@file{cccp.c} and do @samp{make cpp}.  This makes a preliminary version
of GNU cpp.  

@item
Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that
file name.  

@item
Undo your change in @file{cccp.c}, or reinstall the original version,
and do @samp{make cpp} again.  

@item
Copy this final version of GNU cpp into @file{/lib/cpp}.

@item
Replace every occurrence of @code{obstack_free} in @file{tree.c}
with @code{_obstack_free}.  

@item
Run @code{make} to get the first-stage GNU CC.

@item
Reinstall the original version of @file{/lib/cpp}.

@item
Now you can compile GNU CC with itself and install it in the normal
fashion.
@end enumerate

If you have installed an earlier version of GCC, you can compile the
newer version with that.  However, you will run into trouble compiling
@file{gnulib}, since that is normally compiled with CC.  To solve the
problem, uncomment this line in @file{Makefile}:

@example
CCLIBFLAGS = -B/usr/local/lib/gcc- -tp -Wp,-traditional
@end example

@node SCO Install, VMS Install, 3B1 Install, Installation
@section Installing GNU CC on SCO System V 3.2
@cindex Installation on SCO systems

The compiler that comes with this system does not work properly with
@samp{-O}.  Therefore, you should redefine the Make variable
@code{CCLIBFLAGS} not to use @samp{-O}.

You should also edit @file{Makefile} to enable the lines that set
@code{CLIB} to @code{-lPW}, and the ones specifically labeled as being
for SCO, that set @code{RANLIB}, and that set @code{CC} and @code{OLDCC}
to @code{rcc}.

Also, edit the definition of @code{USER_H} to remove the file @file{limits.h}.

Then you can run @samp{config.gcc i386-sco} and finish building GNU CC
normally.

The same recipe should work on ESIX, but use @samp{config.gcc i386-esix}
instead.

@node VMS Install, HPUX Install, SCO Install, Installation
@section Installing GNU CC on VMS

The VMS version of GNU CC is distributed in a backup saveset containing
both source code and precompiled binaries.

To install the @file{gcc} command so you can use the compiler easily, in
the same manner as you use the VMS C compiler, you must install the VMS CLD
file for GNU CC as follows:

@enumerate
@item
Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
to point to the directories where the GNU CC executables
(@file{gcc-cpp}, @file{gcc-cc1}, etc.) and the C include files are
kept.  This should be done with the commands:@refill

@example
$ assign /super /system disk:[gcc.] gnu_cc
$ assign /super /system disk:[gcc.include.] gnu_cc_include
@end example

@noindent
with the appropriate disk and directory names.  These commands can be
placed in your system startup file so they will be executed whenever
the machine is rebooted.  You may, if you choose, do this via the
@file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.

@item
Install the @file{GCC} command with the command line:

@example
$ set command /table=sys$library:dcltables gnu_cc:[000000]gcc
@end example

@item
To install the help file, do the following:

@example
$ lib/help sys$library:helplib.hlb gcc.hlp
@end example

@noindent
Now you can invoke the compiler with a command like @samp{gcc /verbose
file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
Unix.
@end enumerate

We try to put corresponding binaries and sources on the VMS distribution
tape.  But sometimes the binaries will be from an older version that the
sources, because we don't always have time to update them.  (Use the
@samp{/verbose} option to determine the version number of the binaries and
compare it with the source file @file{version.c} to tell whether this is
so.)  In this case, you should use the binaries you get to recompile the
sources.  If you must recompile, here is how:

@enumerate
@item
Copy the file @file{tm-vms.h} to @file{tm.h}, @file{xm-vms.h} to
@file{config.h}, @file{vax.md} to @file{md.} and @file{out-vax.c}
to @file{aux-output.c}.  The files to be copied are found in the
subdirectory named @file{config}; they should be copied to the
main directory of GNU CC.@refill

@item
Setup the logical names and command tables as defined above.  In
addition, define the vms logical name @samp{GNU_BISON} to point at the
to the directories where the Bison executable is kept.  This should be
done with the command:@refill

@example
$ assign /super /system disk:[bison.] gnu_bison
@end example

You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
@file{[BISON]} directory.

@item
Install the @samp{BISON} command with the command line:@refill

@example
$ set command /table=sys$library:dcltables gnu_bison:[000000]bison
@end example

@item
Type @samp{@@make} to do recompile everything.

If you are compiling with a version of GNU CC older than 1.33, specify
@samp{/DEFINE=("inline=")} as an option in all the compilations.  This
requires editing all the @code{gcc} commands in @file{make-cc1.com}.
(The older versions had problems supporting @code{inline}.)  Once you
have a working 1.33 or newer GNU CC, you can change this file back.
@end enumerate

Due to the differences between the filesystems of Unix and VMS, the
preprocessor attempts to translate the names of include files into
something that VMS will understand.  The basic strategy is to prepend a
prefix to the specification of the include file, convert the whole
filename to a VMS filename, and then try to open the file.  The
preprocessor tries various prefixes until one of them succeeds.

The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
where GNU_C header files are traditionally stored.  If a header file is
not found there, @samp{SYS$SYSROOT:[SYSLIB.]} is tried next.  If the
preprocessor is still unable to locate the file, it then assumes that
the include file specification is a valid VMS filename all by itself,
and it uses this filename to attempt to open the include file.  If none
of these strategies succeeds, the preprocessor reports an error.

If you wish to store header files in non-standard locations, then you
can assign the logical @samp{GNU_CC_INCLUDE} to be a search list, where
each element of the list is suitable for use with a rooted logical.

With this version of GNU CC, @code{const} global variables now work
properly.  Unless, however, the @code{const} modifier is also specified
in every external declaration of the variable in all of the source files
that use that variable, the linker will issue warnings about conflicting
attributes for the variable, since the linker does not know if the
variable should be read-only.  The program will still work, but the
variable will be placed in writable storage.

Due to an assembler bug, offsets to static constants are sometimes
incorrectly evaluated.  This bug is present in GAS 1.38.1, and should be
fixed in the next version.

Under previous versions of GNU CC, the generated code would occasionally
give strange results when linked to the sharable @file{VAXCRTL} library.
Now this should work.

Even with this version, however, GNU CC itself should not be linked to the
sharable @file{VAXCRTL}. The @file{qsort} routine supplied with @file{VAXCRTL}
has a bug which can cause a compiler crash.

Similarly, the preprocessor should not be linked to the sharable
@file{VAXCRTL}. The @code{strncat} routine supplied with @file{VAXCRTL} has a
bug which can cause the preprocessor to go into an infinite loop. 

It should be pointed out that if you attempt to link to the sharable
@file{VAXCRTL}, the VMS linker will strongly resist any effort to force
it to use the @code{qsort} and @code{strncat} routines from
@file{gcclib}.  Until the bugs in @file{VAXCRTL} have been fixed,
linking any of the compiler components to the sharable VAXCRTL is not
recommended.  (These routines can be bypassed by placing duplicate copies
of @code{qsort} and @code{strncat} in @file{gcclib} under different
names, and patching the compiler sources to use these routines).  Both
of the bugs in @file{VAXCRTL} are still present in VMS version 5.4-1,
which is the most recent version as of this writing.

The executables that are generated by @file{make-cc1.com} and
@file{make-cccp.com} use the non-shared version of @file{VAXCRTL} (and
thus use the @code{qsort} and @code{strncat} routines from
@file{gcclib.olb}).

Note that GNU CC on VMS now generates debugging information to describe
the programs symbols to the VMS debugger.  However, you need version 1.37
or later of GAS in order to output them properly in the object file.

The VMS linker does not distinguish between upper and lower case letters
in function and variable names.  However, usual practice in C is to
distinguish case.  Normally GNU C (by means of the assembler GAS)
implements usual C behavior by augmenting each name that is not all
lower-case.  A name is augmented by truncating it to at most 23
characters and then adding more characters at the end which encode the
case pattern the rest.

Name augmentation yields bad results for programs that use precompiled
libraries (such as Xlib) which were generated by another compiler.  Use
the compiler option @samp{/NOCASE_HACK} to inhibits augmentation; it
makes external C functions and variables case-independent as is usual on
VMS.  Alternatively, you could write all references to the functions and
variables in such libraries using lower case; this will work on VMS, but
is not portable to other systems.  In cases where you need to
selectively inhibit augmentation, you can define a macro for each mixed
case symbol for which you wish to inhibit augmentation, where the macro
expands into the lower case equivalent of the name.

@node HPUX Install, Tower Install, VMS Install, Installation
@section Installing GNU CC on HPUX

To install GNU CC on HPUX, you must start by editing the file
@file{Makefile}.  Search for the string @samp{HPUX} to find comments
saying what to change.  You need to change some variable definitions and
(if you are using GAS) some lines in the rule for the target
@samp{gnulib}.

To avoid errors when linking programs with @samp{-g}, create an empty
library named @file{libg.a}.  An easy way to do this is:

@example
ar rc /usr/local/lib/libg.a
@end example

To compile with the HPUX C compiler, you must specify get the file
@file{alloca.c} from GNU Emacs.  Then, when you run @code{make}, use
this argument:

@example
make ALLOCA=alloca.o
@end example

When recompiling GNU CC with itself, do not define @code{ALLOCA}.
Instead, an @samp{-I} option needs to be added to @code{CFLAGS} as
follows:

@example
make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -I../binutils/hp-include"
@end example

@node Tower Install,, HPUX Install, Installation
@section Installing GNU CC on an NCR Tower

On an NCR Tower model 4x0 or 6x0, you may have trouble because the
default maximum virtual address size of a process is just 1 Mb.  Most
often you will find this problem while compiling GNU CC with itself.

The only way to solve the problem is to reconfigure the kernel.
Add a line such as this to the configuration file:

@example
MAXUMEM = 4096
@end example

@noindent
and then relink the kernel and reboot the machine.


@node Trouble, Service, Installation, Top
@chapter Known Causes of Trouble with GNU CC

Here are some of the things that have caused trouble for people installing
or using GNU CC.

@itemize @bullet
@item
On certain systems, defining certain environment variables such as
@code{CC} can interfere with the functioning of @code{make}.

@item
Cross compilation can run into trouble for certain machines because
some target machines' assemblers require floating point numbers to be
written as @emph{integer} constants in certain contexts.

The compiler writes these integer constants by examining the floating
point value as an integer and printing that integer, because this is
simple to write and independent of the details of the floating point
representation.  But this does not work if the compiler is running on
a different machine with an incompatible floating point format, or
even a different byte-ordering.

In addition, correct constant folding of floating point values
requires representing them in the target machine's format.
(The C standard does not quite require this, but in practice
it is the only way to win.)

It is now possible to overcome these problems by defining macros such
as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
work for each target machine.  @xref{Cross-compilation}.

@item
Users often think it is a bug when GNU CC reports an error for code
like this:

@example
int foo (short);

int foo (x)
     short x;
@{@dots{}@}
@end example

The error message is correct: this code really is erroneous, because the
old-style non-prototype definition passes subword integers in their
promoted types.  In other words, the argument is really an @code{int},
not a @code{short}.  The correct prototype is this:

@example
int foo (int);
@end example

@item
Users often think it is a bug when GNU CC reports an error for code
like this:

@example
int foo (struct mumble *);

struct mumble @{ @dots{} @};

int foo (struct mumble *x)
@{ @dots{} @}
@end example

This code really is erroneous, because the scope of @code{struct
mumble} the prototype is limited to the argument list containing it.
It does not refer to the @code{struct mumble} defined with file scope
immediately below---they are two unrelated types with similar names in
different scopes.

But in the definition of @code{foo}, the file-scope type is used
because that is available to be inherited.  Thus, the definition and
the prototype do not match, and you get an error.

This behavior may seem silly, but it's what the ANSI standard
specifies.  It is easy enough for you to make your code work by moving
the definition of @code{struct mumble} above the prototype.  I don't
think it's worth being incompatible for.
@end itemize

Additional problems are described in @ref{Incompatibilities}.

@node Service, Incompatibilities, Trouble, Top
@chapter How To Get Help with GNU CC

If you need help installing, using or changing GNU CC, there are two
ways to find it:

@itemize @bullet
@item
Send a message to a suitable network mailing list.  First try
@code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try
@code{help-gcc@@prep.ai.mit.edu}.

@item
Look in the service directory for someone who might help you for a fee.
The service directory is found in the file named @file{SERVICE} in the
GNU CC distribution.
@end itemize

@node Incompatibilities, Extensions, Service, Top
@chapter Incompatibilities of GNU CC

There are several noteworthy incompatibilities between GNU C and most
existing (non-ANSI) versions of C.  The @samp{-traditional} option
eliminates most of these incompatibilities, @emph{but not all}, by
telling GNU C to behave like older C compilers.

@itemize @bullet
@item
GNU CC normally makes string constants read-only.  If several
identical-looking string constants are used, GNU CC stores only one
copy of the string.

One consequence is that you cannot call @code{mktemp} with a string
constant argument.  The function @code{mktemp} always alters the
string its argument points to.

Another consequence is that @code{sscanf} does not work on some
systems when passed a string constant as its format control string.
This is because @code{sscanf} incorrectly tries to write into the
string constant.  Likewise @code{fscanf} and @code{scanf}.

The best solution to these problems is to change the program to use
@code{char}-array variables with initialization strings for these
purposes instead of string constants.  But if this is not possible,
you can use the @samp{-fwritable-strings} flag, which directs GNU CC
to handle string constants the same way most C compilers do.
@samp{-traditional} also has this effect, among others.

@item
GNU CC does not substitute macro arguments when they appear inside of
string constants.  For example, the following macro in GNU CC

@example
#define foo(a) "a"
@end example

@noindent
will produce output @code{"a"} regardless of what the argument @var{a} is.

The @samp{-traditional} option directs GNU CC to handle such cases
(among others) in the old-fashioned (non-ANSI) fashion.

@item
When you use @code{setjmp} and @code{longjmp}, the only automatic
variables guaranteed to remain valid are those declared
@code{volatile}.  This is a consequence of automatic register
allocation.  Consider this function:

@example
jmp_buf j;

foo ()
@{
  int a, b;

  a = fun1 ();
  if (setjmp (j))
    return a;

  a = fun2 ();
  /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
  return a + fun3 ();
@}
@end example

Here @code{a} may or may not be restored to its first value when the
@code{longjmp} occurs.  If @code{a} is allocated in a register, then
its first value is restored; otherwise, it keeps the last value stored
in it.

If you use the @samp{-W} option with the @samp{-O} option, you will
get a warning when GNU CC thinks such a problem might be possible.

The @samp{-traditional} option directs GNU C to put variables in
the stack by default, rather than in registers, in functions that
call @code{setjmp}.  This results in the behavior found in
traditional C compilers.

@item
Declarations of external variables and functions within a block apply
only to the block containing the declaration.  In other words, they
have the same scope as any other declaration in the same place.

In some other C compilers, a @code{extern} declaration affects all the
rest of the file even if it happens within a block.

The @samp{-traditional} option directs GNU C to treat all @code{extern}
declarations as global, like traditional compilers.

@item
In traditional C, you can combine @code{long}, etc., with a typedef name,
as shown here:

@example
typedef int foo;
typedef long foo bar;
@end example

In ANSI C, this is not allowed: @code{long} and other type modifiers
require an explicit @code{int}.  Because this criterion is expressed
by Bison grammar rules rather than C code, the @samp{-traditional}
flag cannot alter it.

@item
PCC allows typedef names to be used as function parameters.  The
difficulty described immediately above applies here too.

@item
PCC allows whitespace in the middle of compound assignment operators
such as @samp{+=}.  GNU CC, following the ANSI standard, does not
allow this.  The difficulty described immediately above applies here
too.

@item
GNU CC will flag unterminated character constants inside of preprocessor
conditionals that fail.  Some programs have English comments enclosed in
conditionals that are guaranteed to fail; if these comments contain
apostrophes, GNU CC will probably report an error.  For example,
this code would produce an error:

@example
#if 0
You can't expect this to work.
#endif
@end example

The best solution to such a problem is to put the text into an actual
C comment delimited by @samp{/*@dots{}*/}.  However,
@samp{-traditional} suppresses these error messages.

@item
When compiling functions that return @code{float}, PCC converts it to
a double.  GNU CC actually returns a @code{float}.  If you are concerned
with PCC compatibility, you should declare your functions to return
@code{double}; you might as well say what you mean.

@item
When compiling functions that return structures or unions, GNU CC
output code normally uses a method different from that used on most
versions of Unix.  As a result, code compiled with GNU CC cannot call
a structure-returning function compiled with PCC, and vice versa.

The method used by GNU CC is as follows: a structure or union which is 1,
2, 4 or 8 bytes long is returned like a scalar.  A structure or union
with any other size is stored into an address supplied by the caller
in a special, fixed register.

PCC usually handles all sizes of structures and unions by returning
the address of a block of static storage containing the value.  This
method is not used in GNU CC because it is slower and nonreentrant.

You can tell GNU CC to use the PCC convention with the option
@samp{-fpcc-struct-return}.
@end itemize

There are also system-specific incompatibilities.

@itemize @bullet
@item
On the Sparc, GNU CC uses an incompatible calling convention for
structures.  It passes them by including their contents in the argument
list, whereas the standard compiler passes them effectively by
reference.

This really ought to be fixed, but such calling conventions are not
yet supported in GNU CC, so it isn't straightforward to fix it.
GNU CC version 2 will use a compatible calling convention.

The convention for structure returning is also incompatible, and
@samp{-fpcc-struct-return} does not help.

@item 
The Sparc version of @code{setjmp} interacts badly with unexpected stack
adjustments.  With rare exceptions, you cannot use @code{setjmp} in a
function which moves the stack pointer.

In the current version of GNU CC, there are three ways that the stack
pointer can change value: (1) calls to @code{alloca}, (2) use of
variable-sized objects, and (3) calls to functions with parameters that
do not all fit in the argument-passing registers (e.g., more than 6
parameters).  You should avoid all three in functions that call
@code{setjmp}.

The cause of the problem is the way that Sun implemented register
windows.  The 64 bytes at addresses @code{%sp} through @code{%sp+63}
correspond to the register window save area.  When a register window
must be spilled, its stack pointer is located, and the registers are
dumped starting at that address.  Similarly, when a register window must
be restored, its stack pointer is located, and the registers are
restored from that address.

When @code{setjmp} is called, the current register window's registers
are saved into the register save area, and when @code{longjmp} is
called, they are restored (actually, @emph{all} register windows are
restored from all valid register windows at the time @code{longjmp} is
called).  If there is a change in the value of the stack pointer bewteen
the @code{setjmp} and @code{longjmp} calls, when the registers are
restored, they are restored with random values.

@item
On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
by function calls.  We have not been able to tell whether the C compiler
agrees with the Fortran compiler.  Currently, GNU CC treats these registers
as temporaries on the Vax, which is compatible with BSD Unix.

If we learn for certain that Ultrix has departed from the traditional
BSD calling convention, we will change GNU CC for Ultrix to fit.  In the
mean time, you can use these options to produce code compatible with the
Fortran compiler:

@example
-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
@end example

@item
DBX rejects some files produced by GNU CC, though it accepts similar
constructs in output from PCC.  Until someone can supply a coherent
description of what is valid DBX input and what is not, there is
nothing I can do about these problems.  You are on your own.
@end itemize

@node Extensions, Bugs, Incompatibilities, Top
@chapter GNU Extensions to the C Language

GNU C provides several language features not found in ANSI standard C.
(The @samp{-pedantic} option directs GNU CC to print a warning message if
any of these features is used.)  To test for the availability of these
features in conditional compilation, check for a predefined macro
@code{__GNUC__}, which is always defined under GNU CC.

@menu
* Statement Exprs::     Putting statements and declarations inside expressions.
* Naming Types::        Giving a name to the type of some expression.
* Typeof::              @code{typeof}: referring to the type of an expression.
* Lvalues::             Using @samp{?:}, @samp{,} and casts in lvalues.
* Conditionals::        Omitting the middle operand of a @samp{?:} expression.
* Zero-Length::         Zero-length arrays.
* Variable-Length::     Arrays whose length is computed at run time.
* Subscripting::        Any array can be subscripted, even if not an lvalue.
* Pointer Arith::       Arithmetic on @code{void}-pointers and function pointers.
* Initializers::        Non-constant initializers.
* Constructors::        Constructor expressions give structures, unions
                         or arrays as values.
* Function Attributes:: Declaring that functions have no side effects,
                         or that they can never return.
* Dollar Signs::        Dollar sign is allowed in identifiers.
* Alignment::           Inquiring about the alignment of a type or variable.
* Inline::              Defining inline functions (as fast as macros).
* Extended Asm::        Assembler instructions with C expressions as operands.
                         (With them you can define ``built-in'' functions.)
* Asm Labels::          Specifying the assembler name to use for a C symbol.
* Explicit Reg Vars::   Defining variables residing in specified registers.
* Alternate Keywords::  @code{__const__}, @code{__asm__}, etc., for header files.
@end menu

@node Statement Exprs, Naming Types, Extensions, Extensions
@section Statements and Declarations inside of Expressions

A compound statement in parentheses may appear inside an expression in GNU
C.  This allows you to declare variables within an expression.  For
example:

@example
(@{ int y = foo (); int z;
   if (y > 0) z = y;
   else z = - y;
   z; @})
@end example

@noindent
is a valid (though slightly more complex than necessary) expression
for the absolute value of @code{foo ()}.

This feature is especially useful in making macro definitions ``safe'' (so
that they evaluate each operand exactly once).  For example, the
``maximum'' function is commonly defined as a macro in standard C as
follows:

@example
#define max(a,b) ((a) > (b) ? (a) : (b))
@end example

@noindent
But this definition computes either @var{a} or @var{b} twice, with bad
results if the operand has side effects.  In GNU C, if you know the
type of the operands (here let's assume @code{int}), you can define
the macro safely as follows:

@example
#define maxint(a,b) \
  (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
@end example

Embedded statements are not allowed in constant expressions, such as
the value of an enumeration constant, the width of a bit field, or
the initial value of a static variable.

If you don't know the type of the operand, you can still do this, but you
must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
Types}).

@node Naming Types, Typeof, Statement Exprs, Extensions
@section Naming an Expression's Type

You can give a name to the type of an expression using a @code{typedef}
declaration with an initializer.  Here is how to define @var{name} as a
type name for the type of @var{exp}:

@example
typedef @var{name} = @var{exp};
@end example

This is useful in conjunction with the statements-within-expressions
feature.  Here is how the two together can be used to define a safe
``maximum'' macro that operates on any arithmetic type:

@example
#define max(a,b) \
  (@{typedef _ta = (a), _tb = (b);  \
    _ta _a = (a); _tb _b = (b);     \
    _a > _b ? _a : _b; @})
@end example

The reason for using names that start with underscores for the local
variables is to avoid conflicts with variable names that occur within the
expressions that are substituted for @code{a} and @code{b}.  Eventually we
hope to design a new form of declaration syntax that allows you to declare
variables whose scopes start only after their initializers; this will be a
more reliable way to prevent such conflicts.

@node Typeof, Lvalues, Naming Types, Extensions
@section Referring to a Type with @code{typeof}

Another way to refer to the type of an expression is with @code{typeof}.
The syntax of using of this keyword looks like @code{sizeof}, but the
construct acts semantically like a type name defined with @code{typedef}.

There are two ways of writing the argument to @code{typeof}: with an
expression or with a type.  Here is an example with an expression:

@example
typeof (x[0](1))
@end example

@noindent
This assumes that @code{x} is an array of functions; the type described
is that of the values of the functions.

Here is an example with a typename as the argument:

@example
typeof (int *)
@end example

@noindent
Here the type described is that of pointers to @code{int}.

If you are writing a header file that must work when included in ANSI C
programs, write @code{__typeof__} instead of @code{typeof}.
@xref{Alternate Keywords}.

A @code{typeof}-construct can be used anywhere a typedef name could be
used.  For example, you can use it in a declaration, in a cast, or inside
of @code{sizeof} or @code{typeof}.

@itemize @bullet
@item
This declares @code{y} with the type of what @code{x} points to.

@example
typeof (*x) y;
@end example

@item
This declares @code{y} as an array of such values.

@example
typeof (*x) y[4];
@end example

@item
This declares @code{y} as an array of pointers to characters:

@example
typeof (typeof (char *)[4]) y;
@end example

@noindent
It is equivalent to the following traditional C declaration:

@example
char *y[4];
@end example

To see the meaning of the declaration using @code{typeof}, and why it
might be a useful way to write, let's rewrite it with these macros:

@example
#define pointer(T)  typeof(T *)
#define array(T, N) typeof(T [N])
@end example

@noindent
Now the declaration can be rewritten this way:

@example
array (pointer (char), 4) y;
@end example

@noindent
Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
pointers to @code{char}.
@end itemize

@node Lvalues, Conditionals, Typeof, Extensions
@section Generalized Lvalues

Compound expressions, conditional expressions and casts are allowed as
lvalues provided their operands are lvalues.  This means that you can take
their addresses or store values into them.

For example, a compound expression can be assigned, provided the last
expression in the sequence is an lvalue.  These two expressions are
equivalent:

@example
(a, b) += 5
a, (b += 5)
@end example

Similarly, the address of the compound expression can be taken.  These two
expressions are equivalent:

@example
&(a, b)
a, &b
@end example

A conditional expression is a valid lvalue if its type is not void and the
true and false branches are both valid lvalues.  For example, these two
expressions are equivalent:

@example
(a ? b : c) = 5
(a ? b = 5 : (c = 5))
@end example

A cast is a valid lvalue if its operand is valid.  Taking the address of
the cast is the same as taking the address without a cast, except for the
type of the result.  For example, these two expressions are equivalent (but
the second may be valid when the type of @code{a} does not permit a cast to
@code{int *}).

@example
&(int *)a
(int **)&a
@end example

A simple assignment whose left-hand side is a cast works by converting the
right-hand side first to the specified type, then to the type of the inner
left-hand side expression.  After this is stored, the value is converter
back to the specified type to become the value of the assignment.  Thus, if
@code{a} has type @code{char *}, the following two expressions are
equivalent:

@example
(int)a = 5
(int)(a = (char *)5)
@end example

An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
performs the arithmetic using the type resulting from the cast, and then
continues as in the previous case.  Therefore, these two expressions are
equivalent:

@example
(int)a += 5
(int)(a = (char *) ((int)a + 5))
@end example

@node Conditionals, Zero-Length, Lvalues, Extensions
@section Conditional Expressions with Omitted Middle-Operands

The middle operand in a conditional expression may be omitted.  Then
if the first operand is nonzero, its value is the value of the conditional
expression.

Therefore, the expression

@example
x ? : y
@end example

@noindent
has the value of @code{x} if that is nonzero; otherwise, the value of
@code{y}.

This example is perfectly equivalent to

@example
x ? x : y
@end example

@noindent
In this simple case, the ability to omit the middle operand is not
especially useful.  When it becomes useful is when the first operand does,
or may (if it is a macro argument), contain a side effect.  Then repeating
the operand in the middle would perform the side effect twice.  Omitting
the middle operand uses the value already computed without the undesirable
effects of recomputing it.

@node Zero-Length, Variable-Length, Conditionals, Extensions
@section Arrays of Length Zero

Zero-length arrays are allowed in GNU C.  They are very useful as the last
element of a structure which is really a header for a variable-length
object:

@example
struct line @{
  int length;
  char contents[0];
@};

@{
  struct line *thisline 
    = (struct line *) malloc (sizeof (struct line) + this_length);
  thisline->length = this_length;
@}
@end example

In standard C, you would have to give @code{contents} a length of 1, which
means either you waste space or complicate the argument to @code{malloc}.

@node Variable-Length, Subscripting, Zero-Length, Extensions
@section Arrays of Variable Length

Variable-length automatic arrays are allowed in GNU C.  These arrays are
declared like any other automatic arrays, but with a length that is not a
constant expression.  The storage is allocated at that time and
deallocated when the brace-level is exited.  For example:

@example
FILE *concat_fopen (char *s1, char *s2, char *mode)
@{
  char str[strlen (s1) + strlen (s2) + 1];
  strcpy (str, s1);
  strcat (str, s2);
  return fopen (str, mode);
@}
@end example

You can also use variable-length arrays as arguments to functions:

@example
struct entry
tester (int len, char data[len])
@{
  @dots{}
@}
@end example

The length of an array is computed on entry to the brace-level where the
array is declared and is remembered for the scope of the array in case you
access it with @code{sizeof}.

Jumping or breaking out of the scope of the array name will also deallocate
the storage.  Jumping into the scope is not allowed; you will get an error
message for it.

You can use the function @code{alloca} to get an effect much like
variable-length arrays.  The function @code{alloca} is available in
many other C implementations (but not in all).  On the other hand,
variable-length arrays are more elegant.

There are other differences between these two methods.  Space allocated
with @code{alloca} exists until the containing @emph{function} returns.
The space for a variable-length array is deallocated as soon as the array
name's scope ends.  (If you use both variable-length arrays and
@code{alloca} in the same function, deallocation of a variable-length array
will also deallocate anything more recently allocated with @code{alloca}.)

@node Subscripting, Pointer Arith, Variable-Length, Extensions
@section Non-Lvalue Arrays May Have Subscripts

Subscripting is allowed on arrays that are not lvalues, even though the
unary @samp{&} operator is not.  For example, this is valid in GNU C though
not valid in other C dialects:

@example
struct foo @{int a[4];@};

struct foo f();

bar (int index)
@{
  return f().a[index];
@}
@end example

@node Pointer Arith, Initializers, Subscripting, Extensions
@section Arithmetic on @code{void}-Pointers and Function Pointers

In GNU C, addition and subtraction operations are supported on pointers to
@code{void} and on pointers to functions.  This is done by treating the
size of a @code{void} or of a function as 1.

A consequence of this is that @code{sizeof} is also allowed on @code{void}
and on function types, and returns 1.

The option @samp{-Wpointer-arith} requests a warning if these extensions
are used.

@node Initializers, Constructors, Pointer Arith, Extensions
@section Non-Constant Initializers

The elements of an aggregate initializer for an automatic variable are
not required to be constant expressions in GNU C.  Here is an example of
an initializer with run-time varying elements:

@example
foo (float f, float g)
@{
  float beat_freqs[2] = @{ f-g, f+g @};
  @dots{}
@}
@end example

@node Constructors, Function Attributes, Initializers, Extensions
@section Constructor Expressions

GNU C supports constructor expressions.  A constructor looks like a cast
containing an initializer.  Its value is an object of the type specified in
the cast, containing the elements specified in the initializer.  The type
must be a structure, union or array type.

Assume that @code{struct foo} and @code{structure} are declared as shown:

@example
struct foo @{int a; char b[2];@} structure;
@end example

@noindent
Here is an example of constructing a @code{struct foo} with a constructor:

@example
structure = ((struct foo) @{x + y, 'a', 0@});
@end example

@noindent
This is equivalent to writing the following:

@example
@{
  struct foo temp = @{x + y, 'a', 0@};
  structure = temp;
@}
@end example

You can also construct an array.  If all the elements of the constructor
are (made up of) simple constant expressions, suitable for use in
initializers, then the constructor is an lvalue and can be coerced to a
pointer to its first element, as shown here:

@example
char **foo = (char *[]) @{ "x", "y", "z" @};
@end example

Array constructors whose elements are not simple constants are not very
useful, because the constructor is not an lvalue.  There are only two valid
ways to use it: to subscript it, or initialize an array variable with it.
The former is probably slower than a @code{switch} statement, while the
latter does the same thing an ordinary C initializer would do.

@example
output = ((int[]) @{ 2, x, 28 @}) [input];
@end example

@node Function Attributes, Dollar Signs, Constructors, Extensions
@section Declaring Attributes of Functions

In GNU C, you declare certain things about functions called in your program
which help the compiler optimize function calls.

A few functions, such as @code{abort} and @code{exit}, cannot return.
These functions should be declared @code{volatile}.  For example,

@example
extern volatile void abort ();
@end example

@noindent
tells the compiler that it can assume that @code{abort} will not return.
This makes slightly better code, but more importantly it helps avoid
spurious warnings of uninitialized variables.

Many functions do not examine any values except their arguments, and
have no effects except the return value.  Such a function can be subject
to common subexpression elimination and loop optimization just as an
arithmetic operator would be.  These functions should be declared
@code{const}.  For example,

@example
extern const void square ();
@end example

@noindent
says that the hypothetical function @code{square} is safe to call
fewer times than the program says.

Note that a function that has pointer arguments and examines the data
pointed to must @emph{not} be declared @code{const}.  Likewise, a
function that calls a non-@code{const} function usually must not be
@code{const}.

Some people object to this feature, claiming that ANSI C's @code{#pragma}
should be used instead.  There are two reasons I did not do this.

@enumerate
@item
It is impossible to generate @code{#pragma} commands from a macro.

@item
The @code{#pragma} command is just as likely as these keywords to mean
something else in another compiler.
@end enumerate

These two reasons apply to @emph{any} application whatever: as far as
I can see, @code{#pragma} is never useful.

@node Dollar Signs, Alignment, Function Attributes, Extensions
@section Dollar Signs in Identifier Names

In GNU C, you may use dollar signs in identifier names.  This is because
many traditional C implementations allow such identifiers.

Dollar signs are allowed if you specify @samp{-traditional}; they are
not allowed if you specify @samp{-ansi}.  Whether they are allowed by
default depends on the target machine; usually, they are not.

@node Alignment, Inline, Dollar Signs, Extensions
@section Inquiring about the Alignment of a Type or Variable

The keyword @code{__alignof__} allows you to inquire about how an object
is aligned, or the minimum alignment usually required by a type.  Its
syntax is just like @code{sizeof}.

For example, if the target machine requires a @code{double} value to be
aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
This is true on many RISC machines.  On more traditional machine
designs, @code{__alignof__ (double)} is 4 or even 2.

Some machines never actually require alignment; they allow reference to any
data type even at an odd addresses.  For these machines, @code{__alignof__}
reports the @emph{recommended} alignment of a type.

When the operand of @code{__alignof__} is an lvalue rather than a type, the
value is the largest alignment that the lvalue is known to have.  It may
have this alignment as a result of its data type, or because it is part of
a structure and inherits alignment from that structure. For example, after
this declaration:

@example
struct foo @{ int x; char y; @} foo1;
@end example

@noindent
the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
@code{__alignof__ (int)}, even though the data type of @code{foo1.y}
does not itself demand any alignment.@refill

@node Inline, Extended Asm, Alignment, Extensions
@section An Inline Function is As Fast As a Macro

By declaring a function @code{inline}, you can direct GNU CC to integrate
that function's code into the code for its callers.  This makes execution
faster by eliminating the function-call overhead; in addition, if any of
the actual argument values are constant, their known values may permit
simplifications at compile time so that not all of the inline function's
code needs to be included.

To declare a function inline, use the @code{inline} keyword in its
declaration, like this:

@example
inline int
inc (int *a)
@{
  (*a)++;
@}
@end example

(If you are writing a header file to be included in ANSI C programs, write
@code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.)

You can also make all ``simple enough'' functions inline with the option
@samp{-finline-functions}.  Note that certain usages in a function
definition can make it unsuitable for inline substitution.

When a function is both inline and @code{static}, if all calls to the
function are integrated into the caller, and the function's address is
never used, then the function's own assembler code is never referenced.
In this case, GNU CC does not actually output assembler code for the
function, unless you specify the option @samp{-fkeep-inline-functions}.
Some calls cannot be integrated for various reasons (in particular,
calls that precede the function's definition cannot be integrated, and
neither can recursive calls within the definition).  If there is a
nonintegrated call, then the function is compiled to assembler code as
usual.  The function must also be compiled as usual if the program
refers to its address, because that can't be inlined.

When an inline function is not @code{static}, then the compiler must assume
that there may be calls from other source files; since a global symbol can
be defined only once in any program, the function must not be defined in
the other source files, so the calls therein cannot be integrated.
Therefore, a non-@code{static} inline function is always compiled on its
own in the usual fashion.

If you specify both @code{inline} and @code{extern} in the function
definition, then the definition is used only for inlining.  In no case
is the function compiled on its own, not even if you refer to its
address explicitly.  Such an address becomes an external reference, as
if you had only declared the function, and had not defined it.

This combination of @code{inline} and @code{extern} has almost the
effect of a macro.  The way to use it is to put a function definition in
a header file with these keywords, and put another copy of the
definition (lacking @code{inline} and @code{extern}) in a library file.
The definition in the header file will cause most calls to the function
to be inlined.  If any uses of the function remain, they will refer to
the single copy in the library.

@node Extended Asm, Asm Labels, Inline, Extensions
@section Assembler Instructions with C Expression Operands

In an assembler instruction using @code{asm}, you can now specify the
operands of the instruction using C expressions.  This means no more
guessing which registers or memory locations will contain the data you want
to use.

You must specify an assembler instruction template much like what appears
in a machine description, plus an operand constraint string for each
operand.

For example, here is how to use the 68881's @code{fsinx} instruction:

@example
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
@end example

@noindent
Here @code{angle} is the C expression for the input operand while
@code{result} is that of the output operand.  Each has @samp{"f"} as its
operand constraint, saying that a floating-point register is required.  The
@samp{=} in @samp{=f} indicates that the operand is an output; all output
operands' constraints must use @samp{=}.  The constraints use the same
language used in the machine description (@pxref{Constraints}).

Each operand is described by an operand-constraint string followed by the C
expression in parentheses.  A colon separates the assembler template from
the first output operand, and another separates the last output operand
from the first input, if any.  Commas separate output operands and separate
inputs.  The total number of operands is limited to the maximum number of
operands in any instruction pattern in the machine description.

If there are no output operands, and there are input operands, then there
must be two consecutive colons surrounding the place where the output
operands would go.

Output operand expressions must be lvalues; the compiler can check this.
The input operands need not be lvalues.  The compiler cannot check whether
the operands have data types that are reasonable for the instruction being
executed.  It does not parse the assembler instruction template and does
not know what it means, or whether it is valid assembler input.  The
extended @code{asm} feature is most often used for machine instructions
that the compiler itself does not know exist.

The output operands must be write-only; GNU CC will assume that the values
in these operands before the instruction are dead and need not be
generated.  Extended asm does not support input-output or read-write
operands.  For this reason, the constraint character @samp{+}, which
indicates such an operand, may not be used.

When the assembler instruction has a read-write operand, or an operand
in which only some of the bits are to be changed, you must logically
split its function into two separate operands, one input operand and one
write-only output operand.  The connection between them is expressed by
constraints which say they need to be in the same location when the
instruction executes.  You can use the same C expression for both
operands, or different expressions.  For example, here we write the
(fictitious) @samp{combine} instruction with @code{bar} as its read-only
source operand and @code{foo} as its read-write destination:

@example
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
@end example

@noindent
The constraint @samp{"0"} for operand 1 says that it must occupy the same
location as operand 0.  A digit in constraint is allowed only in an input
operand, and it must refer to an output operand.

Only a digit in the constraint can guarantee that one operand will be in
the same place as another.  The mere fact that @code{foo} is the value of
both operands is not enough to guarantee that they will be in the same
place in the generated assembler code.  The following would not work:

@example
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
@end example

Various optimizations or reloading could cause operands 0 and 1 to be in
different registers; GNU CC knows no reason not to do so.  For example, the
compiler might find a copy of the value of @code{foo} in one register and
use it for operand 1, but generate the output operand 0 in a different
register (copying it afterward to @code{foo}'s own address).  Of course,
since the register for operand 1 is not even mentioned in the assembler
code, the result will not work, but GNU CC can't tell that.

Unless an output operand has the @samp{&} constraint modifier, GNU CC may
allocate it in the same register as an unrelated input operand, on the
assumption that the inputs are consumed before the outputs are produced.
This assumption may be false if the assembler code actually consists of
more than one instruction.  In such a case, use @samp{&} for each output
operand that may not overlap an input.  @xref{Modifiers}.

Some instructions clobber specific hard registers.  To describe this, write
a third colon after the input operands, followed by the names of the
clobbered hard registers (given as strings).  Here is a realistic example
for the vax:

@example
asm volatile ("movc3 %0,%1,%2"
              : /* no outputs */
              : "g" (from), "g" (to), "g" (count)
              : "r0", "r1", "r2", "r3", "r4", "r5");
@end example

You can put multiple assembler instructions together in a single @code{asm}
template, separated either with newlines (written as @samp{\n}) or with
semicolons if the assembler allows such semicolons.  The GNU assembler
allows semicolons and all Unix assemblers seem to do so.  The input
operands are guaranteed not to use any of the clobbered registers, and
neither will the output operands' addresses, so you can read and write the
clobbered registers as many times as you like.  Here is an example of
multiple instructions in a template; it assumes that the subroutine
@code{_foo} accepts arguments in registers 9 and 10:

@example
asm ("movl %0,r9;movl %1,r10;call _foo"
     : /* no outputs */
     : "g" (from), "g" (to)
     : "r9", "r10");
@end example

If you want to test the condition code produced by an assembler instruction,
you must include a branch and a label in the @code{asm} construct, as follows:

@example
asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
     : "g" (result)
     : "g" (input));
@end example

@noindent
This assumes your assembler supports local labels, as the GNU assembler
and most Unix assemblers do.

Usually the most convenient way to use these @code{asm} instructions is to
encapsulate them in macros that look like functions.  For example,

@example
#define sin(x)       \
(@{ double __value, __arg = (x);   \
   asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
   __value; @})
@end example

@noindent
Here the variable @code{__arg} is used to make sure that the instruction
operates on a proper @code{double} value, and to accept only those
arguments @code{x} which can convert automatically to a @code{double}.

Another way to make sure the instruction operates on the correct data type
is to use a cast in the @code{asm}.  This is different from using a
variable @code{__arg} in that it converts more different types.  For
example, if the desired type were @code{int}, casting the argument to
@code{int} would accept a pointer with no complaint, while assigning the
argument to an @code{int} variable named @code{__arg} would warn about
using a pointer unless the caller explicitly casts it.

If an @code{asm} has output operands, GNU CC assumes for optimization
purposes that the instruction has no side effects except to change the
output operands.  This does not mean that instructions with a side effect
cannot be used, but you must be careful, because the compiler may eliminate
them if the output operands aren't used, or move them out of loops, or
replace two with one if they constitute a common subexpression.  Also, if
your instruction does have a side effect on a variable that otherwise
appears not to change, the old value of the variable may be reused later if
it happens to be found in a register.

You can prevent an @code{asm} instruction from being deleted, moved or
combined by writing the keyword @code{volatile} after the @code{asm}.  For
example:

@example
#define set_priority(x)  \
asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
@end example

@noindent
(However, an instruction without output operands will not be deleted
or moved, regardless, unless it is unreachable.)

It is a natural idea to look for a way to give access to the condition
code left by the assembler instruction.  However, when we attempted to
implement this, we found no way to make it work reliably.  The problem
is that output operands might need reloading, which would result in
additional following ``store'' instructions.  On most machines, these
instructions would alter the condition code before there was time to
test it.  This problem doesn't arise for ordinary ``test'' and
``compare'' instructions because they don't have any output operands.

If you are writing a header file that should be includable in ANSI C
programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
Keywords}.

@node Asm Labels, Explicit Reg Vars, Extended Asm, Extensions
@section 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 @code{asm} (or @code{__asm__})
keyword after the declarator as follows:

@example
int foo asm ("myfoo") = 2;
@end example

@noindent
This specifies that the name to be used for the variable @code{foo} in
the assembler code should be @samp{myfoo} rather than the usual
@samp{_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.

You cannot use @code{asm} in this way in a function @emph{definition}; but
you can get the same effect by writing a declaration for the function
before its definition and putting @code{asm} there, like this:

@example
extern func () asm ("FUNC");

func (x, y)
     int x, y;
@dots{}
@end example

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.  GNU
CC does not as yet have the ability to store static variables in registers.
Perhaps that will be added.

@node Explicit Reg Vars, Alternate Keywords, Asm Labels, Extensions
@section 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.

@itemize @bullet
@item
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.

@item
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.  These local variables are
sometimes convenient for use with the extended @code{asm} feature
(@pxref{Extended Asm}).
@end itemize

@menu
* Global Reg Vars::
* Local Reg Vars::
@end menu

@node Global Reg Vars, Local Reg Vars, Explicit Reg Vars, Explicit Reg Vars
@subsection Defining Global Register Variables

You can define a global register variable in GNU C like this:

@example
register int *foo asm ("a5");
@end example

@noindent
Here @code{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
@code{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 @code{%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 @code{foo} by way of a third function
@code{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 @code{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 @code{qsort}, since @code{qsort}
might have put something else in that register.  (If you are prepared to
recompile @code{qsort} with the same global register variable, you can
solve this problem.)

If you want to recompile @code{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 @samp{-ffixed-@var{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, @code{longjmp} will restore to each global register
variable the value it had at the time of the @code{setjmp}.  On some
machines, however, @code{longjmp} will not change the value of global
register variables.  To be portable, the function that called @code{setjmp}
should make other arrangements to save the values of the global register
variables, and to restore them in a @code{longjmp}.  This way, the same
thing will happen regardless of what @code{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.

@node Local Reg Vars,, Global Reg Vars, Explicit Reg Vars
@subsection Specifying Registers for Local Variables

You can define a local register variable with a specified register
like this:

@example
register int *foo asm ("a5");
@end example

@noindent
Here @code{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 (@pxref{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 @code{%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 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.  I would not be surprised if
excessive use of this feature leaves the compiler too few available
registers to compile certain functions.

@node Alternate Keywords,, Explicit Reg Vars, Extensions
@section Alternate Keywords

The option @samp{-traditional} disables certain keywords; @samp{-ansi}
disables certain others.  This causes trouble when you want to use GNU C
extensions, or ANSI C features, in a general-purpose header file that
should be usable by all programs, including ANSI C programs and traditional
ones.  The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
used since they won't work in a program compiled with @samp{-ansi}, while
the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
and @code{inline} won't work in a program compiled with
@samp{-traditional}.@refill

The way to solve these problems is to put @samp{__} at the beginning and
end of each problematical keyword.  For example, use @code{__asm__}
instead of @code{asm}, @code{__const__} instead of @code{const}, and
@code{__inline__} instead of @code{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:

@example
#ifndef __GNUC__
#define __asm__ asm
#endif
@end example

@node Bugs, Portability, Extensions, Top
@chapter Reporting Bugs

Your bug reports play an essential role in making GNU CC reliable.

When you encounter a problem, the first thing to do is to see if it is
already known.  @xref{Trouble}.  Also look in @ref{Incompatibilities}.
If it isn't known, then you should report the problem.

Reporting a bug may help you by bringing a solution to your problem, or
it may not.  (If it does not, look in the service directory; see
@ref{Service}.)  In any case, the principal function of a bug report
is to help the entire community by making the next version of GNU CC
work better.  Bug reports are your contribution to the maintenance of
GNU CC.

In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug.

@menu
* Criteria:  Bug Criteria.   Have you really found a bug?
* Reporting: Bug Reporting.  How to report a bug effectively.
@end menu

@node Bug Criteria, Bug Reporting, Bugs, Bugs
@section Have You Found a Bug?

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

@itemize @bullet
@item
If the compiler gets a fatal signal, for any input whatever, that is a
compiler bug.  Reliable compilers never crash.

@item
If the compiler produces invalid assembly code, for any input whatever
(except an @code{asm} statement), that is a compiler bug, unless the
compiler reports errors (not just warnings) which would ordinarily
prevent the assembler from being run.

@item
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 run
into an incompatibility between GNU C and traditional C
(@pxref{Incompatibilities}).  These incompatibilities might be considered
bugs, but they are inescapable consequences of valuable features.

Or you may have a program whose behavior is undefined, which happened
by chance to give the desired results with another C compiler.

For example, in many nonoptimizing compilers, you can write @samp{x;}
at the end of a function instead of @samp{return x;}, with the same
results.  But the value of the function is undefined if @code{return}
is omitted; it is not a bug when GNU CC produces different results.

Problems often result from expressions with two increment operators,
as in @code{f (*p++, *p++)}.  Your previous compiler might have
interpreted that expression the way you intended; GNU CC 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.

@item
If the compiler produces an error message for valid input, that is a
compiler bug.

Note that the following is not valid input, and the error message for
it is not a bug:

@example
int foo (char);

int
foo (x)
     char x;
@{ @dots{} @}
@end example

@noindent
The prototype says to pass a @code{char}, while the definition says to
pass an @code{int} and treat the value as a @code{char}.  This is what
the ANSI standard says, and it makes sense.

@item
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 my idea of ``an extension'' or ``support
for traditional practice''.

@item
If you are an experienced user of C compilers, your suggestions
for improvement of GNU CC are welcome in any case.
@end itemize

@node Bug Reporting,, Bug Criteria, Bugs
@section How to Report Bugs

Send bug reports for GNU C to one of these addresses:

@example
bug-gcc@@prep.ai.mit.edu
@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
@end example

@strong{Do not send bug reports to @samp{help-gcc}, or to the newsgroup
@samp{gnu.gcc.help}.}  Most users of GNU CC do not want to receive bug
reports.  Those that do, have asked to be on @samp{bug-gcc}.

The mailing list @samp{bug-gcc} has a newsgroup which serves as a
repeater.  The mailing list and the newsgroup carry exactly the same
messages.  Often people think of posting bug reports to the newsgroup
instead of mailing them.  This appears to work, but it has one problem
which can be crucial: a newsgroup posting does not contain a mail path
back to the sender.  Thus, if I need to ask for more information, I
may be unable to reach you.  For this reason, it is better to send bug
reports to the mailing list.

As a last resort, send bug reports on paper to:

@example
GNU Compiler Bugs
Free Software Foundation
675 Mass Ave
Cambridge, MA 02139
@end example

The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}.  If you are not sure whether to state a
fact or leave it out, state it!

Often people omit facts because they think they know what causes the
problem and they conclude that some details don't matter.  Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
name is stored in memory; perhaps, if the name were different, the contents
of that location would fool the compiler into doing the right thing despite
the bug.  Play it safe and give a specific, complete example.  That is the
easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable me to fix
the bug if it is not known.  It isn't very important what happens if
the bug is already known.  Therefore, always write your bug reports on
the assumption that the bug is not known.

Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?''  Those bug reports are useless, and I urge everyone to
@emph{refuse to respond to them} except to chide the sender to report
bugs properly.

To enable me to fix the bug, you should include all these things:

@itemize @bullet
@item
The version of GNU CC.  You can get this by running it with the
@samp{-v} option.

Without this, I won't know whether there is any point in looking for
the bug in the current version of GNU CC.

@item
A complete input file that will reproduce the bug.  If the bug is in
the C preprocessor, send me a source file and any header files that it
requires.  If the bug is in the compiler proper (@file{cc1}), run your
source file through the C preprocessor by doing @samp{gcc -E
@var{sourcefile} > @var{outfile}}, then include the contents of
@var{outfile} in the bug report.  (Any @samp{-I}, @samp{-D} or
@samp{-U} options that you used in actual compilation should also be
used when doing this.)

A single statement is not enough of an example.  In order to compile
it, it must be embedded in a function definition; and the bug might
depend on the details of how this is done.

Without a real example I can compile, all I can do about your bug
report is wish you luck.  It would be futile to try to guess how to
provoke the bug.  For example, bugs in register allocation and
reloading frequently depend on every little detail of the function
they happen in.

@item
The command arguments you gave GNU CC to compile that example and
observe the bug.  For example, did you use @samp{-O}?  To guarantee
you won't omit something important, list them all.

If I were to try to guess the arguments, I would probably guess wrong
and then I would not encounter the bug.

@item
The names of the files that you used for @file{tm.h} and @file{md}
when you installed the compiler.

@item
The type of machine you are using, and the operating system name and
version number.

@item
A description of what behavior you observe that you believe is
incorrect.  For example, ``It gets a fatal signal,'' or, ``There is an
incorrect assembler instruction in the output.''

Of course, if the bug is that the compiler gets a fatal signal, then I
will certainly notice it.  But if the bug is incorrect output, I might
not notice unless it is glaringly wrong.  I won't study all the
assembler code from a 50-line C program just on the off chance that it
might be wrong.

Even if the problem you experience is a fatal signal, you should still
say so explicitly.  Suppose something strange is going on, such as,
your copy of the compiler is out of synch, or you have encountered a
bug in the C library on your system.  (This has happened!)  Your copy
might crash and mine would not.  If you @i{told} me to expect a crash,
then when mine fails to crash, I would know that the bug was not
happening for me.  If you had not told me to expect a crash, then I
would not be able to draw any conclusion from my observations.

Often the observed symptom is incorrect output when your program is run.
Sad to say, this is not enough information for me unless the program is
short and simple.  If you send me a large program, I don't have time to
figure out how it would work if compiled correctly, much less which line
of it was compiled wrong.  So you will have to do that.  Tell me which
source line it is, and what incorrect result happens when that line is
executed.  A person who understands the test program can find this as
easily as a bug in the program itself.

@item
If you send me examples of output from GNU CC, please use @samp{-g}
when you make them.  The debugging information includes source line
numbers which are essential for correlating the output with the input.

@item
If you wish to suggest changes to the GNU CC source, send me context
diffs.  If you even discuss something in the GNU CC source, refer to
it by context, not by line number.

The line numbers in my development sources don't match those in your
sources.  Your line numbers would convey no useful information to me.

@item
Additional information from a debugger might enable me to find
a problem on a machine which I do not have available myself.
However, you need to think when you collect this information if
you want it to have any chance of being useful.

For example, many people send just a backtrace, but that is never
useful by itself.  A simple backtrace with arguments conveys little
about GNU CC because the compiler is largely data-driven; the same
functions are called over and over for different RTL insns, doing
different things depending on the details of the insn.

Most of the arguments listed in the backtrace are useless because they
are pointers to RTL list structure.  The numeric values of the
pointers, which the debugger prints in the backtrace, have no
significance whatever; all that matters is the contents of the objects
they point to (and most of the contents are other such pointers).

In addition, most compiler passes consist of one or more loops that
scan the RTL insn sequence.  The most vital piece of information about
such a loop---which insn it has reached---is usually in a local variable,
not in an argument.

What you need to provide in addition to a backtrace are the values of
the local variables for several stack frames up.  When a local
variable or an argument is an RTX, first print its value and then use
the GDB command @code{pr} to print the RTL expression that it points
to.  (If GDB doesn't run on your machine, use your debugger to call
the function @code{debug_rtx} with the RTX as an argument.)  In
general, whenever a variable is a pointer, its value is no use
without the data it points to.

In addition, include a debugging dump from just before the pass
in which the crash happens.  Most bugs involve a series of insns,
not just one.
@end itemize

Here are some things that are not necessary:

@itemize @bullet
@item
A description of the envelope of the bug.

Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.

This is often time consuming and not very useful, because the way I
will find the bug is by running a single example under the debugger
with breakpoints, not by pure deduction from a series of examples.
I recommend that you save your time for something else.

Of course, if you can find a simpler example to report @emph{instead}
of the original one, that is a convenience for me.  Errors in the
output will be easier to spot, running under the debugger will take
less time, etc.  Most GNU CC bugs involve just one function, so the
most straightforward way to simplify an example is to delete all the
function definitions except the one where the bug occurs.  Those
earlier in the file may be replaced by external declarations if the
crucial function depends on them.  (Exception: inline functions may
affect compilation of functions defined later in the file.)

However, simplification is not vital; if you don't want to do this,
report the bug anyway and send me the entire test case you used.

@item
A patch for the bug.

A patch for the bug does help me if it is a good one.  But don't omit
the necessary information, such as the test case, on the assumption that
a patch is all I need.  I might see problems with your patch and decide
to fix the problem another way, or I might not understand it at all.

Sometimes with a program as complicated as GNU CC it is very hard to
construct an example that will make the program follow a certain path
through the code.  If you don't send me the example, I won't be able
to construct one, so I won't be able to verify that the bug is fixed.

And if I can't understand what bug you are trying to fix, or why your
patch should be an improvement, I won't install it.  A test case will
help me to understand.

@item
A guess about what the bug is or what it depends on.

Such guesses are usually wrong.  Even I can't guess right about such
things without first using the debugger to find the facts.
@end itemize

@node Portability, Interface, Bugs, Top
@chapter GNU CC and Portability

The main goal of GNU CC was to make a good, fast compiler for machines in
the class that the GNU system aims to run on: 32-bit machines that address
8-bit bytes and have several general registers.  Elegance, theoretical
power and simplicity are only secondary.

GNU CC gets most of the information about the target machine from a machine
description which gives an algebraic formula for each of the machine's
instructions.  This is a very clean way to describe the target.  But when
the compiler needs information that is difficult to express in this
fashion, I have not hesitated to define an ad-hoc parameter to the machine
description.  The purpose of portability is to reduce the total work needed
on the compiler; it was not of interest for its own sake.

GNU CC does not contain machine dependent code, but it does contain code
that depends on machine parameters such as endianness (whether the most
significant byte has the highest or lowest address of the bytes in a word)
and the availability of autoincrement addressing.  In the RTL-generation
pass, it is often necessary to have multiple strategies for generating code
for a particular kind of syntax tree, strategies that are usable for different
combinations of parameters.  Often I have not tried to address all possible
cases, but only the common ones or only the ones that I have encountered.
As a result, a new target may require additional strategies.  You will know
if this happens because the compiler will call @code{abort}.  Fortunately,
the new strategies can be added in a machine-independent fashion, and will
affect only the target machines that need them.

@node Interface, Passes, Portability, Top
@chapter Interfacing to GNU CC Output

GNU CC is normally configured to use the same function calling convention
normally in use on the target system.  This is done with the
machine-description macros described (@pxref{Machine Macros}).

However, returning of structure and union values is done differently on
some target machines.  As a result, functions compiled with PCC
returning such types cannot be called from code compiled with GNU CC,
and vice versa.  This does not cause trouble often because few Unix
library routines return structures or unions.

GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
long in the same registers used for @code{int} or @code{double} return
values.  (GNU CC typically allocates variables of such types in
registers also.)  Structures and unions of other sizes are returned by
storing them into an address passed by the caller (usually in a
register).  The machine-description macros @code{STRUCT_VALUE} and
@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.

By contrast, PCC on most target machines returns structures and unions
of any size by copying the data into an area of static storage, and then
returning the address of that storage as if it were a pointer value.
The caller must copy the data from that memory area to the place where
the value is wanted.  This is slower than the method used by GNU CC, and
fails to be reentrant.

On some target machines, such as RISC machines and the 80386, the
standard system convention is to pass to the subroutine the address of
where to return the value.  On these machines, GNU CC has been
configured to be compatible with the standard compiler, when this method
is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.

GNU CC uses the system's standard convention for passing arguments.  On
some machines, the first few arguments are passed in registers; in
others, all are passed on the stack.  It would be possible to use
registers for argument passing on any machine, and this would probably
result in a significant speedup.  But the result would be complete
incompatibility with code that follows the standard convention.  So this
change is practical only if you are switching to GNU CC as the sole C
compiler for the system.  We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
compile the libraries with GNU CC.

If you use @code{longjmp}, beware of automatic variables.  ANSI C says that
automatic variables that are not declared @code{volatile} have undefined
values after a @code{longjmp}.  And this is all GNU CC promises to do,
because it is very difficult to restore register variables correctly, and
one of GNU CC's features is that it can put variables in registers without
your asking it to.

If you want a variable to be unaltered by @code{longjmp}, and you don't
want to write @code{volatile} because old C compilers don't accept it,
just take the address of the variable.  If a variable's address is ever
taken, even if just to compute it and ignore it, then the variable cannot
go in a register:

@example
@{
  int careful;
  &careful;
  @dots{}
@}
@end example

Code compiled with GNU CC may call certain library routines.  Most of
them handle arithmetic for which there are no instructions.  This
includes multiply and divide on some machines, and floating point
operations on any machine for which floating point support is disabled
with @samp{-msoft-float}.  Some standard parts of the C library, such as
@code{bcopy} or @code{memcpy}, are also called automatically.  The usual
function call interface is used for calling the library routines.

These library routines should be defined in the library @file{gnulib},
which GNU CC automatically searches whenever it links a program.  On
machines that have multiply and divide instructions, if hardware
floating point is in use, normally @file{gnulib} is not needed, but it
is searched just in case.

Each arithmetic function is defined in @file{gnulib.c} to use the
corresponding C arithmetic operator.  As long as the file is compiled
with another C compiler, which supports all the C arithmetic operators,
this file will work portably.  However, @file{gnulib.c} does not work if
compiled with GNU CC, because each arithmetic function would compile
into a call to itself!

@node Passes, RTL, Interface, Top
@chapter Passes and Files of the Compiler

The overall control structure of the compiler is in @file{toplev.c}.  This
file is responsible for initialization, decoding arguments, opening and
closing files, and sequencing the passes.

The parsing pass is invoked only once, to parse the entire input.  The RTL
intermediate code for a function is generated as the function is parsed, a
statement at a time.  Each statement is read in as a syntax tree and then
converted to RTL; then the storage for the tree for the statement is
reclaimed.  Storage for types (and the expressions for their sizes),
declarations, and a representation of the binding contours and how they nest,
remains until the function is finished being compiled; these are all needed
to output the debugging information.

Each time the parsing pass reads a complete function definition or
top-level declaration, it calls the function
@code{rest_of_compilation} or @code{rest_of_decl_compilation} in
@file{toplev.c}, which are responsible for all further processing
necessary, ending with output of the assembler language.  All other
compiler passes run, in sequence, within @code{rest_of_compilation}.
When that function returns from compiling a function definition, the
storage used for that function definition's compilation is entirely
freed, unless it is an inline function (@pxref{Inline}).

Here is a list of all the passes of the compiler and their source files.
Also included is a description of where debugging dumps can be requested
with @samp{-d} options.

@itemize @bullet
@item
Parsing.  This pass reads the entire text of a function definition,
constructing partial syntax trees.  This and RTL generation are no longer
truly separate passes (formerly they were), but it is easier to think
of them as separate.

The tree representation does not entirely follow C syntax, because it is
intended to support other languages as well.

C data type analysis is also done in this pass, and every tree node
that represents an expression has a data type attached.  Variables are
represented as declaration nodes.

Constant folding and associative-law simplifications are also done
during this pass.

The source files for parsing are @file{c-parse.y}, @file{c-decl.c},
@file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c},
@file{fold-const.c}, and @file{tree.c}.  The last three files are
intended to be language-independent.  There are also header files
@file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}.
The last two define the format of the tree representation.@refill

@item
RTL generation.  This is the conversion of syntax tree into RTL code.
It is actually done statement-by-statement during parsing, but for
most purposes it can be thought of as a separate pass.

This is where the bulk of target-parameter-dependent code is found,
since often it is necessary for strategies to apply only when certain
standard kinds of instructions are available.  The purpose of named
instruction patterns is to provide this information to the RTL
generation pass.

Optimization is done in this pass for @code{if}-conditions that are
comparisons, boolean operations or conditional expressions.  Tail
recursion is detected at this time also.  Decisions are made about how
best to arrange loops and how to output @code{switch} statements.

The source files for RTL generation are @file{stmt.c}, @file{expr.c},
@file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
Also, the file @file{insn-emit.c}, generated from the machine description
by the program @code{genemit}, is used in this pass.  The header files
@file{expr.h} is used for communication within this pass.@refill

The header files @file{insn-flags.h} and @file{insn-codes.h},
generated from the machine description by the programs @code{genflags}
and @code{gencodes}, tell this pass which standard names are available
for use and which patterns correspond to them.@refill

Aside from debugging information output, none of the following passes
refers to the tree structure representation of the function (only
part of which is saved).

The decision of whether the function can and should be expanded inline
in its subsequent callers is made at the end of rtl generation.  The
function must meet certain criteria, currently related to the size of
the function and the types and number of parameters it has.  Note that
this function may contain loops, recursive calls to itself
(tail-recursive functions can be inlined!), gotos, in short, all
constructs supported by GNU CC.

The option @samp{-dr} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.rtl} to
the input file name.

@item
Jump optimization.  This pass simplifies jumps to the following
instruction, jumps across jumps, and jumps to jumps.  It deletes
unreferenced labels and unreachable code, except that unreachable code
that contains a loop is not recognized as unreachable in this pass.
(Such loops are deleted later in the basic block analysis.)

Jump optimization is performed two or three times.  The first time is
immediately following RTL generation.  The second time is after CSE,
but only if CSE says repeated jump optimization is needed.  The
last time is right before the final pass.  That time, cross-jumping
and deletion of no-op move instructions are done together with the
optimizations described above.

The source file of this pass is @file{jump.c}.

The option @samp{-dj} causes a debugging dump of the RTL code after
this pass is run for the first time.  This dump file's name is made by
appending @samp{.jump} to the input file name.

@item
Register scan.  This pass finds the first and last use of each
register, as a guide for common subexpression elimination.  Its source
is in @file{regclass.c}.

@item
Common subexpression elimination.  This pass also does constant
propagation.  Its source file is @file{cse.c}.  If constant
propagation causes conditional jumps to become unconditional or to
become no-ops, jump optimization is run again when CSE is finished.

The option @samp{-ds} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.cse} to
the input file name.

@item
Loop optimization.  This pass moves constant expressions out of loops,
and optionally does strength-reduction as well.  Its source file is
@file{loop.c}.

The option @samp{-dL} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.loop} to
the input file name.

@item
Stupid register allocation is performed at this point in a
nonoptimizing compilation.  It does a little data flow analysis as
well.  When stupid register allocation is in use, the next pass
executed is the reloading pass; the others in between are skipped.
The source file is @file{stupid.c}.

@item
Data flow analysis (@file{flow.c}).  This pass divides the program
into basic blocks (and in the process deletes unreachable loops); then
it computes which pseudo-registers are live at each point in the
program, and makes the first instruction that uses a value point at
the instruction that computed the value.

This pass also deletes computations whose results are never used, and
combines memory references with add or subtract instructions to make
autoincrement or autodecrement addressing.

The option @samp{-df} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.flow} to
the input file name.  If stupid register allocation is in use, this
dump file reflects the full results of such allocation.

@item
Instruction combination (@file{combine.c}).  This pass attempts to
combine groups of two or three instructions that are related by data
flow into single instructions.  It combines the RTL expressions for
the instructions by substitution, simplifies the result using algebra,
and then attempts to match the result against the machine description.

The option @samp{-dc} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.combine}
to the input file name.

@item
Register class preferencing.  The RTL code is scanned to find out
which register class is best for each pseudo register.  The source
file is @file{regclass.c}.

@item
Local register allocation (@file{local-alloc.c}).  This pass allocates
hard registers to pseudo registers that are used only within one basic
block.  Because the basic block is linear, it can use fast and
powerful techniques to do a very good job.

The option @samp{-dl} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.lreg} to
the input file name.

@item
Global register allocation (@file{global-alloc.c}).  This pass
allocates hard registers for the remaining pseudo registers (those
whose life spans are not contained in one basic block).

@item
Reloading.  This pass renumbers pseudo registers with the hardware
registers numbers they were allocated.  Pseudo registers that did not
get hard registers are replaced with stack slots.  Then it finds
instructions that are invalid because a value has failed to end up in
a register, or has ended up in a register of the wrong kind.  It fixes
up these instructions by reloading the problematical values
temporarily into registers.  Additional instructions are generated to
do the copying.

Source files are @file{reload.c} and @file{reload1.c}, plus the header
@file{reload.h} used for communication between them.

The option @samp{-dg} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.greg} to
the input file name.

@item
Jump optimization is repeated, this time including cross-jumping
and deletion of no-op move instructions.

The option @samp{-dJ} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.jump2}
to the input file name.

@item
Delayed branch scheduling may be done at this point.  The source file
name is @file{dbranch.c}.

The option @samp{-dd} causes a debugging dump of the RTL code after
this pass.  This dump file's name is made by appending @samp{.dbr}
to the input file name.

@item
Final.  This pass outputs the assembler code for the function.  It is
also responsible for identifying spurious test and compare
instructions.  Machine-specific peephole optimizations are performed
at the same time.  The function entry and exit sequences are generated
directly as assembler code in this pass; they never exist as RTL.

The source files are @file{final.c} plus @file{insn-output.c}; the
latter is generated automatically from the machine description by the
tool @file{genoutput}.  The header file @file{conditions.h} is used
for communication between these files.

@item
Debugging information output.  This is run after final because it must
output the stack slot offsets for pseudo registers that did not get
hard registers.  Source files are @file{dbxout.c} for DBX symbol table
format and @file{symout.c} for GDB's own symbol table format.
@end itemize

Some additional files are used by all or many passes:

@itemize @bullet
@item
Every pass uses @file{machmode.def}, which defines the machine modes.

@item
All the passes that work with RTL use the header files @file{rtl.h}
and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
@code{gen*} also use these files to read and work with the machine
description RTL.

@item
Several passes refer to the header file @file{insn-config.h} which
contains a few parameters (C macro definitions) generated
automatically from the machine description RTL by the tool
@code{genconfig}.

@item
Several passes use the instruction recognizer, which consists of
@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
and @file{insn-extract.c} that are generated automatically from the
machine description by the tools @file{genrecog} and
@file{genextract}.@refill

@item
Several passes use the header files @file{regs.h} which defines the
information recorded about pseudo register usage, and @file{basic-block.h}
which defines the information recorded about basic blocks.

@item
@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
with a bit for each hard register, and some macros to manipulate it.
This type is just @code{int} if the machine has few enough hard registers;
otherwise it is an array of @code{int} and some of the macros expand
into loops.
@end itemize

@node RTL, Machine Desc, Passes, Top
@chapter RTL Representation

Most of the work of the compiler is done on an intermediate representation
called register transfer language.  In this language, the instructions to be
output are described, pretty much one by one, in an algebraic form that
describes what the instruction does.

RTL is inspired by Lisp lists.  It has both an internal form, made up of
structures that point at other structures, and a textual form that is used
in the machine description and in printed debugging dumps.  The textual
form uses nested parentheses to indicate the pointers in the internal form.

@menu
* RTL Objects::       Expressions vs vectors vs strings vs integers.
* Accessors::         Macros to access expression operands or vector elts.
* Flags::             Other flags in an RTL expression.
* Machine Modes::     Describing the size and format of a datum.
* Constants::         Expressions with constant values.
* Regs and Memory::   Expressions representing register contents or memory.
* Arithmetic::        Expressions representing arithmetic on other expressions.
* Comparisons::       Expressions representing comparison of expressions.
* Bit Fields::        Expressions representing bit-fields in memory or reg.
* Conversions::       Extending, truncating, floating or fixing.
* RTL Declarations::  Declaring volatility, constancy, etc.
* Side Effects::      Expressions for storing in registers, etc.
* Incdec::            Embedded side-effects for autoincrement addressing.
* Assembler::         Representing @code{asm} with operands.
* Insns::             Expression types for entire insns.
* Calls::             RTL representation of function call insns.
* Sharing::           Some expressions are unique; others *must* be copied.
@end menu

@node RTL Objects, Accessors, RTL, RTL
@section RTL Object Types

RTL uses four kinds of objects: expressions, integers, strings and vectors.
Expressions are the most important ones.  An RTL expression (``RTX'', for
short) is a C structure, but it is usually referred to with a pointer; a
type that is given the typedef name @code{rtx}.

An integer is simply an @code{int}, and a string is a @code{char *}.
Within RTL code, strings appear only inside @code{symbol_ref} expressions,
but they appear in other contexts in the RTL expressions that make up
machine descriptions.  Their written form uses decimal digits.

A string is a sequence of characters.  In core it is represented as a
@code{char *} in usual C fashion, and it is written in C syntax as well.
However, strings in RTL may never be null.  If you write an empty string in
a machine description, it is represented in core as a null pointer rather
than as a pointer to a null character.  In certain contexts, these null
pointers instead of strings are valid.

A vector contains an arbitrary, specified number of pointers to
expressions.  The number of elements in the vector is explicitly present in
the vector.  The written form of a vector consists of square brackets
(@samp{[@dots{}]}) surrounding the elements, in sequence and with
whitespace separating them.  Vectors of length zero are not created; null
pointers are used instead.

Expressions are classified by @dfn{expression codes} (also called RTX
codes).  The expression code is a name defined in @file{rtl.def}, which is
also (in upper case) a C enumeration constant.  The possible expression
codes and their meanings are machine-independent.  The code of an RTX can
be extracted with the macro @code{GET_CODE (@var{x})} and altered with
@code{PUT_CODE (@var{x}, @var{newcode})}.

The expression code determines how many operands the expression contains,
and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
by looking at an operand what kind of object it is.  Instead, you must know
from its context---from the expression code of the containing expression.
For example, in an expression of code @code{subreg}, the first operand is
to be regarded as an expression and the second operand as an integer.  In
an expression of code @code{plus}, there are two operands, both of which
are to be regarded as expressions.  In a @code{symbol_ref} expression,
there is one operand, which is to be regarded as a string.

Expressions are written as parentheses containing the name of the
expression type, its flags and machine mode if any, and then the operands
of the expression (separated by spaces).

Expression code names in the @samp{md} file are written in lower case,
but when they appear in C code they are written in upper case.  In this
manual, they are shown as follows: @code{const_int}.

In a few contexts a null pointer is valid where an expression is normally
wanted.  The written form of this is @code{(nil)}.

@node Accessors, Flags, RTL Objects, RTL
@section Access to Operands

For each expression type @file{rtl.def} specifies the number of contained
objects and their kinds, with four possibilities: @samp{e} for expression
(actually a pointer to an expression), @samp{i} for integer, @samp{s} for
string, and @samp{E} for vector of expressions.  The sequence of letters
for an expression code is called its @dfn{format}.  Thus, the format of
@code{subreg} is @samp{ei}.@refill

Two other format characters are used occasionally: @samp{u} and @samp{0}.
@samp{u} is equivalent to @samp{e} except that it is printed differently in
debugging dumps, and @samp{0} means a slot whose contents do not fit any
normal category.  @samp{0} slots are not printed at all in dumps, and are
often used in special ways by small parts of the compiler.@refill

There are macros to get the number of operands and the format of an
expression code:

@table @code
@item GET_RTX_LENGTH (@var{code})
Number of operands of an RTX of code @var{code}.

@item GET_RTX_FORMAT (@var{code})
The format of an RTX of code @var{code}, as a C string.
@end table

Operands of expressions are accessed using the macros @code{XEXP},
@code{XINT} and @code{XSTR}.  Each of these macros takes two arguments: an
expression-pointer (RTX) and an operand number (counting from zero).
Thus,@refill

@example
XEXP (@var{x}, 2)
@end example

@noindent
accesses operand 2 of expression @var{x}, as an expression.

@example
XINT (@var{x}, 2)
@end example

@noindent
accesses the same operand as an integer.  @code{XSTR}, used in the same
fashion, would access it as a string.

Any operand can be accessed as an integer, as an expression or as a string.
You must choose the correct method of access for the kind of value actually
stored in the operand.  You would do this based on the expression code of
the containing expression.  That is also how you would know how many
operands there are.

For example, if @var{x} is a @code{subreg} expression, you know that it has
two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
would get the address of the expression operand but cast as an integer;
that might occasionally be useful, but it would be cleaner to write
@code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
compile without error, and would return the second, integer operand cast as
an expression pointer, which would probably result in a crash when
accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
but this will access memory past the end of the expression with
unpredictable results.@refill

Access to operands which are vectors is more complicated.  You can use the
macro @code{XVEC} to get the vector-pointer itself, or the macros
@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
vector.

@table @code
@item XVEC (@var{exp}, @var{idx})
Access the vector-pointer which is operand number @var{idx} in @var{exp}.

@item XVECLEN (@var{exp}, @var{idx})
Access the length (number of elements) in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an @code{int}.

@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
Access element number @var{eltnum} in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an RTX.

It is up to you to make sure that @var{eltnum} is not negative
and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
@end table

All the macros defined in this section expand into lvalues and therefore
can be used to assign the operands, lengths and vector elements as well as
to access them.

@node Flags, Machine Modes, Accessors, RTL
@section Flags in an RTL Expression

RTL expressions contain several flags (one-bit bit-fields) that are used
in certain types of expression.  Most often they are accessed with the
following macros:

@table @code
@item EXTERNAL_SYMBOL_P (@var{x})
In a @code{symbol_ref} expression, nonzero if it corresponds to a variable
declared extern in the users code.  Zero for all other variables. Stored in
the @code{volatil} field and printed as @samp{/v}.

@item MEM_VOLATILE_P (@var{x})
In @code{mem} expressions, nonzero for volatile memory references.
Stored in the @code{volatil} field and printed as @samp{/v}.

@item MEM_IN_STRUCT_P (@var{x})
In @code{mem} expressions, nonzero for reference to an entire
structure, union or array, or to a component of one.  Zero for
references to a scalar variable or through a pointer to a scalar.
Stored in the @code{in_struct} field and printed as @samp{/s}.

@item REG_USER_VAR_P (@var{x})
In a @code{reg}, nonzero if it corresponds to a variable present in
the user's source code.  Zero for temporaries generated internally by
the compiler.  Stored in the @code{volatil} field and printed as
@samp{/v}.

@item REG_FUNCTION_VALUE_P (@var{x})
Nonzero in a @code{reg} if it is the place in which this function's
value is going to be returned.  (This happens only in a hard
register.)  Stored in the @code{integrated} field and printed as
@samp{/i}.

The same hard register may be used also for collecting the values of
functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
in this kind of use.

@item RTX_UNCHANGING_P (@var{x})
Nonzero in a @code{reg} or @code{mem} if the value is not changed
explicitly by the current function.  (If it is a memory reference then
it may be changed by other functions or by aliasing.)  Stored in the
@code{unchanging} field and printed as @samp{/u}.

@item RTX_INTEGRATED_P (@var{insn})
Nonzero in an insn if it resulted from an in-line function call.
Stored in the @code{integrated} field and printed as @samp{/i}.  This
may be deleted; nothing currently depends on it.

@item INSN_DELETED_P (@var{insn})
In an insn, nonzero if the insn has been deleted.  Stored in the
@code{volatil} field and printed as @samp{/v}.

@item CONSTANT_POOL_ADDRESS_P (@var{x})
Nonzero in a @code{symbol_ref} if it refers to part of the current
function's ``constants pool''.  These are addresses close to the
beginning of the function, and GNU CC assumes they can be addressed
directly (perhaps with the help of base registers).  Stored in the
@code{unchanging} field and printed as @samp{/u}.
@end table

These are the fields which the above macros refer to:

@table @code
@item used
This flag is used only momentarily, at the end of RTL generation for a
function, to count the number of times an expression appears in insns.
Expressions that appear more than once are copied, according to the
rules for shared structure (@pxref{Sharing}).

@item volatil
This flag is used in @code{mem},@code{symbol_ref} and @code{reg} expressions
and in insns.  In RTL dump files, it is printed as @samp{/v}.

In a @code{mem} expression, it is 1 if the memory reference is volatile.
Volatile memory references may not be deleted, reordered or combined.

In a @code{reg} expression, it is 1 if the value is a user-level variable.
0 indicates an internal compiler temporary.

In a @code{symbol_ref} expression, it is 1 if the symbol is declared
@code{extern}.

In an insn, 1 means the insn has been deleted.

@item in_struct
This flag is used in @code{mem} expressions.  It is 1 if the memory
datum referred to is all or part of a structure or array; 0 if it is (or
might be) a scalar variable.  A reference through a C pointer has 0
because the pointer might point to a scalar variable.

This information allows the compiler to determine something about possible
cases of aliasing.

In an RTL dump, this flag is represented as @samp{/s}.

@item unchanging
This flag is used in @code{reg} and @code{mem} expressions.  1 means
that the value of the expression never changes (at least within the
current function).

In an RTL dump, this flag is represented as @samp{/u}.

@item integrated
In some kinds of expressions, including insns, this flag means the
rtl was produced by procedure integration.

In a @code{reg} expression, this flag indicates the register
containing the value to be returned by the current function.  On
machines that pass parameters in registers, the same register number
may be used for parameters as well, but this flag is not set on such
uses.
@end table

@node Machine Modes, Constants, Flags, RTL
@section Machine Modes

A machine mode describes a size of data object and the representation used
for it.  In the C code, machine modes are represented by an enumeration
type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
expression has room for a machine mode and so do certain kinds of tree
expressions (declarations and types, to be precise).

In debugging dumps and machine descriptions, the machine mode of an RTL
expression is written after the expression code with a colon to separate
them.  The letters @samp{mode} which appear at the end of each machine mode
name are omitted.  For example, @code{(reg:SI 38)} is a @code{reg}
expression with machine mode @code{SImode}.  If the mode is
@code{VOIDmode}, it is not written at all.

Here is a table of machine modes.

@table @code
@item QImode
``Quarter-Integer'' mode represents a single byte treated as an integer.

@item HImode
``Half-Integer'' mode represents a two-byte integer.

@item PSImode
``Partial Single Integer'' mode represents an integer which occupies
four bytes but which doesn't really use all four.  On some machines,
this is the right mode to use for pointers.

@item SImode
``Single Integer'' mode represents a four-byte integer.

@item PDImode
``Partial Double Integer'' mode represents an integer which occupies
eight bytes but which doesn't really use all eight.  On some machines,
this is the right mode to use for certain pointers.

@item DImode
``Double Integer'' mode represents an eight-byte integer.

@item TImode
``Tetra Integer'' (?) mode represents a sixteen-byte integer.

@item SFmode
``Single Floating'' mode represents a single-precision (four byte) floating
point number.

@item DFmode
``Double Floating'' mode represents a double-precision (eight byte) floating
point number.

@item XFmode
``Extended Floating'' mode represents a triple-precision (twelve byte)
floating point number.  This mode is used for IEEE extended floating
point.

@item TFmode
``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
floating point number.

@item BLKmode
``Block'' mode represents values that are aggregates to which none of
the other modes apply.  In RTL, only memory references can have this mode,
and only if they appear in string-move or vector instructions.  On machines
which have no such instructions, @code{BLKmode} will not appear in RTL.

@item VOIDmode
Void mode means the absence of a mode or an unspecified mode.
For example, RTL expressions of code @code{const_int} have mode
@code{VOIDmode} because they can be taken to have whatever mode the context
requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
the absence of any mode.

@item EPmode
``Entry Pointer'' mode is intended to be used for function variables in
Pascal and other block structured languages.  Such values contain
both a function address and a static chain pointer for access to
automatic variables of outer levels.  This mode is only partially
implemented since C does not use it.

@item CSImode@r{, @dots{}}
``Complex Single Integer'' mode stands for a complex number represented
as a pair of @code{SImode} integers.  Any of the integer and floating modes
may have @samp{C} prefixed to its name to obtain a complex number mode.
For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
Since C does not support complex numbers, these machine modes are only
partially implemented.

@item BImode
This is the machine mode of a bit-field in a structure.  It is used
only in the syntax tree, never in RTL, and in the syntax tree it appears
only in declaration nodes.  In C, it appears only in @code{FIELD_DECL}
nodes for structure fields defined with a bit size.
@end table

The machine description defines @code{Pmode} as a C macro which expands
into the machine mode used for addresses.  Normally this is @code{SImode}.

The only modes which a machine description @i{must} support are
@code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}.  The
compiler will attempt to use @code{DImode} for two-word structures and
unions, but this can be prevented by overriding the definition of
@code{MAX_FIXED_MODE_SIZE}.  Likewise, you can arrange for the C type
@code{short int} to avoid using @code{HImode}.  In the long term it
might be desirable to make the set of available machine modes
machine-dependent and eliminate all assumptions about specific machine
modes or their uses from the machine-independent code of the compiler.

To help begin this process, the machine modes are divided into mode
classes.  These are represented by the enumeration type @code{enum
mode_class} defined in @file{rtl.h}.  The possible mode classes are:

@table @code
@item MODE_INT
Integer modes.  By default these are @code{QImode}, @code{HImode},
@code{SImode}, @code{DImode}, @code{TImode}, and also @code{BImode}.

@item MODE_FLOAT
Floating-point modes.  By default these are @code{QFmode},
@code{HFmode}, @code{SFmode}, @code{DFmode} and @code{TFmode}, but the
MC68881 also defines @code{XFmode} to be an 80-bit extended-precision
floating-point mode.

@item MODE_COMPLEX_INT
Complex integer modes.  By default these are @code{CQImode},
@code{CHImode}, @code{CSImode}, @code{CDImode} and @code{CTImode}.

@item MODE_COMPLEX_FLOAT
Complex floating-point modes.  By default these are @code{CQFmode},
@code{CHFmode}, @code{CSFmode}, @code{CDFmode} and @code{CTFmode},

@item MODE_FUNCTION
Algol or Pascal function variables including a static chain.
(These are not currently implemented).

@item MODE_RANDOM
This is a catchall mode class for modes which don't fit into the above
classes.  Currently @code{VOIDmode}, @code{BLKmode} and @code{EPmode}
are in @code{MODE_RANDOM}.
@end table

Here are some C macros that relate to machine modes:

@table @code
@item GET_MODE (@var{x})
Returns the machine mode of the RTX @var{x}.

@item PUT_MODE (@var{x}, @var{newmode})
Alters the machine mode of the RTX @var{x} to be @var{newmode}.

@item NUM_MACHINE_MODES
Stands for the number of machine modes available on the target
machine.  This is one greater than the largest numeric value of any
machine mode.

@item GET_MODE_NAME (@var{m})
Returns the name of mode @var{m} as a string.

@item GET_MODE_CLASS (@var{m})
Returns the mode class of mode @var{m}.

@item GET_MODE_SIZE (@var{m})
Returns the size in bytes of a datum of mode @var{m}.

@item GET_MODE_BITSIZE (@var{m})
Returns the size in bits of a datum of mode @var{m}.

@item GET_MODE_UNIT_SIZE (@var{m})
Returns the size in bits of the subunits of a datum of mode @var{m}.
This is the same as @code{GET_MODE_SIZE} except in the case of
complex modes and @code{EPmode}.  For them, the unit size is the
size of the real or imaginary part, or the size of the function
pointer or the context pointer.
@end table

@node Constants, Regs and Memory, Machine Modes, RTL
@section Constant Expression Types

The simplest RTL expressions are those that represent constant values.

@table @code
@item (const_int @var{i})
This type of expression represents the integer value @var{i}.  @var{i}
is customarily accessed with the macro @code{INTVAL} as in
@code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.

There is only one expression object for the integer value zero;
it is the value of the variable @code{const0_rtx}.  Likewise, the
only expression for integer value one is found in @code{const1_rtx}.
Any attempt to create an expression of code @code{const_int} and
value zero or one will return @code{const0_rtx} or @code{const1_rtx}
as appropriate.

@item (const_double:@var{m} @var{i0} @var{i1})
Represents a 64-bit constant of mode @var{m}.  All floating point
constants are represented in this way, and so are 64-bit @code{DImode}
integer constants.

The two integers @var{i0} and @var{i1} together contain the bits of
the value.  If the constant is floating point (either single or double
precision), then they represent a @code{double}.  To convert them to a
@code{double}, do

@example
union @{ double d; int i[2];@} u;
u.i[0] = CONST_DOUBLE_LOW(x);
u.i[1] = CONST_DOUBLE_HIGH(x);
@end example

@noindent
and then refer to @code{u.d}.

The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
@code{const_double} expressions with value 0, in modes @code{DFmode}
and @code{SFmode}, respectively.  The macro @code{CONST0_RTX
(@var{mode})} refers to a @code{const_double} expression with value 0
in mode @var{mode}.  The mode @var{mode} must be of mode class
@code{MODE_FLOAT}.

@item (symbol_ref @var{symbol})
Represents the value of an assembler label for data.  @var{symbol} is
a string that describes the name of the assembler label.  If it starts
with a @samp{*}, the label is the rest of @var{symbol} not including
the @samp{*}.  Otherwise, the label is @var{symbol}, prefixed with
@samp{_}.

@item (label_ref @var{label})
Represents the value of an assembler label for code.  It contains one
operand, an expression, which must be a @code{code_label} that appears
in the instruction sequence to identify the place where the label
should go.

The reason for using a distinct expression type for code label
references is so that jump optimization can distinguish them.

@item (const @var{exp})
Represents a constant that is the result of an assembly-time
arithmetic computation.  The operand, @var{exp}, is an expression that
contains only constants (@code{const_int}, @code{symbol_ref} and
@code{label_ref} expressions) combined with @code{plus} and
@code{minus}.  However, not all combinations are valid, since the
assembler cannot do arbitrary arithmetic on relocatable symbols.
@end table

@node Regs and Memory, Arithmetic, Constants, RTL
@section Registers and Memory

Here are the RTL expression types for describing access to machine
registers and to main memory.

@table @code
@item (reg:@var{m} @var{n})
For small values of the integer @var{n} (less than
@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
register number @var{n}: a @dfn{hard register}.  For larger values of
@var{n}, it stands for a temporary value or @dfn{pseudo register}.
The compiler's strategy is to generate code assuming an unlimited
number of such pseudo registers, and later convert them into hard
registers or into memory references.

The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
description, since the number of hard registers on the machine is an
invariant characteristic of the machine.  Note, however, that not
all of the machine registers must be general registers.  All the
machine registers that can be used for storage of data are given
hard register numbers, even those that can be used only in certain
instructions or can hold only certain types of data.

Each pseudo register number used in a function's RTL code is
represented by a unique @code{reg} expression.

@var{m} is the machine mode of the reference.  It is necessary because
machines can generally refer to each register in more than one mode.
For example, a register may contain a full word but there may be
instructions to refer to it as a half word or as a single byte, as
well as instructions to refer to it as a floating point number of
various precisions.

Even for a register that the machine can access in only one mode,
the mode must always be specified.

A hard register may be accessed in various modes throughout one
function, but each pseudo register is given a natural mode
and is accessed only in that mode.  When it is necessary to describe
an access to a pseudo register using a nonnatural mode, a @code{subreg}
expression is used.

A @code{reg} expression with a machine mode that specifies more than
one word of data may actually stand for several consecutive registers.
If in addition the register number specifies a hardware register, then
it actually represents several consecutive hardware registers starting
with the specified one.

Such multi-word hardware register @code{reg} expressions must not be live
across the boundary of a basic block.  The lifetime analysis pass does not
know how to record properly that several consecutive registers are
actually live there, and therefore register allocation would be confused.
The CSE pass must go out of its way to make sure the situation does
not arise.

@item (subreg:@var{m} @var{reg} @var{wordnum})
@code{subreg} expressions are used to refer to a register in a machine
mode other than its natural one, or to refer to one register of
a multi-word @code{reg} that actually refers to several registers.

Each pseudo-register has a natural mode.  If it is necessary to
operate on it in a different mode---for example, to perform a fullword
move instruction on a pseudo-register that contains a single
byte---the pseudo-register must be enclosed in a @code{subreg}.  In
such a case, @var{wordnum} is zero.

The other use of @code{subreg} is to extract the individual registers
of a multi-register value.  Machine modes such as @code{DImode} and
@code{EPmode} indicate values longer than a word, values which usually
require two consecutive registers.  To access one of the registers,
use a @code{subreg} with mode @code{SImode} and a @var{wordnum} that
says which register.

The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
that word number zero is the most significant part; otherwise, it is
the least significant part.

Between the combiner pass and the reload pass, it is possible to have
a @code{subreg} which contains a @code{mem} instead of a @code{reg} as
its first operand.  The reload pass eliminates these cases by
reloading the @code{mem} into a suitable register.

Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
using a @code{subreg}.  On some machines the most significant part of a
@code{DFmode} value does not have the same format as a single-precision
floating value.

@item (cc0)
This refers to the machine's condition code register.  It has no
operands and may not have a machine mode.  There are two ways to use it:

@itemize @bullet
@item
To stand for a complete set of condition code flags.  This is best on
most machines, where each comparison sets the entire series of flags.

With this technique, @code{(cc0)} may be validly used in only two
contexts: as the destination of an assignment (in test and compare
instructions) and in comparison operators comparing against zero
(@code{const_int} with value zero; that is to say, @code{const0_rtx}).

@item
To stand for a single flag that is the result of a single condition.
This is useful on machines that have only a single flag bit, and in
which comparison instructions must specify the condition to test.

With this technique, @code{(cc0)} may be validly used in only two
contexts: as the destination of an assignment (in test and compare
instructions) where the source is a comparison operator, and as the
first operand of @code{if_then_else} (in a conditional branch).
@end itemize

There is only one expression object of code @code{cc0}; it is the
value of the variable @code{cc0_rtx}.  Any attempt to create an
expression of code @code{cc0} will return @code{cc0_rtx}.

One special thing about the condition code register is that
instructions can set it implicitly.  On many machines, nearly all
instructions set the condition code based on the value that they
compute or store.  It is not necessary to record these actions
explicitly in the RTL because the machine description includes a
prescription for recognizing the instructions that do so (by means of
the macro @code{NOTICE_UPDATE_CC}).  Only instructions whose sole
purpose is to set the condition code, and instructions that use the
condition code, need mention @code{(cc0)}.

In some cases, better code may result from recognizing combinations or
peepholes that include instructions that set the condition codes, even
in cases where some reloading is inevitable.  For examples, search for
@samp{addcc} and @samp{andcc} in @file{sparc.md}.

@item (pc)
This represents the machine's program counter.  It has no operands and
may not have a machine mode.  @code{(pc)} may be validly used only in
certain specific contexts in jump instructions.

There is only one expression object of code @code{pc}; it is the value
of the variable @code{pc_rtx}.  Any attempt to create an expression of
code @code{pc} will return @code{pc_rtx}.

All instructions that do not jump alter the program counter implicitly
by incrementing it, but there is no need to mention this in the RTL.

@item (mem:@var{m} @var{addr})
This RTX represents a reference to main memory at an address
represented by the expression @var{addr}.  @var{m} specifies how large
a unit of memory is accessed.
@end table

@node Arithmetic, Comparisons, Regs and Memory, RTL
@section RTL Expressions for Arithmetic

@table @code
@item (plus:@var{m} @var{x} @var{y})
Represents the sum of the values represented by @var{x} and @var{y}
carried out in machine mode @var{m}.  This is valid only if
@var{x} and @var{y} both are valid for mode @var{m}.

@item (minus:@var{m} @var{x} @var{y})
Like @code{plus} but represents subtraction.

@item (compare @var{x} @var{y})
Represents the result of subtracting @var{y} from @var{x}
for purposes of comparison.  The absence of a machine mode
in the @code{compare} expression indicates that the result is
computed without overflow, as if with infinite precision.

Of course, machines can't really subtract with infinite precision.
However, they can pretend to do so when only the sign of the
result will be used, which is the case when the result is stored
in @code{(cc0)}.  And that is the only way this kind of expression
may validly be used: as a value to be stored in the condition codes.

@item (neg:@var{m} @var{x})
Represents the negation (subtraction from zero) of the value
represented by @var{x}, carried out in mode @var{m}.  @var{x} must be
valid for mode @var{m}.

@item (mult:@var{m} @var{x} @var{y})
Represents the signed product of the values represented by @var{x} and
@var{y} carried out in machine mode @var{m}.  If
@var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
size-preserving multiplication.  Alternatively, both @var{x} and @var{y}
may be valid for a different, narrower mode.  This represents the
kind of multiplication that generates a product wider than the operands.
Widening multiplication and same-size multiplication are completely
distinct and supported by different machine instructions; machines may
support one but not the other.@refill

@code{mult} may be used for floating point multiplication as well.
Then @var{m} is a floating point machine mode.

@item (umult:@var{m} @var{x} @var{y})
Like @code{mult} but represents unsigned multiplication.  It may be
used in both same-size and widening forms, like @code{mult}.
@code{umult} is used only for fixed-point multiplication.

@item (div:@var{m} @var{x} @var{y})
Represents the quotient in signed division of @var{x} by @var{y},
carried out in machine mode @var{m}.  If @var{m} is a floating-point
mode, it represents the exact quotient; otherwise, the integerized
quotient.  If @var{x} and @var{y} are both valid for mode @var{m},
this is ordinary size-preserving division.  Some machines have
division instructions in which the operands and quotient widths are
not all the same; such instructions are represented by @code{div}
expressions in which the machine modes are not all the same.

@item (udiv:@var{m} @var{x} @var{y})
Like @code{div} but represents unsigned division.

@item (mod:@var{m} @var{x} @var{y})
@itemx (umod:@var{m} @var{x} @var{y})
Like @code{div} and @code{udiv} but represent the remainder instead of
the quotient.

@item (not:@var{m} @var{x})
Represents the bitwise complement of the value represented by @var{x},
carried out in mode @var{m}, which must be a fixed-point machine mode.
@var{x} must be valid for mode @var{m}, which must be a fixed-point mode.

@item (and:@var{m} @var{x} @var{y})
Represents the bitwise logical-and of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (ior:@var{m} @var{x} @var{y})
Represents the bitwise inclusive-or of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (xor:@var{m} @var{x} @var{y})
Represents the bitwise exclusive-or of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (lshift:@var{m} @var{x} @var{c})
Represents the result of logically shifting @var{x} left by @var{c}
places.  @var{x} must be valid for the mode @var{m}, a fixed-point
machine mode.  @var{c} must be valid for a fixed-point mode;
which mode is determined by the mode called for in the machine
description entry for the left-shift instruction.  For example,
on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.

On some machines, negative values of @var{c} may be meaningful; this
is why logical left shift and arithmetic left shift are distinguished.
For example, Vaxes have no right-shift instructions, and right shifts
are represented as left-shift instructions whose counts happen
to be negative constants or else computed (in a previous instruction)
by negation.

@item (ashift:@var{m} @var{x} @var{c})
Like @code{lshift} but for arithmetic left shift.

@item (lshiftrt:@var{m} @var{x} @var{c})
@itemx (ashiftrt:@var{m} @var{x} @var{c})
Like @code{lshift} and @code{ashift} but for right shift.

@item (rotate:@var{m} @var{x} @var{c})
@itemx (rotatert:@var{m} @var{x} @var{c})
Similar but represent left and right rotate.

@item (abs:@var{m} @var{x})
Represents the absolute value of @var{x}, computed in mode @var{m}.
@var{x} must be valid for @var{m}.

@item (sqrt:@var{m} @var{x})
Represents the square root of @var{x}, computed in mode @var{m}.
@var{x} must be valid for @var{m}.  Most often @var{m} will be
a floating point mode.

@item (ffs:@var{m} @var{x})
Represents one plus the index of the least significant 1-bit in
@var{x}, represented as an integer of mode @var{m}.  (The value is
zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
depending on the target machine, various mode combinations may be
valid.
@end table

@node Comparisons, Bit Fields, Arithmetic, RTL
@section Comparison Operations

Comparison operators test a relation on two operands and are considered
to represent a machine-dependent nonzero value (@code{STORE_FLAG_VALUE})
if the relation holds, or zero if it does not.  The mode of the
comparison is determined by the operands; they must both be valid for a
common machine mode.  A comparison with both operands constant would be
invalid as the machine mode could not be deduced from it, but such a
comparison should never exist in RTL due to constant folding.

Inequality comparisons come in two flavors, signed and unsigned.  Thus,
there are distinct expression codes @code{gt} and @code{gtu} for signed and
unsigned greater-than.  These can produce different results for the same
pair of integer values: for example, 1 is signed greater-than -1 but not
unsigned greater-than, because -1 when regarded as unsigned is actually
@code{0xffffffff} which is greater than 1.

The signed comparisons are also used for floating point values.  Floating
point comparisons are distinguished by the machine modes of the operands.

The comparison operators may be used to compare the condition codes
@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such a
construct actually refers to the result of the preceding instruction in
which the condition codes were set.  The above example stands for 1 if the
condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
Although the same comparison operators are used for this as may be used in
other contexts on actual data, no confusion can result since the machine
description would never allow both kinds of uses in the same context.

@table @code
@item (eq @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are equal,
otherwise 0.

@item (ne @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are not equal,
otherwise 0.

@item (gt @var{x} @var{y})
1 if the @var{x} is greater than @var{y}.  If they are fixed-point,
the comparison is done in a signed sense.

@item (gtu @var{x} @var{y})
Like @code{gt} but does unsigned comparison, on fixed-point numbers only.

@item (lt @var{x} @var{y})
@item (ltu @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``less than''.

@item (ge @var{x} @var{y})
@item (geu @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``greater than or equal''.

@item (le @var{x} @var{y})
@item (leu @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``less than or equal''.

@item (if_then_else @var{cond} @var{then} @var{else})
This is not a comparison operation but is listed here because it is
always used in conjunction with a comparison operation.  To be
precise, @var{cond} is a comparison expression.  This expression
represents a choice, according to @var{cond}, between the value
represented by @var{then} and the one represented by @var{else}.

On most machines, @code{if_then_else} expressions are valid only
to express conditional jumps.
@end table

@node Bit Fields, Conversions, Comparisons, RTL
@section Bit-fields

Special expression codes exist to represent bit-field instructions.
These types of expressions are lvalues in RTL; they may appear
on the left side of an assignment, indicating insertion of a value
into the specified bit field.

@table @code
@item (sign_extract:SI @var{loc} @var{size} @var{pos})
This represents a reference to a sign-extended bit-field contained or
starting in @var{loc} (a memory or register reference).  The bit field
is @var{size} bits wide and starts at bit @var{pos}.  The compilation
option @code{BITS_BIG_ENDIAN} says which end of the memory unit
@var{pos} counts from.

Which machine modes are valid for @var{loc} depends on the machine,
but typically @var{loc} should be a single byte when in memory
or a full word in a register.

@item (zero_extract:SI @var{loc} @var{size} @var{pos})
Like @code{sign_extract} but refers to an unsigned or zero-extended
bit field.  The same sequence of bits are extracted, but they
are filled to an entire word with zeros instead of by sign-extension.
@end table

@node Conversions, RTL Declarations, Bit Fields, RTL
@section Conversions

All conversions between machine modes must be represented by
explicit conversion operations.  For example, an expression
which is the sum of a byte and a full word cannot be written as
@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
operation requires two operands of the same machine mode.
Therefore, the byte-sized operand is enclosed in a conversion
operation, as in

@example
(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
@end example

The conversion operation is not a mere placeholder, because there
may be more than one way of converting from a given starting mode
to the desired final mode.  The conversion operation code says how
to do it.

@table @code
@item (sign_extend:@var{m} @var{x})
Represents the result of sign-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@item (zero_extend:@var{m} @var{x})
Represents the result of zero-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@item (float_extend:@var{m} @var{x})
Represents the result of extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode narrower than @var{m}.

@item (truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode wider than @var{m}.

@item (float_truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode wider than @var{m}.

@item (float:@var{m} @var{x})
Represents the result of converting fixed point value @var{x},
regarded as signed, to floating point mode @var{m}.

@item (unsigned_float:@var{m} @var{x})
Represents the result of converting fixed point value @var{x},
regarded as unsigned, to floating point mode @var{m}.

@item (fix:@var{m} @var{x})
When @var{m} is a fixed point mode, represents the result of
converting floating point value @var{x} to mode @var{m}, regarded as
signed.  How rounding is done is not specified, so this operation may
be used validly in compiling C code only for integer-valued operands.

@item (unsigned_fix:@var{m} @var{x})
Represents the result of converting floating point value @var{x} to
fixed point mode @var{m}, regarded as unsigned.  How rounding is done
is not specified.

@item (fix:@var{m} @var{x})
When @var{m} is a floating point mode, represents the result of
converting floating point value @var{x} (valid for mode @var{m}) to an
integer, still represented in floating point mode @var{m}, by rounding
towards zero.
@end table

@node RTL Declarations, Side Effects, Conversions, RTL
@section Declarations

Declaration expression codes do not represent arithmetic operations
but rather state assertions about their operands.

@table @code
@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
This expression code is used in only one context: operand 0 of a
@code{set} expression.  In addition, the operand of this expression
must be a @code{subreg} expression.

The presence of @code{strict_low_part} says that the part of the
register which is meaningful in mode @var{n}, but is not part of
mode @var{m}, is not to be altered.  Normally, an assignment to such
a subreg is allowed to have undefined effects on the rest of the
register when @var{m} is less than a word.
@end table

@node Side Effects, Incdec, RTL Declarations, RTL
@section Side Effect Expressions

The expression codes described so far represent values, not actions.
But machine instructions never produce values; they are meaningful
only for their side effects on the state of the machine.  Special
expression codes are used to represent side effects.

The body of an instruction is always one of these side effect codes;
the codes described above, which represent values, appear only as
the operands of these.

@table @code
@item (set @var{lval} @var{x})
Represents the action of storing the value of @var{x} into the place
represented by @var{lval}.  @var{lval} must be an expression
representing a place that can be stored in: @code{reg} (or
@code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
@code{cc0}.@refill

If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
machine mode; then @var{x} must be valid for that mode.@refill

If @var{lval} is a @code{reg} whose machine mode is less than the full
width of the register, then it means that the part of the register
specified by the machine mode is given the specified value and the
rest of the register receives an undefined value.  Likewise, if
@var{lval} is a @code{subreg} whose machine mode is narrower than
@code{SImode}, the rest of the register can be changed in an undefined way.

If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
part of the register specified by the machine mode of the
@code{subreg} is given the value @var{x} and the rest of the register
is not changed.@refill

If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
have any mode.  This represents a ``test'' or ``compare'' instruction.@refill

If @var{lval} is @code{(pc)}, we have a jump instruction, and the
possibilities for @var{x} are very limited.  It may be a
@code{label_ref} expression (unconditional jump).  It may be an
@code{if_then_else} (conditional jump), in which case either the
second or the third operand must be @code{(pc)} (for the case which
does not jump) and the other of the two must be a @code{label_ref}
(for the case which does jump).  @var{x} may also be a @code{mem} or
@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
@code{mem}; these unusual patterns are used to represent jumps through
branch tables.@refill

@item (return)
Represents a return from the current function, on machines where this
can be done with one instruction, such as Vaxes.  On machines where a
multi-instruction ``epilogue'' must be executed in order to return
from the function, returning is done by jumping to a label which
precedes the epilogue, and the @code{return} expression code is never
used.

@item (call @var{function} @var{nargs})
Represents a function call.  @var{function} is a @code{mem} expression
whose address is the address of the function to be called.
@var{nargs} is an expression which can be used for two purposes: on
some machines it represents the number of bytes of stack argument; on
others, it represents the number of argument registers.

Each machine has a standard machine mode which @var{function} must
have.  The machine description defines macro @code{FUNCTION_MODE} to
expand into the requisite mode name.  The purpose of this mode is to
specify what kind of addressing is allowed, on machines where the
allowed kinds of addressing depend on the machine mode being
addressed.

@item (clobber @var{x})
Represents the storing or possible storing of an unpredictable,
undescribed value into @var{x}, which must be a @code{reg} or
@code{mem} expression.

One place this is used is in string instructions that store standard
values into particular hard registers.  It may not be worth the
trouble to describe the values that are stored, but it is essential to
inform the compiler that the registers will be altered, lest it
attempt to keep data in them across the string instruction.

@var{x} may also be null---a null C pointer, no expression at all.
Such a @code{(clobber (null))} expression means that all memory
locations must be presumed clobbered.

Note that the machine description classifies certain hard registers as
``call-clobbered''.  All function call instructions are assumed by
default to clobber these registers, so there is no need to use
@code{clobber} expressions to indicate this fact.  Also, each function
call is assumed to have the potential to alter any memory location,
unless the function is declared @code{const}.

When a @code{clobber} expression for a register appears inside a
@code{parallel} with other side effects, GNU CC guarantees that the
register is unoccupied both before and after that insn.  Therefore, it
is safe for the assembler code produced by the insn to use the
register as a temporary.  You can clobber either a specific hard
register or a pseudo register; in the latter case, GNU CC will
allocate a hard register that is available there for use as a
temporary.

If you clobber a pseudo register in this way, use a pseudo register
which appears nowhere else---generate a new one each time.  Otherwise,
you may confuse CSE.

There is one other known use for clobbering a pseudo register in a
@code{parallel}: when one of the input operands of the insn is also
clobbered by the insn.  In this case, using the same pseudo register in
the clobber and elsewhere in the insn produces the expected results.

@item (use @var{x})
Represents the use of the value of @var{x}.  It indicates that the
value in @var{x} at this point in the program is needed, even though
it may not be apparent why this is so.  Therefore, the compiler will
not attempt to delete previous instructions whose only effect is to
store a value in @var{x}.  @var{x} must be a @code{reg} expression.

@item (parallel [@var{x0} @var{x1} @dots{}])
Represents several side effects performed in parallel.  The square
brackets stand for a vector; the operand of @code{parallel} is a
vector of expressions.  @var{x0}, @var{x1} and so on are individual
side effect expressions---expressions of code @code{set}, @code{call},
@code{return}, @code{clobber} or @code{use}.@refill

``In parallel'' means that first all the values used in the individual
side-effects are computed, and second all the actual side-effects are
performed.  For example,

@example
(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
           (set (mem:SI (reg:SI 1)) (reg:SI 1))])
@end example

@noindent
says unambiguously that the values of hard register 1 and the memory
location addressed by it are interchanged.  In both places where
@code{(reg:SI 1)} appears as a memory address it refers to the value
in register 1 @emph{before} the execution of the insn.

It follows that it is @emph{incorrect} to use @code{parallel} and
expect the result of one @code{set} to be available for the next one.
For example, people sometimes attempt to represent a jump-if-zero
instruction this way:

@example
(parallel [(set (cc0) (reg:SI 34))
           (set (pc) (if_then_else
                        (eq (cc0) (const_int 0))
                        (label_ref @dots{})
                        (pc)))])
@end example

@noindent
But this is incorrect, because it says that the jump condition depends
on the condition code value @emph{before} this instruction, not on the
new value that is set by this instruction.

Peephole optimization, which takes place in together with final assembly
code output, can produce insns whose patterns consist of a @code{parallel}
whose elements are the operands needed to output the resulting
assembler code---often @code{reg}, @code{mem} or constant expressions.
This would not be well-formed RTL at any other stage in compilation,
but it is ok then because no further optimization remains to be done.
However, the definition of the macro @code{NOTICE_UPDATE_CC} must
deal with such insns if you define any peephole optimizations.

@item (sequence [@var{insns} @dots{}])
Represents a sequence of insns.  Each of the @var{insns} that appears
in the vector is suitable for appearing in the chain of insns, so it
must be an @code{insn}, @code{jump_insn}, @code{call_insn},
@code{code_label}, @code{barrier} or @code{note}.

A @code{sequence} RTX never appears in an actual insn.  It represents
the sequence of insns that result from a @code{define_expand}
@emph{before} those insns are passed to @code{emit_insn} to insert
them in the chain of insns.  When actually inserted, the individual
sub-insns are separated out and the @code{sequence} is forgotten.
@end table

Three expression codes appear in place of a side effect, as the body of an
insn, though strictly speaking they do not describe side effects as such:

@table @code
@item (asm_input @var{s})
Represents literal assembler code as described by the string @var{s}.

@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
Represents a table of jump addresses.  The vector elements @var{lr0},
etc., are @code{label_ref} expressions.  The mode @var{m} specifies
how much space is given to each address; normally @var{m} would be
@code{Pmode}.

@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
Represents a table of jump addresses expressed as offsets from
@var{base}.  The vector elements @var{lr0}, etc., are @code{label_ref}
expressions and so is @var{base}.  The mode @var{m} specifies how much
space is given to each address-difference.@refill
@end table

@node Incdec, Assembler, Side Effects, RTL
@section Embedded Side-Effects on Addresses

Four special side-effect expression codes appear as memory addresses.

@table @code
@item (pre_dec:@var{m} @var{x})
Represents the side effect of decrementing @var{x} by a standard
amount and represents also the value that @var{x} has after being
decremented.  @var{x} must be a @code{reg} or @code{mem}, but most
machines allow only a @code{reg}.  @var{m} must be the machine mode
for pointers on the machine in use.  The amount @var{x} is decremented
by is the length in bytes of the machine mode of the containing memory
reference of which this expression serves as the address.  Here is an
example of its use:@refill

@example
(mem:DF (pre_dec:SI (reg:SI 39)))
@end example

@noindent
This says to decrement pseudo register 39 by the length of a @code{DFmode}
value and use the result to address a @code{DFmode} value.

@item (pre_inc:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.

@item (post_dec:@var{m} @var{x})
Represents the same side effect as @code{pre_dec} but a different
value.  The value represented here is the value @var{x} has @i{before}
being decremented.

@item (post_inc:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.
@end table

These embedded side effect expressions must be used with care.  Instruction
patterns may not use them.  Until the @samp{flow} pass of the compiler,
they may occur only to represent pushes onto the stack.  The @samp{flow}
pass finds cases where registers are incremented or decremented in one
instruction and used as an address shortly before or after; these cases are
then transformed to use pre- or post-increment or -decrement.

Explicit popping of the stack could be represented with these embedded
side effect operators, but that would not be safe; the instruction
combination pass could move the popping past pushes, thus changing
the meaning of the code.

An instruction that can be represented with an embedded side effect
could also be represented using @code{parallel} containing an additional
@code{set} to describe how the address register is altered.  This is not
done because machines that allow these operations at all typically
allow them wherever a memory address is called for.  Describing them as
additional parallel stores would require doubling the number of entries
in the machine description.

@node Assembler, Insns, IncDec, RTL
@section Assembler Instructions as Expressions

The RTX code @code{asm_operands} represents a value produced by a
user-specified assembler instruction.  It is used to represent
an @code{asm} statement with arguments.  An @code{asm} statement with
a single output operand, like this:

@example
asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
@end example

@noindent
is represented using a single @code{asm_operands} RTX which represents
the value that is stored in @code{outputvar}:

@example
(set @var{rtx-for-outputvar}
     (asm_operands "foo %1,%2,%0" "a" 0
                   [@var{rtx-for-addition-result} @var{rtx-for-*z}]
                   [(asm_input:@var{m1} "g")
                    (asm_input:@var{m2} "di")]))
@end example

@noindent
Here the operands of the @code{asm_operands} RTX are the assembler
template string, the output-operand's constraint, the index-number of the
output operand among the output operands specified, a vector of input
operand RTX's, and a vector of input-operand modes and constraints.  The
mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
@code{*z}.

When an @code{asm} statement has multiple output values, its insn has
several such @code{set} RTX's inside of a @code{parallel}.  Each @code{set}
contains a @code{asm_operands}; all of these share the same assembler
template and vectors, but each contains the constraint for the respective
output operand.  They are also distinguished by the output-operand index
number, which is 0, 1, @dots{} for successive output operands.

@node Insns, Calls, Assembler, RTL
@section Insns

The RTL representation of the code for a function is a doubly-linked
chain of objects called @dfn{insns}.  Insns are expressions with
special codes that are used for no other purpose.  Some insns are
actual instructions; others represent dispatch tables for @code{switch}
statements; others represent labels to jump to or various sorts of
declarative information.

In addition to its own specific data, each insn must have a unique id-number
that distinguishes it from all other insns in the current function, and
chain pointers to the preceding and following insns.  These three fields
occupy the same position in every insn, independent of the expression code
of the insn.  They could be accessed with @code{XEXP} and @code{XINT},
but instead three special macros are always used:

@table @code
@item INSN_UID (@var{i})
Accesses the unique id of insn @var{i}.

@item PREV_INSN (@var{i})
Accesses the chain pointer to the insn preceding @var{i}.
If @var{i} is the first insn, this is a null pointer.

@item NEXT_INSN (@var{i})
Accesses the chain pointer to the insn following @var{i}.
If @var{i} is the last insn, this is a null pointer.
@end table

The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
correspond: if @var{insn} is not the first insn,

@example
NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
@end example

@noindent
is always true.

Every insn has one of the following six expression codes:

@table @code
@item insn
The expression code @code{insn} is used for instructions that do not jump
and do not do function calls.  Insns with code @code{insn} have four
additional fields beyond the three mandatory ones listed above.
These four are described in a table below.

@item jump_insn
The expression code @code{jump_insn} is used for instructions that may jump
(or, more generally, may contain @code{label_ref} expressions).
@code{jump_insn} insns have the same extra fields as @code{insn} insns,
accessed in the same way.  If there is an instruction to return from the
current function, it is recorded as a @code{jump_insn}.

@item call_insn
The expression code @code{call_insn} is used for instructions that may do
function calls.  It is important to distinguish these instructions because
they imply that certain registers and memory locations may be altered
unpredictably.

@code{call_insn} insns have the same extra fields as @code{insn} insns,
accessed in the same way.

@item code_label
A @code{code_label} insn represents a label that a jump insn can jump to.
It contains one special field of data in addition to the three standard ones.
It is used to hold the @dfn{label number}, a number that identifies this
label uniquely among all the labels in the compilation (not just in the
current function).  Ultimately, the label is represented in the assembler
output as an assembler label @samp{L@var{n}} where @var{n} is the label number.

@item barrier
Barriers are placed in the instruction stream after unconditional
jump instructions to indicate that the jumps are unconditional.
They contain no information beyond the three standard fields.

@item note
@code{note} insns are used to represent additional debugging and
declarative information.  They contain two nonstandard fields, an
integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
string accessed with @code{NOTE_SOURCE_FILE}.

If @code{NOTE_LINE_NUMBER} is positive, the note represents the
position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
that the line came from.  These notes control generation of line
number data in the assembler output.

Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
code with one of the following values (and @code{NOTE_SOURCE_FILE}
must contain a null pointer):

@table @code
@item NOTE_INSN_DELETED
Such a note is completely ignorable.  Some passes of the compiler
delete insns by altering them into notes of this kind.

@item NOTE_INSN_BLOCK_BEG
@itemx NOTE_INSN_BLOCK_END
These types of notes indicate the position of the beginning and end
of a level of scoping of variable names.  They control the output
of debugging information.

@item NOTE_INSN_LOOP_BEG
@itemx NOTE_INSN_LOOP_END
These types of notes indicate the position of the beginning and end
of a @code{while} or @code{for} loop.  They enable the loop optimizer
to find loops quickly.
@item NOTE_INSN_FUNCTION_END
Appears near the end of the function body, just before the label that
@code{return} statements jump to (on machine where a single instruction
does not suffice for returning).  This note may be deleted by jump
optimization.
@item NOTE_INSN_SETJMP
Appears following each call to @code{setjmp} or a related function.

@item NOTE_INSN_LOOP_CONT
Appears at the place in a loop that @code{continue} statements jump to.
@end table

These codes are printed symbolically when they appear in debugging dumps.
@end table

The machine mode of an insn is normally zero (@code{VOIDmode}), but the
reload pass sets it to @code{QImode} if the insn needs reloading.

Here is a table of the extra fields of @code{insn}, @code{jump_insn}
and @code{call_insn} insns:

@table @code
@item PATTERN (@var{i})
An expression for the side effect performed by this insn.

@item INSN_CODE (@var{i})
An integer that says which pattern in the machine description matches
this insn, or -1 if the matching has not yet been attempted.

Such matching is never attempted and this field is not used on an insn
whose pattern consists of a single @code{use}, @code{clobber},
@code{asm}, @code{addr_vec} or @code{addr_diff_vec} expression.

@item LOG_LINKS (@var{i})
A list (chain of @code{insn_list} expressions) of previous ``related''
insns: insns which store into registers values that are used for the
first time in this insn.  (An additional constraint is that neither a
jump nor a label may come between the related insns).  This list is
set up by the flow analysis pass; it is a null pointer until then.

@item REG_NOTES (@var{i})
A list (chain of @code{expr_list} expressions) giving information
about the usage of registers in this insn.  This list is set up by the
flow analysis pass; it is a null pointer until then.
@end table

The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
expressions.  Each of these has two operands: the first is an insn,
and the second is another @code{insn_list} expression (the next one in
the chain).  The last @code{insn_list} in the chain has a null pointer
as second operand.  The significant thing about the chain is which
insns appear in it (as first operands of @code{insn_list}
expressions).  Their order is not significant.

The @code{REG_NOTES} field of an insn is a similar chain but of
@code{expr_list} expressions instead of @code{insn_list}.  There are
several kinds of register notes, which are distinguished by the machine
mode of the @code{expr_list}, which in a register note is really
understood as being an @code{enum reg_note}.  The first operand @var{op}
of the @code{expr_list} is data whose meaning depends on the kind of
note.  Here are the kinds of register note:

@table @code
@item REG_DEAD
The register @var{op} dies in this insn; that is to say, altering the
value immediately after this insn would not affect the future behavior
of the program.

@item REG_INC
The register @var{op} is incremented (or decremented; at this level
there is no distinction) by an embedded side effect inside this insn.
This means it appears in a @code{post_inc}, @code{pre_inc},
@code{post_dec} or @code{pre_dec} RTX.

@item REG_EQUIV
The register that is set by this insn will be equal to @var{op} at run
time, and could validly be replaced in all its occurrences by
@var{op}.  (``Validly'' here refers to the data flow of the program;
simple replacement may make some insns invalid.)

The value which the insn explicitly copies into the register may look
different from @var{op}, but they will be equal at run time.

For example, when a constant is loaded into a register that is never
assigned any other value, this kind of note is used.

When a parameter is copied into a pseudo-register at entry to a function,
a note of this kind records that the register is equivalent to the stack
slot where the parameter was passed.  Although in this case the register
may be set by other insns, it is still valid to replace the register
by the stack slot throughout the function.

@item REG_EQUAL
The register that is set by this insn will be equal to @var{op} at run
time at the end of this insn (but not necessarily elsewhere in the
function).

The RTX @var{op} is typically an arithmetic expression.  For example,
when a sequence of insns such as a library call is used to perform an
arithmetic operation, this kind of note is attached to the insn that
produces or copies the final value.  It tells the CSE pass how to
think of that value.

@item REG_RETVAL
This insn copies the value of a library call, and @var{op} is the
first insn that was generated to set up the arguments for the library
call.

Flow analysis uses this note to delete all of a library call whose
result is dead.

@item REG_WAS_0
The register @var{op} contained zero before this insn.  You can rely
on this note if it is present; its absence implies nothing.

@item REG_LIBCALL
This is the inverse of @code{REG_RETVAL}: it is placed on the first
insn of a library call, and it points to the last one.

Loop optimization uses this note to move an entire library call out
of a loop when its value is constant.

@item REG_NONNEG
The register @var{op} is known to have nonnegative value when this
insn is reached.
@end table

For convenience, the machine mode in an @code{insn_list} or
@code{expr_list} is printed using these symbolic codes in debugging dumps.

The only difference between the expression codes @code{insn_list} and
@code{expr_list} is that the first operand of an @code{insn_list} is
assumed to be an insn and is printed in debugging dumps as the insn's
unique id; the first operand of an @code{expr_list} is printed in the
ordinary way as an expression.

@node Calls, Sharing, Insns, RTL
@section RTL Representation of Function-Call Insns

Insns that call subroutines have the RTL expression code @code{call_insn}.
These insns must satisfy special rules, and their bodies must use a special
RTL expression code, @code{call}.

A @code{call} expression has two operands, as follows:

@example
(call (mem:@var{fm} @var{addr}) @var{nbytes})
@end example

@noindent
Here @var{nbytes} is an operand that represents the number of bytes of
argument data being passed to the subroutine, @var{fm} is a machine mode
(which must equal as the definition of the @code{FUNCTION_MODE} macro in
the machine description) and @var{addr} represents the address of the
subroutine.

For a subroutine that returns no value, the @code{call} RTX as shown above
is the entire body of the insn.

For a subroutine that returns a value whose mode is not @code{BLKmode},
the value is returned in a hard register.  If this register's number is
@var{r}, then the body of the call insn looks like this:

@example
(set (reg:@var{m} @var{r})
     (call (mem:@var{fm} @var{addr}) @var{nbytes}))
@end example

@noindent
This RTL expression makes it clear (to the optimizer passes) that the
appropriate register receives a useful value in this insn.

Immediately after RTL generation, if the value of the subroutine is
actually used, this call insn is always followed closely by an insn which
refers to the register @var{r}.  This remains true through all the
optimizer passes until cross jumping occurs.

The following insn has one of two forms.  Either it copies the value into a
pseudo-register, like this:

@example
(set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
@end example

@noindent
or (in the case where the calling function will simply return whatever
value the call produced, and no operation is needed to do this):

@example
(use (reg:@var{m} @var{r}))
@end example

@noindent
Between the call insn and this following insn there may intervene only a
stack-adjustment insn (and perhaps some @code{note} insns).

When a subroutine returns a @code{BLKmode} value, it is handled by
passing to the subroutine the address of a place to store the value.
So the call insn itself does not ``return'' any value, and it has the
same RTL form as a call that returns nothing.

@node Sharing,, Calls, RTL
@section Structure Sharing Assumptions

The compiler assumes that certain kinds of RTL expressions are unique;
there do not exist two distinct objects representing the same value.
In other cases, it makes an opposite assumption: that no RTL expression
object of a certain kind appears in more than one place in the
containing structure.

These assumptions refer to a single function; except for the RTL
objects that describe global variables and external functions,
no RTL objects are common to two functions.

@itemize @bullet
@item
Each pseudo-register has only a single @code{reg} object to represent it,
and therefore only a single machine mode.

@item
For any symbolic label, there is only one @code{symbol_ref} object
referring to it.

@item
There is only one @code{const_int} expression with value zero,
and only one with value one.

@item
There is only one @code{pc} expression.

@item
There is only one @code{cc0} expression.

@item
There is only one @code{const_double} expression with mode
@code{SFmode} and value zero, and only one with mode @code{DFmode} and
value zero.

@item
No @code{label_ref} appears in more than one place in the RTL
structure; in other words, it is safe to do a tree-walk of all the
insns in the function and assume that each time a @code{label_ref} is
seen it is distinct from all others that are seen.

@item
Only one @code{mem} object is normally created for each static
variable or stack slot, so these objects are frequently shared in all
the places they appear.  However, separate but equal objects for these
variables are occasionally made.

@item
When a single @code{asm} statement has multiple output operands,
a distinct @code{asm_operands} RTX is made for each output operand.
However, these all share the vector which contains the sequence of
input operands.  Because this sharing is used later on to test whether
two @code{asm_operands} RTX's come from the same statement, the sharing
must be guaranteed to be preserved.

@item
No RTL object appears in more than one place in the RTL structure
except as described above.  Many passes of the compiler rely on this
by assuming that they can modify RTL objects in place without unwanted
side-effects on other insns.

@item
During initial RTL generation, shared structure is freely introduced.
After all the RTL for a function has been generated, all shared
structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
after which the above rules are guaranteed to be followed.

@item
During the combiner pass, shared structure with an insn can exist
temporarily.  However, the shared structure is copied before the
combiner is finished with the insn.  This is done by
@code{copy_substitutions} in @file{combine.c}.
@end itemize

@node Machine Desc, Machine Macros, RTL, Top
@chapter Machine Descriptions

A machine description has two parts: a file of instruction patterns
(@file{.md} file) and a C header file of macro definitions.

The @file{.md} file for a target machine contains a pattern for each
instruction that the target machine supports (or at least each instruction
that is worth telling the compiler about).  It may also contain comments.
A semicolon causes the rest of the line to be a comment, unless the semicolon
is inside a quoted string.

See the next chapter for information on the C header file.

@menu
* Patterns::            How to write instruction patterns.
* Example::             An explained example of a @code{define_insn} pattern.
* RTL Template::        The RTL template defines what insns match a pattern.
* Output Template::     The output template says how to make assembler code
                          from such an insn.
* Output Statement::    For more generality, write C code to output 
                          the assembler code.
* Constraints::         When not all operands are general operands.
* Standard Names::      Names mark patterns to use for code generation.
* Pattern Ordering::    When the order of patterns makes a difference.
* Dependent Patterns::  Having one pattern may make you need another.
* Jump Patterns::       Special considerations for patterns for jump insns.
* Peephole Definitions::Defining machine-specific peephole optimizations.
* Expander Definitions::Generating a sequence of several RTL insns
                         for a standard operation.
@end menu

@node Patterns, Example, Machine Desc, Machine Desc
@section Everything about Instruction Patterns

Each instruction pattern contains an incomplete RTL expression, with pieces
to be filled in later, operand constraints that restrict how the pieces can
be filled in, and an output pattern or C code to generate the assembler
output, all wrapped up in a @code{define_insn} expression.

A @code{define_insn} is an RTL expression containing four or five operands:

@enumerate
@item
An optional name.  The presence of a name indicate that this instruction
pattern can perform a certain standard job for the RTL-generation
pass of the compiler.  This pass knows certain names and will use
the instruction patterns with those names, if the names are defined
in the machine description.

The absence of a name is indicated by writing an empty string
where the name should go.  Nameless instruction patterns are never
used for generating RTL code, but they may permit several simpler insns
to be combined later on.

Names that are not thus known and used in RTL-generation have no
effect; they are equivalent to no name at all.

@item
The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
incomplete RTL expressions which show what the instruction should look
like.  It is incomplete because it may contain @code{match_operand}
and @code{match_dup} expressions that stand for operands of the
instruction.

If the vector has only one element, that element is the template for the
instruction pattern.  If the vector has multiple elements, then the
instruction pattern is a @code{parallel} expression containing the
elements described.

@item
A condition.  This is a string which contains a C expression that is
the final test to decide whether an insn body matches this pattern.

For a named pattern, the condition (if present) may not depend on
the data in the insn being matched, but only the target-machine-type
flags.  The compiler needs to test these conditions during
initialization in order to learn exactly which named instructions are
available in a particular run.

For nameless patterns, the condition is applied only when matching an
individual insn, and only after the insn has matched the pattern's
recognition template.  The insn's operands may be found in the vector
@code{operands}.

@item
The @dfn{output template}: a string that says how to output matching
insns as assembler code.  @samp{%} in this string specifies where
to substitute the value of an operand.  @xref{Output Template}.

When simple substitution isn't general enough, you can specify a piece
of C code to compute the output.  @xref{Output Statement}.

@item
Optionally, some @dfn{machine-specific information}.  The meaning
of this information is defined only by an individual machine description;
typically it might say whether this insn alters the condition codes,
or how many bytes of output it generates.

This operand is written as a string containing a C initializer
(complete with braces) for the structure type @code{INSN_MACHINE_INFO},
whose definition is up to you (@pxref{Misc}).
@end enumerate

@node Example, RTL Template, Patterns, Machine Desc
@section Example of @code{define_insn}

Here is an actual example of an instruction pattern, for the 68000/68020.

@example
(define_insn "tstsi"
  [(set (cc0)
        (match_operand:SI 0 "general_operand" "rm"))]
  ""
  "*
@{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
    return \"tstl %0\";
  return \"cmpl #0,%0\"; @}")
@end example

This is an instruction that sets the condition codes based on the value of
a general operand.  It has no condition, so any insn whose RTL description
has the form shown may be handled according to this pattern.  The name
@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
pass that, when it is necessary to test such a value, an insn to do so
can be constructed using this pattern.

The output control string is a piece of C code which chooses which
output template to return based on the kind of operand and the specific
type of CPU for which code is being generated.

@samp{"rm"} is an operand constraint.  Its meaning is explained below.

@node RTL Template, Output Template, Example, Machine Desc
@section RTL Template for Generating and Recognizing Insns

The RTL template is used to define which insns match the particular pattern
and how to find their operands.  For named patterns, the RTL template also
says how to construct an insn from specified operands.

Construction involves substituting specified operands into a copy of the
template.  Matching involves determining the values that serve as the
operands in the insn being matched.  Both of these activities are
controlled by special expression types that direct matching and
substitution of the operands.

@table @code
@item (match_operand:@var{m} @var{n} @var{pred} @var{constraint})
This expression is a placeholder for operand number @var{n} of
the insn.  When constructing an insn, operand number @var{n}
will be substituted at this point.  When matching an insn, whatever
appears at this position in the insn will be taken as operand
number @var{n}; but it must satisfy @var{pred} or this instruction
pattern will not match at all.

Operand numbers must be chosen consecutively counting from zero in
each instruction pattern.  There may be only one @code{match_operand}
expression in the pattern for each operand number.  Usually operands
are numbered in the order of appearance in @code{match_operand}
expressions.

@var{pred} is a string that is the name of a C function that accepts
two arguments, an expression and a machine mode.  During matching, the
function will be called with the putative operand as the expression
and @var{m} as the mode argument.  If it returns zero, this
instruction pattern fails to match.  @var{pred} may be an empty
string; then it means no test is to be done on the operand,
so anything which occurs in this position is valid.

@var{constraint} controls reloading and the choice of the best register
class to use for a value, as explained later (@pxref{Constraints}).

People are often unclear on the difference between the constraint and the
predicate.  The predicate helps decide whether a given insn matches the
pattern.  The constraint plays no role in this decision; instead, it
controls various decisions in the case of an insn which does match.

Most often, @var{pred} is @code{"general_operand"}.  This function checks
that the putative operand is either a constant, a register or a memory
reference, and that it is valid for mode @var{m}.

For an operand that must be a register, @var{pred} should be
@code{"register_operand"}.  It would be valid to use
@code{"general_operand"}, since the reload pass would copy any
non-register operands through registers, but this would make GNU CC do
extra work, and it would prevent the register allocator from doing the
best possible job.

For an operand that must be a constant, either @var{pred} should be
@code{"immediate_operand"}, or the instruction pattern's extra
condition should check for constants, or both.  You cannot expect the
constraints to do this work!  If the constraints allow only constants,
but the predicate allows something else, the compiler will crash when
that case arises.

@item (match_dup @var{n})
This expression is also a placeholder for operand number @var{n}.
It is used when the operand needs to appear more than once in the
insn.

In construction, @code{match_dup} behaves exactly like
@code{match_operand}: the operand is substituted into the insn being
constructed.  But in matching, @code{match_dup} behaves differently.
It assumes that operand number @var{n} has already been determined by
a @code{match_operand} appearing earlier in the recognition template,
and it matches only an identical-looking expression.

@item (match_operator:@var{m} @var{n} "@var{predicate}" [@var{operands}@dots{}])
This pattern is a kind of placeholder for a variable RTL expression
code.

When constructing an insn, it stands for an RTL expression whose
expression code is taken from that of operand @var{n}, and whose
operands are constructed from the patterns @var{operands}.

When matching an expression, it matches an expression if the function
@var{predicate} returns nonzero on that expression @emph{and} the
patterns @var{operands} match the operands of the expression.

Suppose that the function @code{commutative_operator} is defined as
follows, to match any expression whose operator is one of the six
commutative arithmetic operators of RTL and whose mode is @var{mode}:

@example
int
commutative_operator (x, mode)
     rtx x;
     enum machine_mode mode;
@{
  enum rtx_code code = GET_CODE (x);
  if (GET_MODE (x) != mode)
    return 0;
  return (code == PLUS || code == MULT || code == UMULT
          || code == AND || code == IOR || code == XOR);
@}
@end example

Then the following pattern will match any RTL expression consisting
of a commutative operator applied to two general operands:

@example
(match_operator:SI 2 "commutative_operator"
  [(match_operand:SI 3 "general_operand" "g")
   (match_operand:SI 4 "general_operand" "g")])
@end example

Here the vector @code{[@var{operands}@dots{}]} contains two patterns
because the expressions to be matched all contain two operands.

When this pattern does match, the two operands of the commutative
operator are recorded as operands 3 and 4 of the insn.  (This is done
by the two instances of @code{match_operand}.)  Operand 2 of the insn
will be the entire commutative expression: use @code{GET_CODE
(operands[2])} to see which commutative operator was used.

The machine mode @var{m} of @code{match_operator} works like that of
@code{match_operand}: it is passed as the second argument to the
predicate function, and that function is solely responsible for
deciding whether the expression to be matched ``has'' that mode.

When constructing an insn, argument 2 of the gen-function will specify
the operation (i.e. the expression code) for the expression to be
made.  It should be an RTL expression, whose expression code is copied
into a new expression whose operands are arguments 3 and 4 of the
gen-function.  The subexpressions of argument 2 are not used;
only its expression code matters.

There is no way to specify constraints in @code{match_operator}.  The
operand of the insn which corresponds to the @code{match_operator}
never has any constraints because it is never reloaded as a whole.
However, if parts of its @var{operands} are matched by
@code{match_operand} patterns, those parts may have constraints of
their own.

@item (address (match_operand:@var{m} @var{n} "address_operand" ""))
This complex of expressions is a placeholder for an operand number
@var{n} in a ``load address'' instruction: an operand which specifies
a memory location in the usual way, but for which the actual operand
value used is the address of the location, not the contents of the
location.

@code{address} expressions never appear in RTL code, only in machine
descriptions.  And they are used only in machine descriptions that do
not use the operand constraint feature.  When operand constraints are
in use, the letter @samp{p} in the constraint serves this purpose.

@var{m} is the machine mode of the @emph{memory location being
addressed}, not the machine mode of the address itself.  That mode is
always the same on a given target machine (it is @code{Pmode}, which
normally is @code{SImode}), so there is no point in mentioning it;
thus, no machine mode is written in the @code{address} expression.  If
some day support is added for machines in which addresses of different
kinds of objects appear differently or are used differently (such as
the PDP-10), different formats would perhaps need different machine
modes and these modes might be written in the @code{address}
expression.
@end table

@node Output Template, Output Statement, RTL Template, Machine Desc
@section Output Templates and Operand Substitution

The @dfn{output template} is a string which specifies how to output the
assembler code for an instruction pattern.  Most of the template is a
fixed string which is output literally.  The character @samp{%} is used
to specify where to substitute an operand; it can also be used to
identify places where different variants of the assembler require
different syntax.

In the simplest case, a @samp{%} followed by a digit @var{n} says to output
operand @var{n} at that point in the string.

@samp{%} followed by a letter and a digit says to output an operand in an
alternate fashion.  Four letters have standard, built-in meanings described
below.  The machine description macro @code{PRINT_OPERAND} can define
additional letters with nonstandard meanings.

@samp{%c@var{digit}} can be used to substitute an operand that is a
constant value without the syntax that normally indicates an immediate
operand.

@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
the constant is negated before printing.

@samp{%a@var{digit}} can be used to substitute an operand as if it were a
memory reference, with the actual operand treated as the address.  This may
be useful when outputting a ``load address'' instruction, because often the
assembler syntax for such an instruction requires you to write the operand
as if it were a memory reference.

@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
instruction.

@samp{%} followed by a punctuation character specifies a substitution that
does not use an operand.  Only one case is standard: @samp{%%} outputs a
@samp{%} into the assembler code.  Other nonstandard cases can be
defined in the @code{PRINT_OPERAND} macro.  You must also define
which punctuation characters are valid with the
@code{PRINT_OPERAND_PUNCT_VALID_P} macro.

The template may generate multiple assembler instructions.  Write the text
for the instructions, with @samp{\;} between them.

When the RTL contains two operands which are required by constraint to match
each other, the output template must refer only to the lower-numbered operand.
Matching operands are not always identical, and the rest of the compiler
arranges to put the proper RTL expression for printing into the lower-numbered
operand.

One use of nonstandard letters or punctuation following @samp{%} is to
distinguish between different assembler languages for the same machine; for
example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
requires periods in most opcode names, while MIT syntax does not.  For
example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
syntax.  The same file of patterns is used for both kinds of output syntax,
but the character sequence @samp{%.} is used in each place where Motorola
syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
defines the sequence to output a period; the macro for MIT syntax defines
it to do nothing.

@node Output Statement, Constraints, Output Template, Machine Desc
@section C Statements for Generating Assembler Output

Often a single fixed template string cannot produce correct and efficient
assembler code for all the cases that are recognized by a single
instruction pattern.  For example, the opcodes may depend on the kinds of
operands; or some unfortunate combinations of operands may require extra
machine instructions.

If the output control string starts with a @samp{*}, then it is not an
output template but rather a piece of C program that should compute a
template.  It should execute a @code{return} statement to return the
template-string you want.  Most such templates use C string literals, which
require doublequote characters to delimit them.  To include these
doublequote characters in the string, prefix each one with @samp{\}.

The operands may be found in the array @code{operands}, whose C data type
is @code{rtx []}.

It is possible to output an assembler instruction and then go on to output
or compute more of them, using the subroutine @code{output_asm_insn}.  This
receives two arguments: a template-string and a vector of operands.  The
vector may be @code{operands}, or it may be another array of @code{rtx}
that you declare locally and initialize yourself.

When an insn pattern has multiple alternatives in its constraints, often
the appearance of the assembler code is determined mostly by which alternative
was matched.  When this is so, the C code can test the variable
@code{which_alternative}, which is the ordinal number of the alternative
that was actually satisfied (0 for the first, 1 for the second alternative,
etc.).

For example, suppose there are two opcodes for storing zero, @samp{clrreg}
for registers and @samp{clrmem} for memory locations.  Here is how
a pattern could use @code{which_alternative} to choose between them:

@example
(define_insn ""
  [(set (match_operand:SI 0 "general_operand" "r,m")
        (const_int 0))]
  ""
  "*
  return (which_alternative == 0
          ? \"clrreg %0\" : \"clrmem %0\");
  ")
@end example

@node Constraints, Standard Names, Output Statement, Machine Desc
@section Operand Constraints

Each @code{match_operand} in an instruction pattern can specify a
constraint for the type of operands allowed.  Constraints can say whether
an operand may be in a register, and which kinds of register; whether the
operand can be a memory reference, and which kinds of address; whether the
operand may be an immediate constant, and which possible values it may
have.  Constraints can also require two operands to match.

@menu
* Simple Constraints::  Basic use of constraints.
* Multi-Alternative::   When an insn has two alternative constraint-patterns.
* Class Preferences::   Constraints guide which hard register to put things in.
* Modifiers::           More precise control over effects of constraints.
* No Constraints::      Describing a clean machine without constraints.
@end menu

@node Simple Constraints, Multi-Alternative, Constraints, Constraints
@subsection Simple Constraints

The simplest kind of constraint is a string full of letters, each of
which describes one kind of operand that is permitted.  Here are
the letters that are allowed:

@table @asis
@item @samp{m}
A memory operand is allowed, with any kind of address that the machine
supports in general.

@item @samp{o}
A memory operand is allowed, but only if the address is
@dfn{offsettable}.  This means that adding a small integer (actually,
the width in bytes of the operand, as determined by its machine mode)
may be added to the address and the result is also a valid memory
address.

For example, an address which is constant is offsettable; so is an
address that is the sum of a register and a constant (as long as a
slightly larger constant is also within the range of address-offsets
supported by the machine); but an autoincrement or autodecrement
address is not offsettable.  More complicated indirect/indexed
addresses may or may not be offsettable depending on the other
addressing modes that the machine supports.

Note that in an output operand which can be matched by another
operand, the constraint letter @samp{o} is valid only when accompanied
by both @samp{<} (if the target machine has predecrement addressing)
and @samp{>} (if the target machine has preincrement addressing).

When the constraint letter @samp{o} is used, the reload pass may
generate instructions which copy a nonoffsettable address into an index
register.  The idea is that the register can be used as a replacement
offsettable address.  But this method requires that there be patterns
to copy any kind of address into a register.  Auto-increment
and auto-decrement addresses are an exception; there need not be an
instruction that can copy such an address into a register, because
reload handles these cases specially.

Most older machine designs have ``load address'' instructions which do
just what is needed here.  Some RISC machines do not advertise such
instructions, but the possible addresses on these machines are very
limited, so it is easy to fake them.

@item @samp{<}
A memory operand with autodecrement addressing (either predecrement or
postdecrement) is allowed.

@item @samp{>}
A memory operand with autoincrement addressing (either preincrement or
postincrement) is allowed.

@item @samp{r}
A register operand is allowed provided that it is in a general
register.

@item @samp{d}, @samp{a}, @samp{f}, @dots{}
Other letters can be defined in machine-dependent fashion to stand for
particular classes of registers.  @samp{d}, @samp{a} and @samp{f} are
defined on the 68000/68020 to stand for data, address and floating
point registers.

@item @samp{i}
An immediate integer operand (one with constant value) is allowed.
This includes symbolic constants whose values will be known only at
assembly time.

@item @samp{n}
An immediate integer operand with a known numeric value is allowed.
Many systems cannot support assembly-time constants for operands less
than a word wide.  Constraints for these operands should use @samp{n}
rather than @samp{i}.

@item @samp{I}, @samp{J}, @samp{K}, @dots{}
Other letters in the range @samp{I} through @samp{M} may be defined in
a machine-dependent fashion to permit immediate integer operands with
explicit integer values in specified ranges.  For example, on the
68000, @samp{I} is defined to stand for the range of values 1 to 8.
This is the range permitted as a shift count in the shift
instructions.

@item @samp{F}
An immediate floating operand (expression code @code{const_double}) is
allowed.

@item @samp{G}, @samp{H}
@samp{G} and @samp{H} may be defined in a machine-dependent fashion to
permit immediate floating operands in particular ranges of values.

@item @samp{s}
An immediate integer operand whose value is not an explicit integer is
allowed.

This might appear strange; if an insn allows a constant operand with a
value not known at compile time, it certainly must allow any known
value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
better code to be generated.

For example, on the 68000 in a fullword instruction it is possible to
use an immediate operand; but if the immediate value is between -128
and 127, better code results from loading the value into a register and
using the register.  This is because the load into the register can be
done with a @samp{moveq} instruction.  We arrange for this to happen
by defining the letter @samp{K} to mean ``any integer outside the
range -128 to 127'', and then specifying @samp{Ks} in the operand
constraints.

@item @samp{g}
Any register, memory or immediate integer operand is allowed, except for
registers that are not general registers.

@item @samp{@var{n}} (a digit)
An operand that matches operand number @var{n} is allowed.
If a digit is used together with letters, the digit should come last.

This is called a @dfn{matching constraint} and what it really means is
that the assembler has only a single operand that fills two roles
considered separate in the RTL insn.  For example, an add insn has two
input operands and one output operand in the RTL, but on most machines
an add instruction really has only two operands, one of them an
input-output operand.

Matching constraints work only in circumstances like that add insn.
More precisely, the matching constraint must appear in an input-only
operand and the operand that it matches must be an output-only operand
with a lower number.  Thus, operand @var{n} must have @samp{=} in its
constraint.

For operands to match in a particular case usually means that they
are identical-looking RTL expressions.  But in a few special cases
specific kinds of dissimilarity are allowed.  For example, @code{*x}
as an input operand will match @code{*x++} as an output operand.
For proper results in such cases, the output template should always
use the output-operand's number when printing the operand.

@item @samp{p}
An operand that is a valid memory address is allowed.  This is
for ``load address'' and ``push address'' instructions.

@samp{p} in the constraint must be accompanies by @code{address_operand}
as the predicate in the @code{match_operand}.
@end table

In order to have valid assembler code, each operand must satisfy
its constraint.  But a failure to do so does not prevent the pattern
from applying to an insn.  Instead, it directs the compiler to modify
the code so that the constraint will be satisfied.  Usually this is
done by copying an operand into a register.

Contrast, therefore, the two instruction patterns that follow:

@example
(define_insn ""
  [(set (match_operand:SI 0 "general_operand" "r")
        (plus:SI (match_dup 0)
                 (match_operand:SI 1 "general_operand" "r")))]
  ""
  "@dots{}")
@end example

@noindent
which has two operands, one of which must appear in two places, and

@example
(define_insn ""
  [(set (match_operand:SI 0 "general_operand" "r")
        (plus:SI (match_operand:SI 1 "general_operand" "0")
                 (match_operand:SI 2 "general_operand" "r")))]
  ""
  "@dots{}")
@end example

@noindent
which has three operands, two of which are required by a constraint to be
identical.  If we are considering an insn of the form

@example
(insn @var{n} @var{prev} @var{next}
  (set (reg:SI 3)
       (plus:SI (reg:SI 6) (reg:SI 109)))
  @dots{})
@end example

@noindent
the first pattern would not apply at all, because this insn does not
contain two identical subexpressions in the right place.  The pattern would
say, ``That does not look like an add instruction; try other patterns.''
The second pattern would say, ``Yes, that's an add instruction, but there
is something wrong with it.''  It would direct the reload pass of the
compiler to generate additional insns to make the constraint true.  The
results might look like this:

@example
(insn @var{n2} @var{prev} @var{n}
  (set (reg:SI 3) (reg:SI 6))
  @dots{})

(insn @var{n} @var{n2} @var{next}
  (set (reg:SI 3)
       (plus:SI (reg:SI 3) (reg:SI 109)))
  @dots{})
@end example

It is up to you to make sure that each operand, in each pattern, has
constraints that can handle any RTL expression that could be present for
that operand.  (When multiple alternatives are in use, each pattern must,
for each possible combination of operand expressions, have at least one
alternative which can handle that combination of operands.)  The
constraints don't need to @emph{allow} any possible operand---when this is
the case, they do not constrain---but they must at least point the way to
reloading any possible operand so that it will fit.

@itemize @bullet
@item
If the constraint accepts whatever operands the predicate permits,
there is no problem: reloading is never necessary for this operand.

For example, an operand whose constraints permit everything except
registers is safe provided its predicate rejects registers.

An operand whose predicate accepts only constant values is safe
provided its constraints include the letter @samp{i}.  If any possible
constant value is accepted, then nothing less than @samp{i} will do;
if the predicate is more selective, then the constraints may also be
more selective.

@item
Any operand expression can be reloaded by copying it into a register.
So if an operand's constraints allow some kind of register, it is
certain to be safe.  It need not permit all classes of registers; the
compiler knows how to copy a register into another register of the
proper class in order to make an instruction valid.

@item
A nonoffsettable memory reference can be reloaded by copying the
address into a register.  So if the constraint uses the letter
@samp{o}, all memory references are taken care of.

@item
A constant operand can be reloaded by allocating space in memory to
hold it as preinitialized data.  Then the memory reference can be used
in place of the constant.  So if the constraint uses the letters
@samp{o} or @samp{m}, constant operands are not a problem.
@end itemize

If the operand's predicate can recognize registers, but the constraint does
not permit them, it can make the compiler crash.  When this operand happens
to be a register, the reload pass will be stymied, because it does not know
how to copy a register temporarily into memory.

@node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
@subsection Multiple Alternative Constraints

Sometimes a single instruction has multiple alternative sets of possible
operands.  For example, on the 68000, a logical-or instruction can combine
register or an immediate value into memory, or it can combine any kind of
operand into a register; but it cannot combine one memory location into
another.

These constraints are represented as multiple alternatives.  An alternative
can be described by a series of letters for each operand.  The overall
constraint for an operand is made from the letters for this operand
from the first alternative, a comma, the letters for this operand from
the second alternative, a comma, and so on until the last alternative.
Here is how it is done for fullword logical-or on the 68000:

@example
(define_insn "iorsi3"
  [(set (match_operand:SI 0 "general_operand" "=m,d")
        (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
                (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
  @dots{})
@end example

The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
2.  The second alternative has @samp{d} (data register) for operand 0,
@samp{0} for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and
@samp{%} in the constraints apply to all the alternatives; their meaning
is explained in the next section.

If all the operands fit any one alternative, the instruction is valid.
Otherwise, for each alternative, the compiler counts how many instructions
must be added to copy the operands so that that alternative applies.
The alternative requiring the least copying is chosen.  If two alternatives
need the same amount of copying, the one that comes first is chosen.
These choices can be altered with the @samp{?} and @samp{!} characters:

@table @samp
@item ?
Disparage slightly the alternative that the @samp{?} appears in,
as a choice when no alternative applies exactly.  The compiler regards
this alternative as one unit more costly for each @samp{?} that appears
in it.

@item !
Disparage severely the alternative that the @samp{!} appears in.
When operands must be copied into registers, the compiler will
never choose this alternative as the one to strive for.
@end table

When an insn pattern has multiple alternatives in its constraints, often
the appearance of the assembler code is determined mostly by which
alternative was matched.  When this is so, the C code for writing the
assembler code can use the variable @code{which_alternative}, which is
the ordinal number of the alternative that was actually satisfied (0 for
the first, 1 for the second alternative, etc.).  For example:

@example
(define_insn ""
  [(set (match_operand:SI 0 "general_operand" "r,m")
        (const_int 0))]
  ""
  "*
  return (which_alternative == 0
          ? \"clrreg %0\" : \"clrmem %0\");
  ")
@end example

@node Class Preferences, Modifiers, Multi-Alternative, Constraints
@subsection Register Class Preferences

The operand constraints have another function: they enable the compiler
to decide which kind of hardware register a pseudo register is best
allocated to.  The compiler examines the constraints that apply to the
insns that use the pseudo register, looking for the machine-dependent
letters such as @samp{d} and @samp{a} that specify classes of registers.
The pseudo register is put in whichever class gets the most ``votes''.
The constraint letters @samp{g} and @samp{r} also vote: they vote in
favor of a general register.  The machine description says which registers
are considered general.

Of course, on some machines all registers are equivalent, and no register
classes are defined.  Then none of this complexity is relevant.

@node Modifiers, No Constraints, Class Preferences, Constraints
@subsection Constraint Modifier Characters

@table @samp
@item =
Means that this operand is write-only for this instruction: the previous
value is discarded and replaced by output data.

@item +
Means that this operand is both read and written by the instruction.

When the compiler fixes up the operands to satisfy the constraints,
it needs to know which operands are inputs to the instruction and
which are outputs from it.  @samp{=} identifies an output; @samp{+}
identifies an operand that is both input and output; all other operands
are assumed to be input only.

@item &
Means (in a particular alternative) that this operand is written
before the instruction is finished using the input operands.
Therefore, this operand may not lie in a register that is used as an
input operand or as part of any memory address.

@samp{&} applies only to the alternative in which it is written.  In
constraints with multiple alternatives, sometimes one alternative
requires @samp{&} while others do not.  See, for example, the
@samp{movdf} insn of the 68000.

@samp{&} does not obviate the need to write @samp{=}.

@item %
Declares the instruction to be commutative for this operand and the
following operand.  This means that the compiler may interchange the
two operands if that is the cheapest way to make all operands fit the
constraints.  This is often used in patterns for addition instructions
that really have only two operands: the result must go in one of the
arguments.  Here for example, is how the 68000 halfword-add
instruction is defined:

@example
(define_insn "addhi3"
  [(set (match_operand:HI 0 "general_operand" "=m,r")
     (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
              (match_operand:HI 2 "general_operand" "di,g")))]
  @dots{})
@end example

Note that in previous versions of GNU CC the @samp{%} constraint
modifier always applied to operands 1 and 2 regardless of which
operand it was written in.  The usual custom was to write it in
operand 0.  Now it must be in operand 1 if the operands to be
exchanged are 1 and 2.

@item #
Says that all following characters, up to the next comma, are to be
ignored as a constraint.  They are significant only for choosing
register preferences.

@item *
Says that the following character should be ignored when choosing
register preferences.  @samp{*} has no effect on the meaning of the
constraint as a constraint.

Here is an example: the 68000 has an instruction to sign-extend a
halfword in a data register, and can also sign-extend a value by
copying it into an address register.  While either kind of register is
acceptable, the constraints on an address-register destination are
less strict, so it is best if register allocation makes an address
register its goal.  Therefore, @samp{*} is used so that the @samp{d}
constraint letter (for data register) is ignored when computing
register preferences.

@example
(define_insn "extendhisi2"
  [(set (match_operand:SI 0 "general_operand" "=*d,a")
        (sign_extend:SI
         (match_operand:HI 1 "general_operand" "0,g")))]
  @dots{})
@end example
@end table

@node No Constraints,, Modifiers, Constraints
@subsection Not Using Constraints

Some machines are so clean that operand constraints are not required.  For
example, on the Vax, an operand valid in one context is valid in any other
context.  On such a machine, every operand constraint would be @samp{g},
excepting only operands of ``load address'' instructions which are
written as if they referred to a memory location's contents but actual
refer to its address.  They would have constraint @samp{p}.

For such machines, instead of writing @samp{g} and @samp{p} for all
the constraints, you can choose to write a description with empty constraints.
Then you write @samp{""} for the constraint in every @code{match_operand}.
Address operands are identified by writing an @code{address} expression
around the @code{match_operand}, not by their constraints.

When the machine description has just empty constraints, certain parts
of compilation are skipped, making the compiler faster.  However,
few machines actually do not need constraints; all machine descriptions
now in existence use constraints.

@node Standard Names, Pattern Ordering, Constraints, Machine Desc
@section Standard Names for Patterns Used in Generation

Here is a table of the instruction names that are meaningful in the RTL
generation pass of the compiler.  Giving one of these names to an
instruction pattern tells the RTL generation pass that it can use the
pattern in to accomplish a certain task.

@table @asis
@item @samp{mov@var{m}}
Here @var{m} stands for a two-letter machine mode name, in lower case.
This instruction pattern moves data with that machine mode from operand
1 to operand 0.  For example, @samp{movsi} moves full-word data.

If operand 0 is a @code{subreg} with mode @var{m} of a register whose
own mode is wider than @var{m}, the effect of this instruction is
to store the specified value in the part of the register that corresponds
to mode @var{m}.  The effect on the rest of the register is undefined.

This class of patterns is special in several ways.  First of all, each
of these names @emph{must} be defined, because there is no other way
to copy a datum from one place to another.

Second, these patterns are not used solely in the RTL generation pass.
Even the reload pass can generate move insns to copy values from stack
slots into temporary registers.  When it does so, one of the operands is
a hard register and the other is an operand that can need to be reloaded
into a register.

Therefore, when given such a pair of operands, the pattern must generate
RTL which needs no reloading and needs no temporary registers---no
registers other than the operands.  For example, if you support the
pattern with a @code{define_expand}, then in such a case the
@code{define_expand} mustn't call @code{force_reg} or any other such
function which might generate new pseudo registers.

This requirement exists even for subword modes on a RISC machine where
fetching those modes from memory normally requires several insns and
some temporary registers.  Look in @file{spur.md} to see how the
requirement can be satisfied.

The variety of operands that have reloads depends on the rest of the
machine description, but typically on a RISC machine these can only be
pseudo registers that did not get hard registers, while on other
machines explicit memory references will get optional reloads.

The constraints on a @samp{move@var{m}} must allow any hard register to
be moved to any other hard register (provided that
@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers).

It is obligatory to support floating point @samp{move@var{m}}
instructions into and out of any registers that can hold fixed point
values, because unions and structures (which have modes @code{SImode} or
@code{DImode}) can be in those registers and they may have floating
point members.

There may also be a need to support fixed point @samp{move@var{m}}
instructions in and out of floating point registers.  Unfortunately, I
have forgotten why this was so, and I don't know whether it is still
true.  If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
floating point registers, then the constraints of the fixed point
@samp{move@var{m}} instructions must be designed to avoid ever trying to
reload into a floating point register.

@item @samp{movstrict@var{m}}
Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
with mode @var{m} of a register whose natural mode is wider,
the @samp{movstrict@var{m}} instruction is guaranteed not to alter
any of the register except the part which belongs to mode @var{m}.

@item @samp{add@var{m}3}
Add operand 2 and operand 1, storing the result in operand 0.  All operands
must have mode @var{m}.  This can be used even on two-address machines, by
means of constraints requiring operands 1 and 0 to be the same location.

@item @samp{sub@var{m}3}, @samp{mul@var{m}3}, @samp{umul@var{m}3}, @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}, @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
Similar, for other arithmetic operations.

There are special considerations for register classes for logical-and
instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
They apply not only to the patterns with these standard names, but to
any patterns that will match such an instruction.  @xref{Register
Classes}.

@item @samp{mulhisi3}
Multiply operands 1 and 2, which have mode @code{HImode}, and store
a @code{SImode} product in operand 0.

@item @samp{mulqihi3}, @samp{mulsidi3}
Similar widening-multiplication instructions of other widths.

@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
Similar widening-multiplication instructions that do unsigned
multiplication.

@item @samp{divmod@var{m}4}
Signed division that produces both a quotient and a remainder.
Operand 1 is divided by operand 2 to produce a quotient stored
in operand 0 and a remainder stored in operand 3.

@item @samp{udivmod@var{m}4}
Similar, but does unsigned division.

@item @samp{ashl@var{m}3}
Arithmetic-shift operand 1 left by a number of bits specified by
operand 2, and store the result in operand 0.  Operand 2 has
mode @code{SImode}, not mode @var{m}.

@item @samp{ashr@var{m}3}, @samp{lshl@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
Other shift and rotate instructions.

Logical and arithmetic left shift are the same.  Machines that do not
allow negative shift counts often have only one instruction for
shifting left.  On such machines, you should define a pattern named
@samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.

There are special considerations for register classes for shift
instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
They apply not only to the patterns with these standard names, but to
any patterns that will match such an instruction.  @xref{Register
Classes}.

@item @samp{neg@var{m}2}
Negate operand 1 and store the result in operand 0.

@item @samp{abs@var{m}2}
Store the absolute value of operand 1 into operand 0.

@item @samp{sqrt@var{m}2}
Store the square root of operand 1 into operand 0.

@item @samp{ffs@var{m}2}
Store into operand 0 one plus the index of the least significant 1-bit
of operand 1.  If operand 1 is zero, store zero.  @var{m} is the mode
of operand 0; operand 1's mode is specified by the instruction
pattern, and the compiler will convert the operand to that mode before
generating the instruction.

@item @samp{one_cmpl@var{m}2}
Store the bitwise-complement of operand 1 into operand 0.

@item @samp{cmp@var{m}}
Compare operand 0 and operand 1, and set the condition codes.
The RTL pattern should look like this:

@example
(set (cc0) (compare (match_operand:@var{m} 0 @dots{})
                    (match_operand:@var{m} 1 @dots{})))
@end example

Each such definition in the machine description, for integer mode
@var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
optimization can simplify the compare into a test when operand 1 is
zero.

@item @samp{tst@var{m}}
Compare operand 0 against zero, and set the condition codes.
The RTL pattern should look like this:

@example
(set (cc0) (match_operand:@var{m} 0 @dots{}))
@end example

@item @samp{movstr@var{m}}
Block move instruction.  The addresses of the destination and source
strings are the first two operands, and both are in mode @code{Pmode}.
The number of bytes to move is the third operand, in mode @var{m}.
The fourth operand is the known shared alignment of the source and
destination, in the form of a @code{const_int} rtx.

@item @samp{cmpstr@var{m}}
Block compare instruction, with operands like @samp{movstr@var{m}}
except that the two memory blocks are compared byte by byte
in lexicographic order.  The effect of the instruction is to set
the condition codes.

@item @samp{float@var{m}@var{n}2}
Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
floating point mode @var{n} and store in operand 0 (which has mode
@var{n}).

@item @samp{floatuns@var{m}@var{n}2}
Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
to floating point mode @var{n} and store in operand 0 (which has mode
@var{n}).

@item @samp{fix@var{m}@var{n}2}
Convert operand 1 (valid for floating point mode @var{m}) to fixed
point mode @var{n} as a signed number and store in operand 0 (which
has mode @var{n}).  This instruction's result is defined only when
the value of operand 1 is an integer.

@item @samp{fixuns@var{m}@var{n}2}
Convert operand 1 (valid for floating point mode @var{m}) to fixed
point mode @var{n} as an unsigned number and store in operand 0 (which
has mode @var{n}).  This instruction's result is defined only when the
value of operand 1 is an integer.

@item @samp{ftrunc@var{m}2}
Convert operand 1 (valid for floating point mode @var{m}) to an
integer value, still represented in floating point mode @var{m}, and
store it in operand 0 (valid for floating point mode @var{m}).

@item @samp{fix_trunc@var{m}@var{n}2}
Like @samp{fix@var{m}@var{n}2} but works for any floating point value
of mode @var{m} by converting the value to an integer.

@item @samp{fixuns_trunc@var{m}@var{n}2}
Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
value of mode @var{m} by converting the value to an integer.

@item @samp{trunc@var{m}@var{n}}
Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
store in operand 0 (which has mode @var{n}).  Both modes must be fixed
point or both floating point.

@item @samp{extend@var{m}@var{n}}
Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
store in operand 0 (which has mode @var{n}).  Both modes must be fixed
point or both floating point.

@item @samp{zero_extend@var{m}@var{n}}
Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
store in operand 0 (which has mode @var{n}).  Both modes must be fixed
point.

@item @samp{extv}
Extract a bit-field from operand 1 (a register or memory operand),
where operand 2 specifies the width in bits and operand 3 the starting
bit, and store it in operand 0.  Operand 0 must have @code{SImode}.
Operand 1 may have mode @code{QImode} or @code{SImode}; often
@code{SImode} is allowed only for registers.  Operands 2 and 3 must be
valid for @code{SImode}.

The RTL generation pass generates this instruction only with constants
for operands 2 and 3.

The bit-field value is sign-extended to a full word integer
before it is stored in operand 0.

@item @samp{extzv}
Like @samp{extv} except that the bit-field value is zero-extended.

@item @samp{insv}
Store operand 3 (which must be valid for @code{SImode}) into a
bit-field in operand 0, where operand 1 specifies the width in bits
and operand 2 the starting bit.  Operand 0 may have mode @code{QImode}
or @code{SImode}; often @code{SImode} is allowed only for registers.
Operands 1 and 2 must be valid for @code{SImode}.

The RTL generation pass generates this instruction only with constants
for operands 1 and 2.

@item @samp{s@var{cond}}
Store zero or nonzero in the operand according to the condition codes.
Value stored is nonzero iff the condition @var{cond} is true.
@var{cond} is the name of a comparison operation expression code, such
as @code{eq}, @code{lt} or @code{leu}.

You specify the mode that the operand must have when you write the
@code{match_operand} expression.  The compiler automatically sees
which mode you have used and supplies an operand of that mode.

The value stored for a true condition must have 1 as its low bit, or
else must be negative.  Otherwise the instruction is not suitable and
must be omitted from the machine description.  You must tell the
compiler exactly which value is stored by defining the macro
@code{STORE_FLAG_VALUE}.

@item @samp{b@var{cond}}
Conditional branch instruction.  Operand 0 is a @code{label_ref}
that refers to the label to jump to.  Jump if the condition codes
meet condition @var{cond}.

@item @samp{call}
Subroutine call instruction returning no value.  Operand 0 is the
function to call; operand 1 is the number of bytes of arguments pushed
(in mode @code{SImode}, except it is normally a @code{const_int});
operand 2 is the number of registers used as operands.

On most machines, operand 2 is not actually stored into the RTL
pattern.  It is supplied for the sake of some RISC machines which need
to put this information into the assembler code; they can put it in
the RTL instead of operand 1.

Operand 0 should be a @code{mem} RTX whose address is the address of
the function.

@item @samp{call_value}
Subroutine call instruction returning a value.  Operand 0 is the hard
register in which the value is returned.  There are three more
operands, the same as the three operands of the @samp{call}
instruction (but with numbers increased by one).

Subroutines that return @code{BLKmode} objects use the @samp{call}
insn.

@item @samp{return}
Subroutine return instruction.  This instruction pattern name should be
defined only if a single instruction can do all the work of returning
from a function.

@item @samp{nop}
No-op instruction.  This instruction pattern name should always be defined
to output a no-op in assembler code.  @code{(const_int 0)} will do as an
RTL pattern.

@item @samp{casesi}
Instruction to jump through a dispatch table, including bounds checking.
This instruction takes five operands:

@enumerate
@item
The index to dispatch on, which has mode @code{SImode}.

@item
The lower bound for indices in the table, an integer constant.

@item
The total range of indices in the table---the largest index
minus the smallest one (both inclusive).

@item
A label to jump to if the index has a value outside the bounds.
(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
then an out-of-bounds index drops through to the code following
the jump table instead of jumping to this label.  In that case,
this label is not actually used by the @samp{casesi} instruction,
but it is always provided as an operand.)

@item
A label that precedes the table itself.
@end enumerate

The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
@code{jump_insn}.  The number of elements in the table is one plus the
difference between the upper bound and the lower bound.

@item @samp{tablejump}
Instruction to jump to a variable address.  This is a low-level
capability which can be used to implement a dispatch table when there
is no @samp{casesi} pattern.

This pattern requires two operands: the address or offset, and a label
which should immediately precede the jump table.  If the macro
@code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
offset that counts from the address of the table; otherwise, it is an
absolute address to jump to.

The @samp{tablejump} insn is always the last insn before the jump
table it uses.  Its assembler code normally has no need to use the
second operand, but you should incorporate it in the RTL pattern so
that the jump optimizer will not delete the table as unreachable code.
@end table

@node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
@section When the Order of Patterns Matters

Sometimes an insn can match more than one instruction pattern.  Then the
pattern that appears first in the machine description is the one used.
Therefore, more specific patterns (patterns that will match fewer things)
and faster instructions (those that will produce better code when they
do match) should usually go first in the description.

In some cases the effect of ordering the patterns can be used to hide
a pattern when it is not valid.  For example, the 68000 has an
instruction for converting a fullword to floating point and another
for converting a byte to floating point.  An instruction converting
an integer to floating point could match either one.  We put the
pattern to convert the fullword first to make sure that one will
be used rather than the other.  (Otherwise a large integer might
be generated as a single-byte immediate quantity, which would not work.)
Instead of using this pattern ordering it would be possible to make the
pattern for convert-a-byte smart enough to deal properly with any
constant value.

@node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
@section Interdependence of Patterns

Every machine description must have a named pattern for each of the
conditional branch names @samp{b@var{cond}}.  The recognition template
must always have the form

@example
(set (pc)
     (if_then_else (@var{cond} (cc0) (const_int 0))
                   (label_ref (match_operand 0 "" ""))
                   (pc)))
@end example

@noindent
In addition, every machine description must have an anonymous pattern
for each of the possible reverse-conditional branches.  These patterns
look like

@example
(set (pc)
     (if_then_else (@var{cond} (cc0) (const_int 0))
                   (pc)
                   (label_ref (match_operand 0 "" ""))))
@end example

@noindent
They are necessary because jump optimization can turn direct-conditional
branches into reverse-conditional branches.

The compiler does more with RTL than just create it from patterns
and recognize the patterns: it can perform arithmetic expression codes
when constant values for their operands can be determined.  As a result,
sometimes having one pattern can require other patterns.  For example, the
Vax has no `and' instruction, but it has `and not' instructions.  Here
is the definition of one of them:

@example
(define_insn "andcbsi2"
  [(set (match_operand:SI 0 "general_operand" "")
        (and:SI (match_dup 0)
                (not:SI (match_operand:SI
                          1 "general_operand" ""))))]
  ""
  "bicl2 %1,%0")
@end example

@noindent
If operand 1 is an explicit integer constant, an instruction constructed
using that pattern can be simplified into an `and' like this:

@example
(set (reg:SI 41)
     (and:SI (reg:SI 41)
             (const_int 0xffff7fff)))
@end example

@noindent
(where the integer constant is the one's complement of what
appeared in the original instruction).

To avoid a fatal error, the compiler must have a pattern that recognizes
such an instruction.  Here is what is used:

@example
(define_insn ""
  [(set (match_operand:SI 0 "general_operand" "")
        (and:SI (match_dup 0)
                (match_operand:SI 1 "general_operand" "")))]
  "GET_CODE (operands[1]) == CONST_INT"
  "*
@{ operands[1]
    = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
  return \"bicl2 %1,%0\";
@}")
@end example

@noindent
Whereas a pattern to match a general `and' instruction is impossible to
support on the Vax, this pattern is possible because it matches only a
constant second argument: a special case that can be output as an `and not'
instruction.

A ``compare'' instruction whose RTL looks like this:

@example
(set (cc0) (compare @var{operand} (const_int 0)))
@end example

@noindent
may be simplified by optimization into a ``test'' like this:

@example
(set (cc0) @var{operand})
@end example

@noindent
So in the machine description, each ``compare'' pattern for an integer
mode must have a corresponding ``test'' pattern that will match the
result of such simplification.

In some cases machines support instructions identical except for the
machine mode of one or more operands.  For example, there may be
``sign-extend halfword'' and ``sign-extend byte'' instructions whose
patterns are

@example
(set (match_operand:SI 0 @dots{})
     (extend:SI (match_operand:HI 1 @dots{})))

(set (match_operand:SI 0 @dots{})
     (extend:SI (match_operand:QI 1 @dots{})))
@end example

@noindent
Constant integers do not specify a machine mode, so an instruction to
extend a constant value could match either pattern.  The pattern it
actually will match is the one that appears first in the file.  For correct
results, this must be the one for the widest possible mode (@code{HImode},
here).  If the pattern matches the @code{QImode} instruction, the results
will be incorrect if the constant value does not actually fit that mode.

Such instructions to extend constants are rarely generated because they are
optimized away, but they do occasionally happen in nonoptimized
compilations.

When an instruction has the constraint letter @samp{o}, the reload
pass may generate instructions which copy a nonoffsettable address into
an index register.  The idea is that the register can be used as a
replacement offsettable address.  In order for these generated
instructions to work, there must be patterns to copy any kind of valid
address into a register.

Most older machine designs have ``load address'' instructions which do
just what is needed here.  Some RISC machines do not advertise such
instructions, but the possible addresses on these machines are very
limited, so it is easy to fake them.

Auto-increment and auto-decrement addresses are an exception; there
need not be an instruction that can copy such an address into a
register, because reload handles these cases in a different manner.

@node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
@section Defining Jump Instruction Patterns

GNU CC assumes that the machine has a condition code.  A comparison insn
sets the condition code, recording the results of both signed and unsigned
comparison of the given operands.  A separate branch insn tests the
condition code and branches or not according its value.  The branch insns
come in distinct signed and unsigned flavors.  Many common machines, such
as the Vax, the 68000 and the 32000, work this way.

Some machines have distinct signed and unsigned compare instructions, and
only one set of conditional branch instructions.  The easiest way to handle
these machines is to treat them just like the others until the final stage
where assembly code is written.  At this time, when outputting code for the
compare instruction, peek ahead at the following branch using
@code{NEXT_INSN (insn)}.  (The variable @code{insn} refers to the insn
being output, in the output-writing code in an instruction pattern.)  If
the RTL says that is an unsigned branch, output an unsigned compare;
otherwise output a signed compare.  When the branch itself is output, you
can treat signed and unsigned branches identically.

The reason you can do this is that GNU CC always generates a pair of
consecutive RTL insns, one to set the condition code and one to test it,
and keeps the pair inviolate until the end.

To go with this technique, you must define the machine-description macro
@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
compare instruction is superfluous.

Some machines have compare-and-branch instructions and no condition code.
A similar technique works for them.  When it is time to ``output'' a
compare instruction, record its operands in two static variables.  When
outputting the branch-on-condition-code instruction that follows, actually
output a compare-and-branch instruction that uses the remembered operands.

It also works to define patterns for compare-and-branch instructions.
In optimizing compilation, the pair of compare and branch instructions
will be combined according to these patterns.  But this does not happen
if optimization is not requested.  So you must use one of the solutions
above in addition to any special patterns you define.

@node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
@section Defining Machine-Specific Peephole Optimizers

In addition to instruction patterns the @file{md} file may contain
definitions of machine-specific peephole optimizations.

The combiner does not notice certain peephole optimizations when the data
flow in the program does not suggest that it should try them.  For example,
sometimes two consecutive insns related in purpose can be combined even
though the second one does not appear to use a register computed in the
first one.  A machine-specific peephole optimizer can detect such
opportunities.

A definition looks like this:

@example
(define_peephole
  [@var{insn-pattern-1}
   @var{insn-pattern-2}
   @dots{}]
  "@var{condition}"
  "@var{template}"
  "@var{machine-specific info}")
@end example

@noindent
The last string operand may be omitted if you are not using any
machine-specific information in this machine description.  If present,
it must obey the same rules as in a @code{define_insn}.

In this skeleton, @var{insn-pattern-1} and so on are patterns to match
consecutive insns.  The optimization applies to a sequence of insns when
@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
the next, and so on.@refill

Each of the insns matched by a peephole must also match a
@code{define_insn}.  Peepholes are checked only at the last stage just
before code generation, and only optionally.  Therefore, any insn which
would match a peephole but no @code{define_insn} will cause a crash in code
generation in an unoptimized compilation, or at various optimization
stages.

The operands of the insns are matched with @code{match_operands} and
@code{match_dup}, as usual.  What is not usual is that the operand numbers
apply to all the insn patterns in the definition.  So, you can check for
identical operands in two insns by using @code{match_operand} in one insn
and @code{match_dup} in the other.

The operand constraints used in @code{match_operand} patterns do not have
any direct effect on the applicability of the peephole, but they will
be validated afterward, so make sure your constraints are general enough
to apply whenever the peephole matches.  If the peephole matches
but the constraints are not satisfied, the compiler will crash.

It is safe to omit constraints in all the operands of the peephole; or
you can write constraints which serve as a double-check on the criteria
previously tested.

Once a sequence of insns matches the patterns, the @var{condition} is
checked.  This is a C expression which makes the final decision whether to
perform the optimization (we do so if the expression is nonzero).  If
@var{condition} is omitted (in other words, the string is empty) then the
optimization is applied to every sequence of insns that matches the
patterns.

The defined peephole optimizations are applied after register allocation
is complete.  Therefore, the peephole definition can check which
operands have ended up in which kinds of registers, just by looking at
the operands.

The way to refer to the operands in @var{condition} is to write
@code{operands[@var{i}]} for operand number @var{i} (as matched by
@code{(match_operand @var{i} @dots{})}).  Use the variable @code{insn} to
refer to the last of the insns being matched; use @code{PREV_INSN} to find
the preceding insns (but be careful to skip over any @code{note} insns that
intervene).@refill

When optimizing computations with intermediate results, you can use
@var{condition} to match only when the intermediate results are not used
elsewhere.  Use the C expression @code{dead_or_set_p (@var{insn},
@var{op})}, where @var{insn} is the insn in which you expect the value to
be used for the last time (from the value of @code{insn}, together with use
of @code{PREV_INSN}), and @var{op} is the intermediate value (from
@code{operands[@var{i}]}).@refill

Applying the optimization means replacing the sequence of insns with one
new insn.  The @var{template} controls ultimate output of assembler code
for this combined insn.  It works exactly like the template of a
@code{define_insn}.  Operand numbers in this template are the same ones
used in matching the original sequence of insns.

The result of a defined peephole optimizer does not need to match any of
the insn patterns in the machine description; it does not even have an
opportunity to match them.  The peephole optimizer definition itself serves
as the insn pattern to control how the insn is output.

Defined peephole optimizers are run as assembler code is being output,
so the insns they produce are never combined or rearranged in any way.

Here is an example, taken from the 68000 machine description:

@example
(define_peephole
  [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
   (set (match_operand:DF 0 "register_operand" "f")
        (match_operand:DF 1 "register_operand" "ad"))]
  "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
  "*
@{
  rtx xoperands[2];
  xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
#ifdef MOTOROLA
  output_asm_insn (\"move.l %1,(sp)\", xoperands);
  output_asm_insn (\"move.l %1,-(sp)\", operands);
  return \"fmove.d (sp)+,%0\";
#else
  output_asm_insn (\"movel %1,sp@@\", xoperands);
  output_asm_insn (\"movel %1,sp@@-\", operands);
  return \"fmoved sp@@+,%0\";
#endif
@}
")
@end example

The effect of this optimization is to change

@example
jbsr _foobar
addql #4,sp
movel d1,sp@@-
movel d0,sp@@-
fmoved sp@@+,fp0
@end example

@noindent
into

@example
jbsr _foobar
movel d1,sp@@
movel d0,sp@@-
fmoved sp@@+,fp0
@end example

@ignore
If a peephole matches a sequence including one or more jump insns, you must
take account of the flags such as @code{CC_REVERSED} which specify that the
condition codes are represented in an unusual manner.  The compiler
automatically alters any ordinary conditional jumps which occur in such
situations, but the compiler cannot alter jumps which have been replaced by
peephole optimizations.  So it is up to you to alter the assembler code
that the peephole produces.  Supply C code to write the assembler output,
and in this C code check the condition code status flags and change the
assembler code as appropriate.
@end ignore

@var{insn-pattern-1} and so on look @emph{almost} like the second
operand of @code{define_insn}.  There is one important difference: the
second operand of @code{define_insn} consists of one or more RTX's
enclosed in square brackets.  Usually, there is only one: then the same
action can be written as an element of a @code{define_peephole}.  But
when there are multiple actions in a @code{define_insn}, they are
implicitly enclosed in a @code{parallel}.  Then you must explicitly
write the @code{parallel}, and the square brackets within it, in the
@code{define_peephole}.  Thus, if an insn pattern looks like this,

@example
(define_insn "divmodsi4"
  [(set (match_operand:SI 0 "general_operand" "=d")
        (div:SI (match_operand:SI 1 "general_operand" "0")
                (match_operand:SI 2 "general_operand" "dmsK")))
   (set (match_operand:SI 3 "general_operand" "=d")
        (mod:SI (match_dup 1) (match_dup 2)))]
  "TARGET_68020"
  "divsl%.l %2,%3:%0")
@end example

@noindent
then the way to mention this insn in a peephole is as follows:

@example
(define_peephole
  [@dots{}
   (parallel
    [(set (match_operand:SI 0 "general_operand" "=d")
          (div:SI (match_operand:SI 1 "general_operand" "0")
                  (match_operand:SI 2 "general_operand" "dmsK")))
     (set (match_operand:SI 3 "general_operand" "=d")
          (mod:SI (match_dup 1) (match_dup 2)))])
   @dots{}]
  @dots{})
@end example

@node Expander Definitions,, Peephole Definitions, Machine Desc
@section Defining RTL Sequences for Code Generation

On some target machines, some standard pattern names for RTL generation
cannot be handled with single insn, but a sequence of RTL insns can
represent them.  For these target machines, you can write a
@code{define_expand} to specify how to generate the sequence of RTL.

A @code{define_expand} is an RTL expression that looks almost like a
@code{define_insn}; but, unlike the latter, a @code{define_expand} is used
only for RTL generation and it can produce more than one RTL insn.

A @code{define_expand} RTX has four operands:

@itemize @bullet
@item
The name.  Each @code{define_expand} must have a name, since the only
use for it is to refer to it by name.

@item
The RTL template.  This is just like the RTL template for a
@code{define_peephole} in that it is a vector of RTL expressions
each being one insn.

@item
The condition, a string containing a C expression.  This expression is
used to express how the availability of this pattern depends on
subclasses of target machine, selected by command-line options when
GNU CC is run.  This is just like the condition of a
@code{define_insn} that has a standard name.

@item
The preparation statements, a string containing zero or more C
statements which are to be executed before RTL code is generated from
the RTL template.

Usually these statements prepare temporary registers for use as
internal operands in the RTL template, but they can also generate RTL
insns directly by calling routines such as @code{emit_insn}, etc.
Any such insns precede the ones that come from the RTL template.
@end itemize

Every RTL insn emitted by a @code{define_expand} must match some
@code{define_insn} in the machine description.  Otherwise, the compiler
will crash when trying to generate code for the insn or trying to optimize
it.

The RTL template, in addition to controlling generation of RTL insns,
also describes the operands that need to be specified when this pattern
is used.  In particular, it gives a predicate for each operand.

A true operand, which need to be specified in order to generate RTL from
the pattern, should be described with a @code{match_operand} in its first
occurrence in the RTL template.  This enters information on the operand's
predicate into the tables that record such things.  GNU CC uses the
information to preload the operand into a register if that is required for
valid RTL code.  If the operand is referred to more than once, subsequent
references should use @code{match_dup}.

The RTL template may also refer to internal ``operands'' which are
temporary registers or labels used only within the sequence made by the
@code{define_expand}.  Internal operands are substituted into the RTL
template with @code{match_dup}, never with @code{match_operand}.  The
values of the internal operands are not passed in as arguments by the
compiler when it requests use of this pattern.  Instead, they are computed
within the pattern, in the preparation statements.  These statements
compute the values and store them into the appropriate elements of
@code{operands} so that @code{match_dup} can find them.

There are two special macros defined for use in the preparation statements:
@code{DONE} and @code{FAIL}.  Use them with a following semicolon,
as a statement.

@table @code
@item DONE
Use the @code{DONE} macro to end RTL generation for the pattern.  The
only RTL insns resulting from the pattern on this occasion will be
those already emitted by explicit calls to @code{emit_insn} within the
preparation statements; the RTL template will not be generated.

@item FAIL
Make the pattern fail on this occasion.  When a pattern fails, it means
that the pattern was not truly available.  The calling routines in the
compiler will try other strategies for code generation using other patterns.

Failure is currently supported only for binary operations (addition,
multiplication, shifting, etc.).

Do not emit any insns explicitly with @code{emit_insn} before failing.
@end table

Here is an example, the definition of left-shift for the SPUR chip:

@example
(define_expand "ashlsi3"
  [(set (match_operand:SI 0 "register_operand" "")
        (ashift:SI
          (match_operand:SI 1 "register_operand" "")
          (match_operand:SI 2 "nonmemory_operand" "")))]
  ""
  "
@{
  if (GET_CODE (operands[2]) != CONST_INT
      || (unsigned) INTVAL (operands[2]) > 3)
    FAIL;
@}")
@end example

@noindent
This example uses @code{define_expand} so that it can generate an RTL insn
for shifting when the shift-count is in the supported range of 0 to 3 but
fail in other cases where machine insns aren't available.  When it fails,
the compiler tries another strategy using different patterns (such as, a
library call).

If the compiler were able to handle nontrivial condition-strings in
patterns with names, then it would be possible to use a
@code{define_insn} in that case.  Here is another case (zero-extension
on the 68000) which makes more use of the power of @code{define_expand}:

@example
(define_expand "zero_extendhisi2"
  [(set (match_operand:SI 0 "general_operand" "")
        (const_int 0))
   (set (strict_low_part 
          (subreg:HI
            (match_dup 0)
            0))
        (match_operand:HI 1 "general_operand" ""))]
  ""
  "operands[1] = make_safe_from (operands[1], operands[0]);")
@end example

@noindent
Here two RTL insns are generated, one to clear the entire output operand
and the other to copy the input operand into its low half.  This sequence
is incorrect if the input operand refers to [the old value of] the output
operand, so the preparation statement makes sure this isn't so.  The
function @code{make_safe_from} copies the @code{operands[1]} into a
temporary register if it refers to @code{operands[0]}.  It does this
by emitting another RTL insn.

Finally, a third example shows the use of an internal operand.
Zero-extension on the SPUR chip is done by @code{and}-ing the result
against a halfword mask.  But this mask cannot be represented by a
@code{const_int} because the constant value is too large to be legitimate
on this machine.  So it must be copied into a register with
@code{force_reg} and then the register used in the @code{and}.

@example
(define_expand "zero_extendhisi2"
  [(set (match_operand:SI 0 "register_operand" "")
        (and:SI (subreg:SI
                  (match_operand:HI 1 "register_operand" "")
                  0)
                (match_dup 2)))]
  ""
  "operands[2]
     = force_reg (SImode, gen_rtx (CONST_INT,
                                   VOIDmode, 65535)); ")
@end example

@strong{Note:} If the @code{define_expand} is used to serve a standard
binary or unary arithmetic operation, then the last insn it generates
must not be a @code{code_label}, @code{barrier} or @code{note}.  It must
be an @code{insn}, @code{jump_insn} or @code{call_insn}.

@node Machine Macros, Config, Machine Desc, Top
@chapter Machine Description Macros

The other half of the machine description is a C header file conventionally
given the name @file{tm-@var{machine}.h}.  The file @file{tm.h} should be a
link to it.  The header file @file{config.h} includes @file{tm.h} and most
compiler source files include @file{config.h}.

@menu
* Run-time Target::     Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}.
* Storage Layout::      Defining sizes and alignments of data types.
* Registers::           Naming and describing the hardware registers.
* Register Classes::    Defining the classes of hardware registers.
* Stack Layout::        Defining which way the stack grows and by how much.
* Library Calls::       Specifying how to call certain library routines.
* Addressing Modes::    Defining addressing modes valid for memory operands.
* Delayed Branch::      Do branches execute the following instruction?
* Condition Code::      Defining how insns update the condition code.
* Cross-compilation::   Handling floating point for cross-compilers.
* Misc::                Everything else.
* Assembler Format::    Defining how to write insns and pseudo-ops to output.
@end menu

@node Run-time Target, Storage Layout, Machine Macros, Machine Macros
@section Run-time Target Specification

@table @code
@item CPP_PREDEFINES
Define this to be a string constant containing @samp{-D} options to
define the predefined macros that identify this machine and system.
These macros will be predefined unless the @samp{-ansi} option is
specified.

In addition, a parallel set of macros are predefined, whose names are
made by appending @samp{__} at the beginning and at the end.  These
@samp{__} macros are permitted by the ANSI standard, so they are
predefined regardless of whether @samp{-ansi} is specified.

For example, on the Sun, one can use the following value:

@example
"-Dmc68000 -Dsun -Dunix"
@end example

The result is to define the macros @code{__mc68000__}, @code{__sun__}
and @code{__unix__} unconditionally, and the macros @code{mc68000},
@code{sun} and @code{unix} provided @samp{-ansi} is not specified.

@item CPP_SPEC
A C string constant that tells the GNU CC driver program options to
pass to CPP.  It can also specify how to translate options you
give to GNU CC into options for GNU CC to pass to the CPP.

Do not define this macro if it does not need to do anything.

@item CC1_SPEC
A C string constant that tells the GNU CC driver program options to
pass to CC1.  It can also specify how to translate options you
give to GNU CC into options for GNU CC to pass to the CC1.

Do not define this macro if it does not need to do anything.

@item extern int target_flags;
This declaration should be present.

@item TARGET_@dots{}
This series of macros is to allow compiler command arguments to
enable or disable the use of optional features of the target machine.
For example, one machine description serves both the 68000 and
the 68020; a command argument tells the compiler whether it should
use 68020-only instructions or not.  This command argument works
by means of a macro @code{TARGET_68020} that tests a bit in
@code{target_flags}.

Define a macro @code{TARGET_@var{featurename}} for each such option.
Its definition should test a bit in @code{target_flags}; for example:

@example
#define TARGET_68020 (target_flags & 1)
@end example

One place where these macros are used is in the condition-expressions
of instruction patterns.  Note how @code{TARGET_68020} appears
frequently in the 68000 machine description file, @file{m68k.md}.
Another place they are used is in the definitions of the other
macros in the @file{tm-@var{machine}.h} file.

@item TARGET_SWITCHES
This macro defines names of command options to set and clear
bits in @code{target_flags}.  Its definition is an initializer
with a subgrouping for each command option.

Each subgrouping contains a string constant, that defines the option
name, and a number, which contains the bits to set in
@code{target_flags}.  A negative number says to clear bits instead;
the negative of the number is which bits to clear.  The actual option
name is made by appending @samp{-m} to the specified name.

One of the subgroupings should have a null string.  The number in
this grouping is the default value for @code{target_flags}.  Any
target options act starting with that value.

Here is an example which defines @samp{-m68000} and @samp{-m68020}
with opposite meanings, and picks the latter as the default:

@example
#define TARGET_SWITCHES \
  @{ @{ "68020", 1@},      \
    @{ "68000", -1@},     \
    @{ "", 1@}@}
@end example

@item OVERRIDE_OPTIONS
Sometimes certain combinations of command options do not make sense on
a particular target machine.  You can define a macro
@code{OVERRIDE_OPTIONS} to take account of this.  This macro, if
defined, is executed once just after all the command options have been
parsed.
@end table

@node Storage Layout, Registers, Run-time Target, Machine Macros
@section Storage Layout

Note that the definitions of the macros in this table which are sizes or
alignments measured in bits do not need to be constant.  They can be C
expressions that refer to static variables, such as the @code{target_flags}.
@xref{Run-time Target}.

@table @code
@item BITS_BIG_ENDIAN
Define this macro if the most significant bit in a byte has the lowest
number.  This means that bit-field instructions count from the most
significant bit.  If the machine has no bit-field instructions, this
macro is irrelevant.

This macro does not affect the way structure fields are packed into
bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.

@item BYTES_BIG_ENDIAN
Define this macro if the most significant byte in a word has the
lowest number.

@item WORDS_BIG_ENDIAN
Define this macro if, in a multiword object, the most significant
word has the lowest number.

@item BITS_PER_UNIT
Number of bits in an addressable storage unit (byte); normally 8.

@item BITS_PER_WORD
Number of bits in a word; normally 32.

@item UNITS_PER_WORD
Number of storage units in a word; normally 4.

@item POINTER_SIZE
Width of a pointer, in bits.

@item POINTER_BOUNDARY
Alignment required for pointers stored in memory, in bits.

@item PARM_BOUNDARY
Normal alignment required for function parameters on the stack, in
bits.  All stack parameters receive least this much alignment
regardless of data type.  On most machines, this is the same as the
size of an integer.

@item MAX_PARM_BOUNDARY
Largest alignment required for any stack parameters, in bits.  If the
data type of the parameter calls for more alignment than
@code{PARM_BOUNDARY}, then it is given extra padding up to this limit.

Don't define this macro if it would be equal to @code{PARM_BOUNDARY};
in other words, if the alignment of a stack parameter should not
depend on its data type (as is the case on most machines).

@item STACK_BOUNDARY
Define this macro if you wish to preserve a certain alignment for
the stack pointer at all times.  The definition is a C expression
for the desired alignment (measured in bits).

@item FUNCTION_BOUNDARY
Alignment required for a function entry point, in bits.

@item BIGGEST_ALIGNMENT
Biggest alignment that any data type can require on this machine, in bits.

@item CONSTANT_ALIGNMENT (@var{code}, @var{typealign})
A C expression to compute the alignment for a constant.  The argument
@var{typealign} is the alignment required for the constant's data type.
@var{code} is the tree code of the constant itself.

If this macro is not defined, the default is to use @var{typealign}.  If
you do define this macro, the value must be a multiple of
@var{typealign}.

The purpose of defining this macro is usually to cause string constants
to be word aligned so that @file{dhrystone} can be made to run faster.

@item EMPTY_FIELD_BOUNDARY
Alignment in bits to be given to a structure bit field that follows an
empty field such as @code{int : 0;}.

@item STRUCTURE_SIZE_BOUNDARY
Number of bits which any structure or union's size must be a multiple of.
Each structure or union's size is rounded up to a multiple of this.

If you do not define this macro, the default is the same as
@code{BITS_PER_UNIT}.

@item STRICT_ALIGNMENT
Define this if instructions will fail to work if given data not
on the nominal alignment.  If instructions will merely go slower
in that case, do not define this macro.

@item PCC_BITFIELD_TYPE_MATTERS
Define this if you wish to imitate a certain bizarre behavior pattern
of some instances of PCC: a bit field whose declared type is
@code{int} has the same effect on the size and alignment of a
structure as an actual @code{int} would have.

If the macro is defined, then its definition should be a C expression; 
a nonzero value for the expression enables PCC-compatible behavior.

Just what effect that is in GNU CC depends on other parameters, but on
most machines it would force the structure's alignment and size to a
multiple of 32 or @code{BIGGEST_ALIGNMENT} bits.

@item MAX_FIXED_MODE_SIZE
An integer expression for the largest integer machine mode that should
actually be used.  All integer machine modes of this size or smaller
can be used for structures and unions with the appropriate sizes.

@item CHECK_FLOAT_VALUE (@var{mode}, @var{value})
A C statement to validate the value @var{value} (or type
@code{double}) for mode @var{mode}.  This means that you check whether
@var{value} fits within the possible range of values for mode
@var{mode} on this target machine.  The mode @var{mode} is always
@code{SFmode} or @code{DFmode}.

If @var{value} is not valid, you should call @code{error} to print an
error message and then assign some valid value to @var{value}.
Allowing an invalid value to go through the compiler can produce
incorrect assembler code which may even cause Unix assemblers to
crash.

This macro need not be defined if there is no work for it to do.
@end table

@node Registers, Register Classes, Storage Layout, Machine Macros
@section Register Usage

@table @code
@item FIRST_PSEUDO_REGISTER
Number of hardware registers known to the compiler.  They receive
numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
pseudo register's number really is assigned the number
@code{FIRST_PSEUDO_REGISTER}.

@item FIXED_REGISTERS
An initializer that says which registers are used for fixed purposes
all throughout the compiled code and are therefore not available for
general allocation.  These would include the stack pointer, the frame
pointer (except on machines where that can be used as a general
register when no frame pointer is needed), the program counter on
machines where that is considered one of the addressable registers,
and any other numbered register with a standard use.

This information is expressed as a sequence of numbers, separated by
commas and surrounded by braces.  The @var{n}th number is 1 if
register @var{n} is fixed, 0 otherwise.

The table initialized from this macro, and the table initialized by
the following one, may be overridden at run time either automatically,
by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
the user with the command options @samp{-ffixed-@var{reg}},
@samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.

@item CALL_USED_REGISTERS
Like @code{FIXED_REGISTERS} but has 1 for each register that is
clobbered (in general) by function calls as well as for fixed
registers.  This macro therefore identifies the registers that are not
available for general allocation of values that must live across
function calls.

If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
automatically saves it on function entry and restores it on function
exit, if the register is used within the function.

@item DEFAULT_CALLER_SAVES
Define this macro if function calls on the target machine do not preserve
any registers; in other words, if @code{CALL_USED_REGISTERS} has 1
for all registers.  This macro enables @samp{-fcaller-saves} by default.
Eventually that option will be enabled by default on all machines and both
the option and this macro will be eliminated.

@item CONDITIONAL_REGISTER_USAGE
Zero or more C statements that may conditionally modify two variables
@code{fixed_regs} and @code{call_used_regs} (both of type @code{char
[]}) after they have been initialized from the two preceding macros.

This is necessary in case the fixed or call-clobbered registers depend
on target flags.

You need not define this macro if it has no work to do.

If the usage of an entire class of registers depends on the target
flags, you may indicate this to GCC by using this macro to modify
@code{fixed_regs} and @code{call_used_regs} to 1 for each of the
registers in the classes which should not be used by GCC.  Also define
the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
is called with a letter for a class that shouldn't be used.

(However, if this class is not included in @code{GENERAL_REGS} and all
of the insn patterns whose constraints permit this class are
controlled by target switches, then GCC will automatically avoid using
these registers when the target switches are opposed to them.)

@item OVERLAPPING_REGNO_P (@var{regno})
If defined, this is a C expression whose value is nonzero if hard
register number @var{regno} is an overlapping register.  This means a
hard register which overlaps a hard register with a different number.
(Such overlap is undesirable, but occasionally it allows a machine to
be supported which otherwise could not be.)  This macro must return
nonzero for @emph{all} the registers which overlap each other.  GNU CC
can use an overlapping register only in certain limited ways.  It can
be used for allocation within a basic block, and may be spilled for
reloading; that is all.

If this macro is not defined, it means that none of the hard registers
overlap each other.  This is the usual situation.

@item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
If defined, this is a C expression whose value should be nonzero if
the insn @var{insn} has the effect of mysteriously clobbering the
contents of hard register number @var{regno}.  By ``mysterious'' we
mean that the insn's RTL expression doesn't describe such an effect.

If this macro is not defined, it means that no insn clobbers registers
mysteriously.  This is the usual situation; all else being equal,
it is best for the RTL expression to show all the activity.

@item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
If defined, this is a C expression whose value is nonzero if accurate
@code{REG_DEAD} notes are needed for hard register number @var{regno}
at the time of outputting the assembler code.  When this is so, a few
optimizations that take place after register allocation and could
invalidate the death notes are not done when this register is
involved.

You would arrange to preserve death info for a register when some of the
code in the machine description which is executed to write the assembler
code looks at the death notes.  This is necessary only when the actual
hardware feature which GNU CC thinks of as a register is not actually a
register of the usual sort.  (It might, for example, be a hardware
stack.)

If this macro is not defined, it means that no death notes need to be
preserved.  This is the usual situation.

@item HARD_REGNO_NREGS (@var{regno}, @var{mode})
A C expression for the number of consecutive hard registers, starting
at register number @var{regno}, required to hold a value of mode
@var{mode}.

On a machine where all registers are exactly one word, a suitable
definition of this macro is

@example
#define HARD_REGNO_NREGS(REGNO, MODE)            \
   ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1)  \
    / UNITS_PER_WORD))
@end example

@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
A C expression that is nonzero if it is permissible to store a value
of mode @var{mode} in hard register number @var{regno} (or in several
registers starting with that one).  For a machine where all registers
are equivalent, a suitable definition is

@example
#define HARD_REGNO_MODE_OK(REGNO, MODE) 1
@end example

It is not necessary for this macro to check for the numbers of fixed
registers, because the allocation mechanism considers them to be always
occupied.

On some machines, double-precision values must be kept in even/odd
register pairs.  The way to implement that is to define this macro
to reject odd register numbers for such modes.

GNU CC assumes that it can always move values between registers and
(suitably addressed) memory locations.  If it is impossible to move a
value of a certain mode between memory and certain registers, then
@code{HARD_REGNO_MODE_OK} must not allow this mode in those registers.

Many machines have special registers for floating point arithmetic.
Often people assume that floating point machine modes are allowed only
in floating point registers.  This is not true.  Any registers that
can hold integers can safely @emph{hold} a floating point machine
mode, whether or not floating arithmetic can be done on it in those
registers.

On some machines, though, the converse is true: fixed-point machine
modes may not go in floating registers.  This is true if the floating
registers normalize any value stored in them, because storing a
non-floating value there would garble it.  In this case,
@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
floating registers.  But if the floating registers do not automatically
normalize, if you can store any bit pattern in one and retrieve it
unchanged without a trap, then any machine mode may go in a floating
register and this macro should say so.

The primary significance of special floating registers is rather that
they are the registers acceptable in floating point arithmetic
instructions.  However, this is of no concern to
@code{HARD_REGNO_MODE_OK}.  You handle it by writing the proper
constraints for those instructions.

On some machines, the floating registers are especially slow to access,
so that it is better to store a value in a stack frame than in such a
register if floating point arithmetic is not being done.  As long as the
floating registers are not in class @code{GENERAL_REGS}, they will not
be used unless some insn's constraint asks for one.

@item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
A C expression that is nonzero if it is desirable to choose register
allocation so as to avoid move instructions between a value of mode
@var{mode1} and a value of mode @var{mode2}.

If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
@var{mode2})} must be zero.

@item PC_REGNUM
If the program counter has a register number, define this as that
register number.  Otherwise, do not define it.

@item STACK_POINTER_REGNUM
The register number of the stack pointer register, which must also be
a fixed register according to @code{FIXED_REGISTERS}.  On many
machines, the hardware determines which register this is.

@item FRAME_POINTER_REGNUM
The register number of the frame pointer register, which is used to
access automatic variables in the stack frame.  On some machines, the
hardware determines which register this is.  On other machines, you
can choose any register you wish for this purpose.

@item FRAME_POINTER_REQUIRED
A C expression which is nonzero if a function must have and use a frame
pointer.  This expression is evaluated twice: at the beginning of
generating RTL, and in the reload pass.  If its value is nonzero at
either time, then the function will have a frame pointer.

The expression can in principle examine the current function and decide
according to the facts, but on most machines the constant 0 or the
constant 1 suffices.  Use 0 when the machine allows code to be generated
with no frame pointer, and doing so saves some time or space.  Use 1
when there is no possible advantage to avoiding a frame pointer.

In certain cases, the compiler does not know how to produce valid code
without a frame pointer.  The compiler recognizes those cases and
automatically gives the function a frame pointer regardless of what
@code{FRAME_POINTER_REQUIRED} says.  You don't need to worry about
them.@refill

In a function that does not require a frame pointer, the frame pointer
register can be allocated for ordinary usage, unless you mark it as a
fixed register.  See @code{FIXED_REGISTERS} for more information.

@item ARG_POINTER_REGNUM
The register number of the arg pointer register, which is used to
access the function's argument list.  On some machines, this is the
same as the frame pointer register.  On some machines, the hardware
determines which register this is.  On other machines, you can choose
any register you wish for this purpose.  If this is not the same
register as the frame pointer register, then you must mark it as a
fixed register according to @code{FIXED_REGISTERS}.

@item STATIC_CHAIN_REGNUM
The register number used for passing a function's static chain
pointer.  This is needed for languages such as Pascal and Algol where
functions defined within other functions can access the local
variables of the outer functions; it is not currently used because C
does not provide this feature, but you must define the macro.

The static chain register need not be a fixed register.

@item STRUCT_VALUE_REGNUM
When a function's value's mode is @code{BLKmode}, the value is not
returned according to @code{FUNCTION_VALUE}.  Instead, the caller
passes the address of a block of memory in which the value should be
stored.

If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM}
should be the number of that register.

@item STRUCT_VALUE
If the structure value address is not passed in a register, define
@code{STRUCT_VALUE} as an expression returning an RTX for the place
where the address is passed.  If it returns a @code{mem} RTX, the
address is passed as an ``invisible'' first argument.

@item STRUCT_VALUE_INCOMING_REGNUM
On some architectures the place where the structure value address
is found by the called function is not the same place that the
caller put it.  This can be due to register windows, or it could
be because the function prologue moves it to a different place.

If the incoming location of the structure value address is in a
register, define this macro as the register number.

@item STRUCT_VALUE_INCOMING
If the incoming location is not a register, define
@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
called function should find the value.  If it should find the value on
the stack, define this to create a @code{mem} which refers to the
frame pointer.  If the value is a @code{mem}, the compiler assumes it
is for an invisible first argument, and leaves space for it when
finding the first real argument.

@item REG_ALLOC_ORDER
If defined, an initializer for a vector of integers, containing the
numbers of hard registers in the order in which the GNU CC should
prefer to use them (from most preferred to least).

If this macro is not defined, registers are used lowest numbered first
(all else being equal).

One use of this macro is on the 360, where the highest numbered
registers must always be saved and the save-multiple-registers
instruction supports only sequences of consecutive registers.  This
macro is defined to cause the highest numbered allocatable registers
to be used first.
@end table

@node Register Classes, Stack Layout, Registers, Machine Macros
@section Register Classes

On many machines, the numbered registers are not all equivalent.
For example, certain registers may not be allowed for indexed addressing;
certain registers may not be allowed in some instructions.  These machine
restrictions are described to the compiler using @dfn{register classes}.

You define a number of register classes, giving each one a name and saying
which of the registers belong to it.  Then you can specify register classes
that are allowed as operands to particular instruction patterns.

In general, each register will belong to several classes.  In fact, one
class must be named @code{ALL_REGS} and contain all the registers.  Another
class must be named @code{NO_REGS} and contain no registers.  Often the
union of two classes will be another class; however, this is not required.

One of the classes must be named @code{GENERAL_REGS}.  There is nothing
terribly special about the name, but the operand constraint letters
@samp{r} and @samp{g} specify this class.  If @code{GENERAL_REGS} is
the same as @code{ALL_REGS}, just define it as a macro which expands
to @code{ALL_REGS}.

The way classes other than @code{GENERAL_REGS} are specified in operand
constraints is through machine-dependent operand constraint letters.
You can define such letters to correspond to various classes, then use
them in operand constraints.

You should define a class for the union of two classes whenever some
instruction allows both classes.  For example, if an instruction allows
either a floating-point (coprocessor) register or a general register for a
certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
which includes both of them.  Otherwise you will get suboptimal code.

You must also specify certain redundant information about the register
classes: for each class, which classes contain it and which ones are
contained in it; for each pair of classes, the largest class contained
in their union.

When a value occupying several consecutive registers is expected in a
certain class, all the registers used must belong to that class.
Therefore, register classes cannot be used to enforce a requirement for
a register pair to start with an even-numbered register.  The way to
specify this requirement is with @code{HARD_REGNO_MODE_OK}.

Register classes used for input-operands of bitwise-and or shift
instructions have a special requirement: each such class must have, for
each fixed-point machine mode, a subclass whose registers can transfer that
mode to or from memory.  For example, on some machines, the operations for
single-byte values (@code{QImode}) are limited to certain registers.  When
this is so, each register class that is used in a bitwise-and or shift
instruction must have a subclass consisting of registers from which
single-byte values can be loaded or stored.  This is so that
@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.

@table @code
@item enum reg_class
An enumeral type that must be defined with all the register class names
as enumeral values.  @code{NO_REGS} must be first.  @code{ALL_REGS}
must be the last register class, followed by one more enumeral value,
@code{LIM_REG_CLASSES}, which is not a register class but rather
tells how many classes there are.

Each register class has a number, which is the value of casting
the class name to type @code{int}.  The number serves as an index
in many of the tables described below.

@item N_REG_CLASSES
The number of distinct register classes, defined as follows:

@example
#define N_REG_CLASSES (int) LIM_REG_CLASSES
@end example

@item REG_CLASS_NAMES
An initializer containing the names of the register classes as C string
constants.  These names are used in writing some of the debugging dumps.

@item REG_CLASS_CONTENTS
An initializer containing the contents of the register classes, as integers
which are bit masks.  The @var{n}th integer specifies the contents of class
@var{n}.  The way the integer @var{mask} is interpreted is that
register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.

When the machine has more than 32 registers, an integer does not suffice.
Then the integers are replaced by sub-initializers, braced groupings containing
several integers.  Each sub-initializer must be suitable as an initializer
for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.

@item REGNO_REG_CLASS (@var{regno})
A C expression whose value is a register class containing hard register
@var{regno}.  In general there is more that one such class; choose a class
which is @dfn{minimal}, meaning that no smaller class also contains the
register.

@item BASE_REG_CLASS
A macro whose definition is the name of the class to which a valid
base register must belong.  A base register is one used in an address
which is the register value plus a displacement.

@item INDEX_REG_CLASS
A macro whose definition is the name of the class to which a valid
index register must belong.  An index register is one used in an
address where its value is either multiplied by a scale factor or
added to another register (as well as added to a displacement).

@item REG_CLASS_FROM_LETTER (@var{char})
A C expression which defines the machine-dependent operand constraint
letters for register classes.  If @var{char} is such a letter, the
value should be the register class corresponding to it.  Otherwise,
the value should be @code{NO_REGS}.

@item REGNO_OK_FOR_BASE_P (@var{num})
A C expression which is nonzero if register number @var{num} is
suitable for use as a base register in operand addresses.  It may be
either a suitable hard register or a pseudo register that has been
allocated such a hard register.

@item REGNO_OK_FOR_INDEX_P (@var{num})
A C expression which is nonzero if register number @var{num} is
suitable for use as an index register in operand addresses.  It may be
either a suitable hard register or a pseudo register that has been
allocated such a hard register.

The difference between an index register and a base register is that
the index register may be scaled.  If an address involves the sum of
two registers, neither one of them scaled, then either one may be
labeled the ``base'' and the other the ``index''; but whichever
labeling is used must fit the machine's constraints of which registers
may serve in each capacity.  The compiler will try both labelings,
looking for one that is valid, and will reload one or both registers
only if neither labeling works.

@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
A C expression that places additional restrictions on the register class
to use when it is necessary to copy value @var{x} into a register in class
@var{class}.  The value is a register class; perhaps @var{class}, or perhaps
another, smaller class.  On many machines, the definition

@example
#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
@end example

@noindent
is safe.

Sometimes returning a more restrictive class makes better code.  For
example, on the 68000, when @var{x} is an integer constant that is in range
for a @samp{moveq} instruction, the value of this macro is always
@code{DATA_REGS} as long as @var{class} includes the data registers.
Requiring a data register guarantees that a @samp{moveq} will be used.

If @var{x} is a @code{const_double}, by returning @code{NO_REGS}
you can force @var{x} into a memory constant.  This is useful on
certain machines where immediate floating values cannot be loaded into
certain kinds of registers.

In a shift instruction or a bitwise-and instruction, the mode of @var{x},
the value being reloaded, may not be the same as the mode of the
instruction's operand.  (They will both be fixed-point modes, however.)  In
such a case, @var{class} may not be a safe value to return.  @var{class} is
certainly valid for the instruction, but it may not be valid for reloading
@var{x}.  This problem can occur on machines such as the 68000 and 80386
where some registers can handle full-word values but cannot handle
single-byte values.

On such machines, this macro must examine the mode of @var{x} and return a
subclass of @var{class} which can handle loads and stores of that mode.  On
the 68000, where address registers cannot handle @code{QImode}, if @var{x}
has @code{QImode} then you must return @code{DATA_REGS}.  If @var{class} is
@code{ADDR_REGS}, then there is no correct value to return; but the shift
and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case
never arises.

@item CLASS_MAX_NREGS (@var{class}, @var{mode})
A C expression for the maximum number of consecutive registers
of class @var{class} needed to hold a value of mode @var{mode}.

This is closely related to the macro @code{HARD_REGNO_NREGS}.
In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
for all @var{regno} values in the class @var{class}.

This macro helps control the handling of multiple-word values
in the reload pass.
@end table

Two other special macros describe which constants fit which constraint
letters.

@table @code
@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
A C expression that defines the machine-dependent operand constraint letters
that specify particular ranges of integer values.  If @var{c} is one
of those letters, the expression should check that @var{value}, an integer,
is in the appropriate range and return 1 if so, 0 otherwise.  If @var{c} is
not one of those letters, the value should be 0 regardless of @var{value}.

@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
A C expression that defines the machine-dependent operand constraint
letters that specify particular ranges of floating values.  If @var{c} is
one of those letters, the expression should check that @var{value}, an RTX
of code @code{const_double}, is in the appropriate range and return 1 if
so, 0 otherwise.  If @var{c} is not one of those letters, the value should
be 0 regardless of @var{value}.
@end table

@node Stack Layout, Library Calls, Register Classes, Machine Macros
@section Describing Stack Layout

@table @code
@item STACK_GROWS_DOWNWARD
Define this macro if pushing a word onto the stack moves the stack
pointer to a smaller address.

When we say, ``define this macro if @dots{},'' it means that the
compiler checks this macro only with @code{#ifdef} so the precise
definition used does not matter.

@item FRAME_GROWS_DOWNWARD
Define this macro if the addresses of local variable slots are at negative
offsets from the frame pointer.

@item STARTING_FRAME_OFFSET
Offset from the frame pointer to the first local variable slot to be allocated.

If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
Otherwise, it is found by adding the length of the first slot to
the value @code{STARTING_FRAME_OFFSET}.

@item PUSH_ROUNDING (@var{npushed})
A C expression that is the number of bytes actually pushed onto the
stack when an instruction attempts to push @var{npushed} bytes.

If the target machine does not have a push instruction, do not define
this macro.  That directs GNU CC to use an alternate strategy: to
allocate the entire argument block and then store the arguments into
it.

On some machines, the definition

@example
#define PUSH_ROUNDING(BYTES) (BYTES)
@end example

@noindent
will suffice.  But on other machines, instructions that appear
to push one byte actually push two bytes in an attempt to maintain
alignment.  Then the definition should be

@example
#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
@end example

@item FIRST_PARM_OFFSET (@var{fundecl})
Offset from the argument pointer register to the first argument's
address.  On some machines it may depend on the data type of the
function.  (In the next version of GNU CC, the argument will be
changed to the function data type rather than its declaration.)

@item FIRST_PARM_CALLER_OFFSET (@var{fundecl})
Define this macro on machines where register parameters have shadow
locations on the stack, at addresses below the nominal parameter.
This matters because certain arguments cannot be passed on the stack.
On these machines, such arguments must be stored into the shadow
locations.

This macro should expand into a C expression whose value is the offset
of the first parameter's shadow location from the nominal stack
pointer value.  (That value is itself computed by adding the value of
@code{STACK_POINTER_OFFSET} to the stack pointer register.)

@item REG_PARM_STACK_SPACE
Define this macro if functions should assume that stack space has been
allocated for arguments even when their values are passed in
registers.

The actual allocation of such space would be done either by
the call instruction or by the function prologue, or by
defining @code{FIRST_PARM_CALLER_OFFSET}.

@item STACK_ARGS_ADJUST (@var{size})
Define this macro if the machine requires padding on the stack for
certain function calls.  This is padding on a per-function-call basis,
not padding for individual arguments.

The argument @var{size} will be a C variable of type @code{struct
arg_data} which contains two fields, an integer named @code{constant}
and an RTX named @code{var}.  These together represent a size measured
in bytes which is the sum of the integer and the RTX.  Most of the
time @code{var} is 0, which means that the size is simply the integer.

The definition should be a C statement or compound statement
which alters the variable supplied in whatever way you wish.

Note that the value you leave in the variable @code{size} will
ultimately be rounded up to a multiple of @code{STACK_BOUNDARY} bits.

This macro is not fully implemented for machines which have push
instructions (i.e., on which @code{PUSH_ROUNDING} is defined).

@item RETURN_POPS_ARGS (@var{funtype})
A C expression that should be 1 if a function pops its own arguments
on returning, or 0 if the function pops no arguments and the caller
must therefore pop them all after the function returns.

@var{funtype} is a C variable whose value is a tree node that
describes the function in question.  Normally it is a node of type
@code{FUNCTION_TYPE} that describes the data type of the function.
From this it is possible to obtain the data types of the value and
arguments (if known).

When a call to a library function is being considered, @var{funtype}
will contain an identifier node for the library function.  Thus, if
you need to distinguish among various library functions, you can do so
by their names.  Note that ``library function'' in this context means
a function used to perform arithmetic, whose name is known specially
in the compiler and was not mentioned in the C code being compiled.

On the Vax, all functions always pop their arguments, so the
definition of this macro is 1.  On the 68000, using the standard
calling convention, no functions pop their arguments, so the value of
the macro is always 0 in this case.  But an alternative calling
convention is available in which functions that take a fixed number of
arguments pop them but other functions (such as @code{printf}) pop
nothing (the caller pops all).  When this convention is in use,
@var{funtype} is examined to determine whether a function takes a
fixed number of arguments.

When this macro returns nonzero, the macro @code{FRAME_POINTER_REQUIRED}
must also return nonzero for proper operation.

@item FUNCTION_VALUE (@var{valtype}, @var{func})
A C expression to create an RTX representing the place where a
function returns a value of data type @var{valtype}.  @var{valtype} is
a tree node representing a data type.  Write @code{TYPE_MODE
(@var{valtype})} to get the machine mode used to represent that type.
On many machines, only the mode is relevant.  (Actually, on most
machines, scalar values are returned in the same place regardless of
mode).@refill

If the precise function being called is known, @var{func} is a tree
node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
pointer.  This makes it possible to use a different value-returning
convention for specific functions when all their calls are
known.@refill

@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
Define this macro if the target machine has ``register windows''
so that the register in which a function returns its value is not
the same as the one in which the caller sees the value.

For such machines, @code{FUNCTION_VALUE} computes the register in
which the caller will see the value, and
@code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
to tell the function where to put the value.@refill

If @code{FUNCTION_OUTGOING_VALUE} is not defined,
@code{FUNCTION_VALUE} serves both purposes.@refill

@item RETURN_IN_MEMORY (@var{type})
A C expression which can inhibit the returning of certain function
values in registers, based on the type of value.  A nonzero value says
to return the function value in memory, just as large structures are
always returned.  Here @var{type} will be a C expression of type
@code{tree}, representing the data type of the value.

Note that values of mode @code{BLKmode} are returned in memory
regardless of this macro.  Also, the option @samp{-fpcc-struct-return}
takes effect regardless of this macro.  On most systems, it is
possible to leave the macro undefined; this causes a default
definition to be used, whose value is the constant 0.

@item LIBCALL_VALUE (@var{mode})
A C expression to create an RTX representing the place where a library
function returns a value of mode @var{mode}.  If the precise function
being called is known, @var{func} is a tree node
(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
pointer.  This makes it possible to use a different value-returning
convention for specific functions when all their calls are
known.@refill

Note that ``library function'' in this context means a compiler
support routine, used to perform arithmetic, whose name is known
specially by the compiler and was not mentioned in the C code being
compiled.

@item FUNCTION_VALUE_REGNO_P (@var{regno})
A C expression that is nonzero if @var{regno} is the number of a hard
register in which the values of called function may come back.

A register whose use for returning values is limited to serving as the
second of a pair (for a value of type @code{double}, say) need not be
recognized by this macro.  So for most machines, this definition
suffices:

@example
#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
@end example

If the machine has register windows, so that the caller and the called
function use different registers for the return value, this macro
should recognize only the caller's register numbers.

@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
A C expression that controls whether a function argument is passed
in a register, and which register.

The arguments are @var{cum}, which summarizes all the previous
arguments; @var{mode}, the machine mode of the argument; @var{type},
the data type of the argument as a tree node or 0 if that is not known
(which happens for C support library functions); and @var{named},
which is 1 for an ordinary argument and 0 for nameless arguments that
correspond to @samp{@dots{}} in the called function's prototype.

The value of the expression should either be a @code{reg} RTX for the
hard register in which to pass the argument, or zero to pass the
argument on the stack.

For the Vax and 68000, where normally all arguments are pushed, zero
suffices as a definition.

The usual way to make the ANSI library @file{stdarg.h} work on a machine
where some arguments are usually passed in registers, is to cause
nameless arguments to be passed on the stack instead.  This is done
by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.

@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
Define this macro if the target machine has ``register windows'', so
that the register in which a function sees an arguments is not
necessarily the same as the one in which the caller passed the
argument.

For such machines, @code{FUNCTION_ARG} computes the register in which
the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
be defined in a similar fashion to tell the function being called
where the arguments will arrive.

If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
serves both purposes.@refill

@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
A C expression for the number of words, at the beginning of an
argument, must be put in registers.  The value must be zero for
arguments that are passed entirely in registers or that are entirely
pushed on the stack.

On some machines, certain arguments must be passed partially in
registers and partially in memory.  On these machines, typically the
first @var{n} words of arguments are passed in registers, and the rest
on the stack.  If a multi-word argument (a @code{double} or a
structure) crosses that boundary, its first few words must be passed
in registers and the rest must be pushed.  This macro tells the
compiler when this occurs, and how many of the words should go in
registers.

@code{FUNCTION_ARG} for these arguments should return the first
register to be used by the caller for this argument; likewise
@code{FUNCTION_INCOMING_ARG}, for the called function.

@item CUMULATIVE_ARGS
A C type for declaring a variable that is used as the first argument
of @code{FUNCTION_ARG} and other related values.  For some target
machines, the type @code{int} suffices and can hold the number of
bytes of argument so far.

@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype})
A C statement (sans semicolon) for initializing the variable @var{cum}
for the state at the beginning of the argument list.  The variable has
type @code{CUMULATIVE_ARGS}.  The value of @var{fntype} is the tree node
for the data type of the function which will receive the args, or 0
if the args are to a compiler support library function.

@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
A C statement (sans semicolon) to update the summarizer variable
@var{cum} to advance past an argument in the argument list.  The
values @var{mode}, @var{type} and @var{named} describe that argument.
Once this is done, the variable @var{cum} is suitable for analyzing
the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill

@item FUNCTION_ARG_REGNO_P (@var{regno})
A C expression that is nonzero if @var{regno} is the number of a hard
register in which function arguments are sometimes passed.  This does
@emph{not} include implicit arguments such as the static chain and
the structure-value address.  On many machines, no registers can be
used for this purpose since all function arguments are pushed on the
stack.

@item FUNCTION_ARG_PADDING (@var{mode}, @var{size})
If defined, a C expression which determines whether, and in which direction,
to pad out an argument with extra space.  The value should be of type
@code{enum direction}: either @code{upward} to pad above the argument,
@code{downward} to pad below, or @code{none} to inhibit padding.

The argument @var{size} is an RTX which describes the size of the
argument, in bytes.  It should be used only if @var{mode} is
@code{BLKmode}.  Otherwise, @var{size} is 0.

This macro does not control the @emph{amount} of padding; that is
always just enough to reach the next multiple of @code{PARM_BOUNDARY}.

This macro has a default definition which is right for most systems.
For little-endian machines, the default is to pad upward.  For
big-endian machines, the default is to pad downward for an argument of
constant size shorter than an @code{int}, and upward otherwise.

@item FUNCTION_PROLOGUE (@var{file}, @var{size})
A C compound statement that outputs the assembler code for entry to a
function.  The prologue is responsible for setting up the stack frame,
initializing the frame pointer register, saving registers that must be
saved, and allocating @var{size} additional bytes of storage for the
local variables.  @var{size} is an integer.  @var{file} is a stdio
stream to which the assembler code should be output.

The label for the beginning of the function need not be output by this
macro.  That has already been done when the macro is run.

To determine which registers to save, the macro can refer to the array
@code{regs_ever_live}: element @var{r} is nonzero if hard register
@var{r} is used anywhere within the function.  This implies the
function prologue should save register @var{r}, but not if it is one
of the call-used registers.

On machines where functions may or may not have frame-pointers, the
function entry code must vary accordingly; it must set up the frame
pointer if one is wanted, and not otherwise.  To determine whether a
frame pointer is in wanted, the macro can refer to the variable
@code{frame_pointer_needed}.  The variable's value will be 1 at run
time in a function that needs a frame pointer.

On machines where an argument may be passed partly in registers and
partly in memory, this macro must examine the variable
@code{current_function_pretend_args_size}, and allocate that many bytes
of uninitialized space on the stack just underneath the first argument
arriving on the stack.  (This may not be at the very end of the stack,
if the calling sequence has pushed anything else since pushing the stack
arguments.  But usually, on such machines, nothing else has been pushed
yet, because the function prologue itself does all the pushing.)

@item FUNCTION_PROFILER (@var{file}, @var{labelno})
A C statement or compound statement to output to @var{file} some
assembler code to call the profiling subroutine @code{mcount}.
Before calling, the assembler code must load the address of a
counter variable into a register where @code{mcount} expects to
find the address.  The name of this variable is @samp{LP} followed
by the number @var{labelno}, so you would generate the name using
@samp{LP%d} in a @code{fprintf}.

The details of how the address should be passed to @code{mcount} are
determined by your operating system environment, not by GNU CC.  To
figure them out, compile a small program for profiling using the
system's installed C compiler and look at the assembler code that
results.

@item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno})
A C statement or compound statement to output to @var{file} some
assembler code to initialize basic-block profiling for the current
object module.  This code should call the subroutine
@code{__bb_init_func} once per object module, passing it as its sole
argument the address of a block allocated in the object module.

The name of the block is a local symbol made with this statement:

@example
ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
@end example

Of course, since you are writing the definition of
@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
can take a short cut in the definition of this macro and use the name
that you know will result.

The first word of this block is a flag which will be nonzero if the
object module has already been initialized.  So test this word first,
and do not call @code{__bb_init_func} if the flag is nonzero.

@item BLOCK_PROFILER (@var{file}, @var{blockno})
A C statement or compound statement to increment the count associated
with the basic block number @var{blockno}.  Basic blocks are numbered
separately from zero within each compilation.  The count associated
with block number @var{blockno} is at index @var{blockno} in a vector
of words; the name of this array is a local symbol made with this
statement:

@example
ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2);
@end example

Of course, since you are writing the definition of
@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
can take a short cut in the definition of this macro and use the name
that you know will result.

@item EXIT_IGNORE_STACK
Define this macro as a C expression that is nonzero if the return
instruction or the function epilogue ignores the value of the stack
pointer; in other words, if it is safe to delete an instruction to
adjust the stack pointer before a return from the function.

Note that this macro's value is relevant only for functions for which
frame pointers are maintained.  It is never safe to delete a final
stack adjustment in a function that has no frame pointer, and the
compiler knows this regardless of @code{EXIT_IGNORE_STACK}.

@item FUNCTION_EPILOGUE (@var{file}, @var{size})
A C compound statement that outputs the assembler code for exit from a
function.  The epilogue is responsible for restoring the saved
registers and stack pointer to their values when the function was
called, and returning control to the caller.  This macro takes the
same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
registers to restore are determined from @code{regs_ever_live} and
@code{CALL_USED_REGISTERS} in the same way.

On some machines, there is a single instruction that does all the work
of returning from the function.  On these machines, give that
instruction the name @samp{return} and do not define the macro
@code{FUNCTION_EPILOGUE} at all.

Do not define a pattern named @samp{return} if you want the
@code{FUNCTION_EPILOGUE} to be used.  If you want the target switches
to control whether return instructions or epilogues are used, define a
@samp{return} pattern with a validity condition that tests the target
switches appropriately.  If the @samp{return} pattern's validity
condition is false, epilogues will be used.

On machines where functions may or may not have frame-pointers, the
function exit code must vary accordingly.  Sometimes the code for
these two cases is completely different.  To determine whether a frame
pointer is in wanted, the macro can refer to the variable
@code{frame_pointer_needed}.  The variable's value will be 1 at run
time in a function that needs a frame pointer.

On some machines, some functions pop their arguments on exit while
others leave that for the caller to do.  For example, the 68020 when
given @samp{-mrtd} pops arguments in functions that take a fixed
number of arguments.

Your definition of the macro @code{RETURN_POPS_ARGS} decides which
functions pop their own arguments.  @code{FUNCTION_EPILOGUE} needs to
know what was decided.  The variable @code{current_function_pops_args}
is nonzero if the function should pop its own arguments.  If so, use
the variable @code{current_function_args_size} as the number of bytes
to pop.

@item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
A C compound statement to alter a memory address that uses the frame
pointer register so that it uses the stack pointer register instead.
This must be done in the instructions that load parameter values into
registers, when the reload pass determines that a frame pointer is not
necessary for the function.  @var{addr} will be a C variable name, and
the updated address should be stored in that variable.  @var{depth}
will be the current depth of stack temporaries (number of bytes of
arguments currently pushed).  The change in offset between a
frame-pointer-relative address and a stack-pointer-relative address
must include @var{depth}.

Even if your machine description specifies there will always be a
frame pointer in the frame pointer register, you must still define
@code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
executed at run time, so it may be empty.

@item LONGJMP_RESTORE_FROM_STACK
Define this macro if the @code{longjmp} function restores registers
from the stack frames, rather than from those saved specifically by
@code{setjmp}.  Certain quantities must not be kept in registers
across a call to @code{setjmp} on such machines.
@end table

@node Library Calls, Addressing Modes, Stack Layout, Machine Macros
@section Implicit Use of Library Routines

@table @code
@item MULSI3_LIBCALL
A C string constant giving the name of the function to call for
multiplication of one signed full-word by another.  If you do not
define this macro, the default name is used, which is @code{__mulsi3},
a function defined in @file{gnulib}.

@item UMULSI3_LIBCALL
A C string constant giving the name of the function to call for
multiplication of one unsigned full-word by another.  If you do not
define this macro, the default name is used, which is
@code{__umulsi3}, a function defined in @file{gnulib}.

@item DIVSI3_LIBCALL
A C string constant giving the name of the function to call for
division of one signed full-word by another.  If you do not define
this macro, the default name is used, which is @code{__divsi3}, a
function defined in @file{gnulib}.

@item UDIVSI3_LIBCALL
A C string constant giving the name of the function to call for
division of one unsigned full-word by another.  If you do not define
this macro, the default name is used, which is @code{__udivsi3}, a
function defined in @file{gnulib}.

@item MODSI3_LIBCALL
A C string constant giving the name of the function to call for the
remainder in division of one signed full-word by another.  If you do
not define this macro, the default name is used, which is
@code{__modsi3}, a function defined in @file{gnulib}.

@item UMODSI3_LIBCALL
A C string constant giving the name of the function to call for the
remainder in division of one unsigned full-word by another.  If you do
not define this macro, the default name is used, which is
@code{__umodsi3}, a function defined in @file{gnulib}.

@item TARGET_MEM_FUNCTIONS
Define this macro if GNU CC should generate calls to the System V
(and ANSI C) library functions @code{memcpy} and @code{memset}
rather than the BSD functions @code{bcopy} and @code{bzero}.

@item GNULIB_NEEDS_DOUBLE
Define this macro if only @code{float} arguments cannot be passed to
library routines (so they must be converted to @code{double}).  This
macro affects both how library calls are generated and how the library
routines in @file{gnulib.c} accept their arguments.  It is useful on
machines where floating and fixed point arguments are passed
differently, such as the i860.
@end table

@node Addressing Modes, Delayed Branch, Library Calls, Machine Macros
@section Addressing Modes

@table @code
@item HAVE_POST_INCREMENT
Define this macro if the machine supports post-increment addressing.

@item HAVE_PRE_INCREMENT
@itemx HAVE_POST_DECREMENT
@itemx HAVE_PRE_DECREMENT
Similar for other kinds of addressing.

@item CONSTANT_ADDRESS_P (@var{x})
A C expression that is 1 if the RTX @var{x} is a constant whose value
is an integer.  This includes integers whose values are not explicitly
known, such as @code{symbol_ref} and @code{label_ref} expressions and
@code{const} arithmetic expressions.

On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
but a few machines are more restrictive in which constant addresses
are supported.

@item MAX_REGS_PER_ADDRESS
A number, the maximum number of registers that can appear in a valid
memory address.  Note that it is up to you to specify a value equal to
the maximum number that @code{go_if_legitimate_address} would ever
accept.

@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
A C compound statement with a conditional @code{goto @var{label};}
executed if @var{x} (an RTX) is a legitimate memory address on the
target machine for a memory operand of mode @var{mode}.

It usually pays to define several simpler macros to serve as
subroutines for this one.  Otherwise it may be too complicated to
understand.

This macro must exist in two variants: a strict variant and a
non-strict one.  The strict variant is used in the reload pass.  It
must be defined so that any pseudo-register that has not been
allocated a hard register is considered a memory reference.  In
contexts where some kind of register is required, a pseudo-register
with no hard register must be rejected.

The non-strict variant is used in other passes.  It must be defined to
accept all pseudo-registers in every context where some kind of
register is required.

Compiler source files that want to use the strict variant of this
macro define the macro @code{REG_OK_STRICT}.  You should use an
@code{#ifdef REG_OK_STRICT} conditional to define the strict variant
in that case and the non-strict variant otherwise.

Typically among the subroutines used to define
@code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
acceptable registers for various purposes (one for base registers, one
for index registers, and so on).  Then only these subroutine macros
need have two variants; the higher levels of macros may be the same
whether strict or not.@refill

Normally, constant addresses which are the sum of a @code{symbol_ref}
and an integer are stored inside a @code{const} RTX to mark them as
constant.  Therefore, there is no need to recognize such sums as
legitimate addresses.

Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
sums that are not marked with  @code{const}.  It assumes that a naked
@code{plus} indicates indexing.  If so, then you @emph{must} reject such
naked constant sums as illegitimate addresses, so that none of them will
be given to @code{PRINT_OPERAND_ADDRESS}.@refill

@item REG_OK_FOR_BASE_P (@var{x})
A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
RTX) is valid for use as a base register.  For hard registers, it
should always accept those which the hardware permits and reject the
others.  Whether the macro accepts or rejects pseudo registers must be
controlled by @code{REG_OK_STRICT} as described above.  This usually
requires two variant definitions, of which @code{REG_OK_STRICT}
controls the one actually used.

@item REG_OK_FOR_INDEX_P (@var{x})
A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
RTX) is valid for use as an index register.

The difference between an index register and a base register is that
the index register may be scaled.  If an address involves the sum of
two registers, neither one of them scaled, then either one may be
labeled the ``base'' and the other the ``index''; but whichever
labeling is used must fit the machine's constraints of which registers
may serve in each capacity.  The compiler will try both labelings,
looking for one that is valid, and will reload one or both registers
only if neither labeling works.

@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
A C compound statement that attempts to replace @var{x} with a valid
memory address for an operand of mode @var{mode}.  @var{win} will be a
C statement label elsewhere in the code; the macro definition may use

@example
GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
@end example

@noindent
to avoid further processing if the address has become legitimate.

@var{x} will always be the result of a call to @code{break_out_memory_refs},
and @var{oldx} will be the operand that was given to that function to produce
@var{x}.

The code generated by this macro should not alter the substructure of
@var{x}.  If it transforms @var{x} into a more legitimate form, it
should assign @var{x} (which will always be a C variable) a new value.

It is not necessary for this macro to come up with a legitimate
address.  The compiler has standard ways of doing so in all cases.  In
fact, it is safe for this macro to do nothing.  But often a
machine-dependent strategy can generate better code.

@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
A C statement or compound statement with a conditional @code{goto
@var{label};} executed if memory address @var{x} (an RTX) can have
different meanings depending on the machine mode of the memory
reference it is used for.

Autoincrement and autodecrement addresses typically have mode-dependent
effects because the amount of the increment or decrement is the size
of the operand being addressed.  Some machines have other mode-dependent
addresses.  Many RISC machines have no mode-dependent addresses.

You may assume that @var{addr} is a valid address for the machine.

@item LEGITIMATE_CONSTANT_P (@var{x})
A C expression that is nonzero if @var{x} is a legitimate constant for
an immediate operand on the target machine.  You can assume that
either @var{x} is a @code{const_double} or it satisfies
@code{CONSTANT_P}, so you need not check these things.  In fact,
@samp{1} is a suitable definition for this macro on machines where any
@code{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
@end table

@node Delayed Branch, Condition Code, Addressing Modes, Machine Macros
@section Parameters for Delayed Branch Optimization

@table @code
@item HAVE_DELAYED_BRANCH
Define this macro if the target machine has delayed branches, that is,
a branch does not take effect immediately, and the actual branch
instruction may be followed by one or more instructions that will be
issued before the PC is actually changed.

If defined, this allows a special scheduling pass to be run after the
second jump optimization to attempt to reorder instructions to exploit
this.  Defining this macro also requires the definition of certain
other macros described below.

@item DBR_SLOTS_AFTER (@var{insn})
This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
Its definition should be a C expression returning the number of
available delay slots following the instruction(s) output by the
pattern for @var{insn}.  The definition of ``slot'' is
machine-dependent, and may denote instructions, bytes, or whatever.

@item DBR_INSN_SLOTS (@var{insn})
This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
It should be a C expression returning the number of slots (typically
the number of machine instructions) consumed by @var{insn}.

You may assume that @var{insn} is truly an insn, not a note, label,
barrier, dispatch table, @code{use}, or @code{clobber}.

@item DBR_INSN_ELIGIBLE_P (@var{insn}, @var{dinsn})
A C expression whose value is non-zero if it is legitimate to put
@var{insn} in the delay slot following @var{dinsn}.

You do not need to take account of data flow considerations in the
definition of this macro, because the delayed branch optimizer always
does that.  This macro is needed only when certain insns may not be
placed in certain delay slots for reasons not evident from the RTL
expressions themselves.  If there are no such problems, you don't need
to define this macro.

You may assume that @var{insn} is truly an insn, not a note, label,
barrier, dispatch table, @code{use}, or @code{clobber}.  You may
assume that @var{dinsn} is a jump insn with a delay slot.

@item DBR_OUTPUT_SEQEND(@var{file})
A C statement, to be executed after all slot-filler instructions have
been output.  If necessary, call @code{dbr_sequence_length} to
determine the number of slots filled in a sequence (zero if not
currently outputting a sequence), to decide how many no-ops to output,
or whatever.

Don't define this macro if it has nothing to do, but it is helpful in
reading assembly output if the extent of the delay sequence is made
explicit (e.g. with white space).

Note that output routines for instructions with delay slots must be
prepared to deal with not being output as part of a sequence (i.e.
when the scheduling pass is not run, or when no slot fillers could be
found.)  The variable @code{final_sequence} is null when not
processing a sequence, otherwise it contains the @code{sequence} rtx
being output.
@end table

@node Condition Code, Cross-compilation, Delayed Branch, Machine Macros
@section Condition Code Information

The file @file{conditions.h} defines a variable @code{cc_status} to
describe how the condition code was computed (in case the interpretation of
the condition code depends on the instruction that it was set by).  This
variable contains the RTL expressions on which the condition code is
currently based, and several standard flags.

Sometimes additional machine-specific flags must be defined in the machine
description header file.  It can also add additional machine-specific
information by defining @code{CC_STATUS_MDEP}.

@table @code
@item CC_STATUS_MDEP
C code for a data type which is used for declaring the @code{mdep}
component of @code{cc_status}.  It defaults to @code{int}.

@item CC_STATUS_MDEP_INIT
A C expression to initialize the @code{mdep} field to ``empty''.
The default definition does nothing, since most machines don't use
the field anyway.  If you want to use the field, you should probably
define this macro to initialize it.

@item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
A C compound statement to set the components of @code{cc_status}
appropriately for an insn @var{insn} whose body is @var{exp}.  It is
this macro's responsibility to recognize insns that set the condition
code as a byproduct of other activity as well as those that explicitly
set @code{(cc0)}.

If there are insn that do not set the condition code but do alter
other machine registers, this macro must check to see whether they
invalidate the expressions that the condition code is recorded as
reflecting.  For example, on the 68000, insns that store in address
registers do not set the condition code, which means that usually
@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
insns.  But suppose that the previous insn set the condition code
based on location @samp{a4@@(102)} and the current insn stores a new
value in @samp{a4}.  Although the condition code is not changed by
this, it will no longer be true that it reflects the contents of
@samp{a4@@(102)}.  Therefore, @code{NOTICE_UPDATE_CC} must alter
@code{cc_status} in this case to say that nothing is known about the
condition code value.

The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
with the results of peephole optimization: insns whose patterns are
@code{parallel} RTXs containing various @code{reg}, @code{mem} or
constants which are just the operands.  The RTL structure of these
insns is not sufficient to indicate what the insns actually do.  What
@code{NOTICE_UPDATE_CC} should do when it sees one is just to run
@code{CC_STATUS_INIT}.
@end table

@node Cross-compilation, Misc, Condition Code, Machine Macros
@section Cross Compilation and Floating-Point Format

While all modern machines use 2's complement representation for integers,
there are a variety of representations for floating point numbers.  This
means that in a cross-compiler the representation of floating point numbers
in the compiled program may be different from that used in the machine
doing the compilation.

Because different representation systems may offer different amounts of
range and precision, the cross compiler cannot safely use the host
machine's floating point arithmetic.  Therefore, floating point constants
must be represented in the target machine's format.  This means that the
cross compiler cannot use @code{atof} to parse a floating point constant;
it must have its own special routine to use instead.  Also, constant
folding must emulate the target machine's arithmetic (or must not be done
at all).

The macros in the following table should be defined only if you are cross
compiling between different floating point formats.

Otherwise, don't define them. Then default definitions will be set up which
use @code{double} as the data type, @code{==} to test for equality, etc.

You don't need to worry about how many times you use an operand of any
of these macros.  The compiler never uses operands which have side effects.

@table @code
@item REAL_VALUE_TYPE
A macro for the C data type to be used to hold a floating point value
in the target machine's format.  Typically this would be a
@code{struct} containing an array of @code{int}.

@item REAL_VALUES_EQUAL (@var{x}, @var{y})
A macro for a C expression which compares for equality the two values,
@var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}.

@item REAL_VALUES_LESS (@var{x}, @var{y})
A macro for a C expression which tests whether @var{x} is less than
@var{y}, both values being of type @code{REAL_VALUE_TYPE} and
interpreted as floating point numbers in the target machine's
representation.

@item REAL_VALUE_LDEXP (@var{x}, @var{scale})
A macro for a C expression which performs the standard library
function @code{ldexp}, but using the target machine's floating point
representation.  Both @var{x} and the value of the expression have
type @code{REAL_VALUE_TYPE}.  The second argument, @var{scale}, is an
integer.

@item REAL_VALUE_ATOF (@var{string})
A macro for a C expression which converts @var{string}, an expression
of type @code{char *}, into a floating point number in the target
machine's representation.  The value has type @code{REAL_VALUE_TYPE}.
@end table

Define the following additional macros if you want to make floating
point constant folding work while cross compiling.  If you don't
define them, cross compilation is still possible, but constant folding
will not happen for floating point values.

@table @code
@item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y})
A macro for a C statement which calculates an arithmetic operation of
the two floating point values @var{x} and @var{y}, both of type
@code{REAL_VALUE_TYPE} in the target machine's representation, to
produce a result of the same type and representation which is stored
in @var{output} (which will be a variable).

The operation to be performed is specified by @var{code}, a tree code
which will always be one of the following: @code{PLUS_EXPR},
@code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR},
@code{MAX_EXPR}, @code{MIN_EXPR}.@refill

The expansion of this macro is responsible for checking for overflow.
If overflow happens, the macro expansion should execute the statement
@code{return 0;}, which indicates the inability to perform the
arithmetic operation requested.

@item REAL_VALUE_NEGATE (@var{x})
A macro for a C expression which returns the negative of the floating
point value @var{x}.  Both @var{x} and the value of the expression
have type @code{REAL_VALUE_TYPE} and are in the target machine's
floating point representation.

There is no way for this macro to report overflow, since overflow
can't happen in the negation operation.

@item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x})
A macro for a C expression which converts a floating point value
@var{x} into a double-precision integer which is then stored into
@var{low} and @var{high}, two variables of type @var{int}.

@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high})
A macro for a C expression which converts a double-precision integer
found in @var{low} and @var{high}, two variables of type @var{int},
into a floating point value which is then stored into @var{x}.
@end table

@node Misc, Assembler Format, Cross-compilation, Machine Macros
@section Miscellaneous Parameters

@table @code
@item CASE_VECTOR_MODE
An alias for a machine mode name.  This is the machine mode that
elements of a jump-table should have.

@item CASE_VECTOR_PC_RELATIVE
Define this macro if jump-tables should contain relative addresses.

@item CASE_DROPS_THROUGH
Define this if control falls through a @code{case} insn when the index
value is out of range.  This means the specified default-label is
actually ignored by the @code{case} insn proper.

@item IMPLICIT_FIX_EXPR
An alias for a tree code that should be used by default for conversion
of floating point values to fixed point.  Normally,
@code{FIX_ROUND_EXPR} is used.@refill

@item FIXUNS_TRUNC_LIKE_FIX_TRUNC
Define this macro if the same instructions that convert a floating
point number to a signed fixed point number also convert validly to an
unsigned one.

@item EASY_DIV_EXPR
An alias for a tree code that is the easiest kind of division to
compile code for in the general case.  It may be
@code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
@code{ROUND_DIV_EXPR}.  These four division operators differ in how
they round the result to an integer.  @code{EASY_DIV_EXPR} is used
when it is permissible to use any of those kinds of division and the
choice should be made on the basis of efficiency.@refill

@item DEFAULT_SIGNED_CHAR
An expression whose value is 1 or 0, according to whether the type
@code{char} should be signed or unsigned by default.  The user can
always override this default with the options @samp{-fsigned-char}
and @samp{-funsigned-char}.

@item SCCS_DIRECTIVE
Define this if the preprocessor should ignore @code{#sccs} directives
and print no error message.

@item HAVE_VPRINTF
Define this if the library function @code{vprintf} is available on your
system.

@item MOVE_MAX
The maximum number of bytes that a single instruction can move quickly
from memory to memory.

@item INT_TYPE_SIZE
A C expression for the size in bits of the type @code{int} on the
target machine.  If you don't define this, the default is one word.

@item SHORT_TYPE_SIZE
A C expression for the size in bits of the type @code{short} on the
target machine.  If you don't define this, the default is half a word.
(If this would be less than one storage unit, it is rounded up to one
unit.)

@item LONG_TYPE_SIZE
A C expression for the size in bits of the type @code{long} on the
target machine.  If you don't define this, the default is one word.

@item LONG_LONG_TYPE_SIZE
A C expression for the size in bits of the type @code{long long} on the
target machine.  If you don't define this, the default is two
words.

@item CHAR_TYPE_SIZE
A C expression for the size in bits of the type @code{char} on the
target machine.  If you don't define this, the default is one quarter
of a word.  (If this would be less than one storage unit, it is rounded up
to one unit.)

@item FLOAT_TYPE_SIZE
A C expression for the size in bits of the type @code{float} on the
target machine.  If you don't define this, the default is one word.

@item DOUBLE_TYPE_SIZE
A C expression for the size in bits of the type @code{double} on the
target machine.  If you don't define this, the default is two
words.

@item LONG_DOUBLE_TYPE_SIZE
A C expression for the size in bits of the type @code{long double} on
the target machine.  If you don't define this, the default is two
words.

@item SLOW_BYTE_ACCESS
Define this macro as a C expression which is nonzero if accessing less
than a word of memory (i.e. a @code{char} or a @code{short}) is slow
(requires more than one instruction).

@item SLOW_ZERO_EXTEND
Define this macro if zero-extension (of a @code{char} or @code{short}
to an @code{int}) can be done faster if the destination is a register
that is known to be zero.

If you define this macro, you must have instruction patterns that
recognize RTL structures like this:

@example
(set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
@end example

@noindent
and likewise for @code{HImode}.

@item SHIFT_COUNT_TRUNCATED
Define this macro if shift instructions ignore all but the lowest few
bits of the shift count.  It implies that a sign-extend or zero-extend
instruction for the shift count can be omitted.

@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
A C expression which is nonzero if on this machine it is safe to
``convert'' an integer of @var{inprec} bits to one of @var{outprec}
bits (where @var{outprec} is smaller than @var{inprec}) by merely
operating on it as if it had only @var{outprec} bits.

On many machines, this expression can be 1.

@item NO_FUNCTION_CSE
Define this macro if it is as good or better to call a constant
function address than to call an address kept in a register.

@item PROMOTE_PROTOTYPES
Define this macro if an argument declared as @code{char} or
@code{short} in a prototype should actually be passed as an
@code{int}.  In addition to avoiding errors in certain cases of
mismatch, it also makes for better code on certain machines.

@item STORE_FLAG_VALUE
A C expression for the value stored by a store-flag instruction
(@code{s@var{cond}}) when the condition is true.  This is usually 1 or
-1; it is required to be an odd number or a negative number.

Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
instructions.

@item Pmode
An alias for the machine mode for pointers.  Normally the definition
can be

@example
#define Pmode SImode
@end example

@item FUNCTION_MODE
An alias for the machine mode used for memory references to functions
being called, in @code{call} RTL expressions.  On most machines this
should be @code{QImode}.

@item INSN_MACHINE_INFO
This macro should expand into a C structure type to use for the
machine-dependent info field specified with the optional last argument
in @code{define_insn} and @code{define_peephole} patterns.  For example,
it might expand into @code{struct machine_info}; then it would be up
to you to define this structure in the @file{tm.h} file.

You do not need to define this macro if you do not write the optional
last argument in any of the patterns in the machine description.

@item DEFAULT_MACHINE_INFO
This macro should expand into a C initializer to use to initialize
the machine-dependent info for one insn pattern.  It is used for patterns
that do not specify the machine-dependent info.

If you do not define this macro, zero is used.

@item CONST_COSTS (@var{x}, @var{code})
A part of a C @code{switch} statement that describes the relative
costs of constant RTL expressions.  It must contain @code{case} labels
for expression codes @code{const_int}, @code{const}, @code{symbol_ref}, @code{label_ref}
and @code{const_double}.  Each case must ultimately reach a
@code{return} statement to return the relative cost of the use of that
kind of constant value in an expression.  The cost may depend on the
precise value of the constant, which is available for examination in
@var{x}.

@var{code} is the expression code---redundant, since it can be
obtained with @code{GET_CODE (@var{x})}.

@item DOLLARS_IN_IDENTIFIERS
Define this to be nonzero if the character @samp{$} should be allowed
by default in identifier names.
@end table

@node Assembler Format,, Misc, Machine Macros
@section Output of Assembler Code

@table @code
@item ASM_SPEC
A C string constant that tells the GNU CC driver program options to
pass to the assembler.  It can also specify how to translate options
you give to GNU CC into options for GNU CC to pass to the assembler.
See the file @file{tm-sun3.h} for an example of this.

Do not define this macro if it does not need to do anything.

@item LINK_SPEC
A C string constant that tells the GNU CC driver program options to
pass to the linker.  It can also specify how to translate options you
give to GNU CC into options for GNU CC to pass to the linker.

Do not define this macro if it does not need to do anything.

@item LIB_SPEC
Another C string constant used much like @code{LINK_SPEC}.  The difference
between the two is that @code{LIBS_SPEC} is used at the end of the
command given to the linker.

If this macro is not defined, a default is provided that
loads the standard C library from the usual place.  See @file{gcc.c}.

@item LIBG_SPEC
Another C string constant used much like @code{LINK_SPEC}.
This controls whether to link @file{libg.a} when debugging.
Some systems expect this; others do not have any @file{libg.a}.

If this macro is not defined, a default is provided that loads the
@file{libg.a} provided @samp{-g} is specified.  See @file{gcc.c}.

@item STARTFILE_SPEC
Another C string constant used much like @code{LINK_SPEC}.  The
difference between the two is that @code{STARTFILE_SPEC} is used at
the very beginning of the command given to the linker.

If this macro is not defined, a default is provided that loads the
standard C startup file from the usual place.  See @file{gcc.c}.

@item STANDARD_EXEC_PREFIX
Define this macro as a C string constant if you wish to override the
standard choice of @file{/usr/local/lib/gcc-} as the default prefix to
try when searching for the executable files of the compiler.

The prefix specified by the @samp{-B} option, if any, is tried before
the default prefix.  After the default prefix, if the executable is
not found that way, @file{/usr/lib/gcc-} is tried next; then the
directories in your search path for shell commands are searched.

@item STANDARD_STARTFILE_PREFIX
Define this macro as a C string constant if you wish to override the
standard choice of @file{/usr/local/lib/} as the default prefix to try
when searching for startup files such as @file{crt0.o}.

In this search, all the prefixes tried for executable files are tried
first.  Then comes the default startfile prefix specified by this
macro, followed by the prefixes @file{/lib/} and @file{/usr/lib/} as
last resorts.

@item ASM_FILE_START (@var{stream})
A C expression which outputs to the stdio stream @var{stream}
some appropriate text to go at the start of an assembler file.

Normally this macro is defined to output a line containing
@samp{#NO_APP}, which is a comment that has no effect on most
assemblers but tells the GNU assembler that it can save time by not
checking for certain assembler constructs.

On systems that use SDB, it is necessary to output certain commands;
see @file{tm-attasm.h}.

@item ASM_FILE_END (@var{stream})
A C expression which outputs to the stdio stream @var{stream}
some appropriate text to go at the end of an assembler file.

If this macro is not defined, the default is to output nothing
special at the end of the file.  Most systems don't require any
definition.

On systems that use SDB, it is necessary to output certain commands;
see @file{tm-attasm.h}.

@item ASM_IDENTIFY_GCC (@var{file})
A C statement to output assembler commands which will identify
the object file as having been compiled with GNU CC (or another
GNU compiler).

If you don't define this macro, the string @samp{gcc_compiled.:}
is output.  This string is calculated to define a symbol which,
on BSD systems, will never be defined for any other reason.
GDB checks for the presence of this symbol when reading the
symbol table of an executable.

On non-BSD systems, you must arrange communication with GDB in
some other fashion.  If GDB is not used on your system, you can
define this macro with an empty body.

@item ASM_APP_ON
A C string constant for text to be output before each @code{asm}
statement or group of consecutive ones.  Normally this is
@code{"#APP"}, which is a comment that has no effect on most
assemblers but tells the GNU assembler that it must check the lines
that follow for all valid assembler constructs.

@item ASM_APP_OFF
A C string constant for text to be output after each @code{asm}
statement or group of consecutive ones.  Normally this is
@code{"#NO_APP"}, which tells the GNU assembler to resume making the
time-saving assumptions that are valid for ordinary compiler output.

@item TEXT_SECTION_ASM_OP
A C string constant for the assembler operation that should precede
instructions and read-only data.  Normally @code{".text"} is right.

@item DATA_SECTION_ASM_OP
A C string constant for the assembler operation to identify the
following data as writable initialized data.  Normally @code{".data"}
is right.

@item EXTRA_SECTIONS
A list of names for sections other than the standard two, which are
@code{in_text} and @code{in_data}.  You need not define this macro
on a system with no other sections (that GCC needs to use).

@item EXTRA_SECTION_FUNCTIONS
One or more functions to be defined in @file{varasm.c}.  These
functions should do jobs analogous to those of @code{text_section} and
@code{data_section}, for your additional sections.  Do not define this
macro if you do not define @code{EXTRA_SECTIONS}.

@item SELECT_SECTION (@var{exp})
A C statement or statements to switch to the appropriate section for
output of @var{exp}.  You can assume that @var{exp} is either a
@code{VAR_DECL} node or a constant of some sort.  Select the section
by calling @code{text_section} or one of the alternatives for other
sections.

Do not define this macro if you use only the standard two sections
and put all read-only variables and constants in the text section.

@item SELECT_RTX_SECTION (@var{mode}, @var{rtx})
A C statement or statements to switch to the appropriate section for
output of @var{rtx} in mode @var{mode}.  You can assume that @var{rtx}
is some kind of constant in RTL.  The argument @var{mode} is redundant
except in the case of a @code{const_int} rtx.  Select the section by
calling @code{text_section} or one of the alternatives for other
sections.  

Do not define this macro if you use only the standard two sections and
put all constants in the text section.  

@item REGISTER_NAMES
A C initializer containing the assembler's names for the machine
registers, each one as a C string constant.  This is what translates
register numbers in the compiler into assembler language.

@item DBX_REGISTER_NUMBER (@var{regno})
A C expression that returns the DBX register number for the compiler
register number @var{regno}.  In simple cases, the value of this
expression may be @var{regno} itself.  But sometimes there are some
registers that the compiler knows about and DBX does not, or vice
versa.  In such cases, some register may need to have one number in
the compiler and another for DBX.

@item DBX_DEBUGGING_INFO
Define this macro if GNU CC should produce debugging output for DBX
in response to the @samp{-g} option.

@item SDB_DEBUGGING_INFO
Define this macro if GNU CC should produce debugging output for SDB
in response to the @samp{-g} option.

@item PUT_SDB_@var{op}
Define these macros to override the assembler syntax for the special
SDB assembler directives.  See @file{sdbout.c} for a list of these
macros and their arguments.  If the standard syntax is used, you need
not define them yourself.

@item SDB_GENERATE_FAKE
Define this macro to override the usual method of constructing a dummy
name for anonymous structure and union types.  See @file{sdbout.c} for
more information.

@item DBX_NO_XREFS
Define this macro if DBX on your system does not support the construct
@samp{xs@var{tagname}}.  On some systems, this construct is used to
describe a forward reference to a structure named @var{tagname}.
On other systems, this construct is not supported at all.

@item DBX_CONTIN_LENGTH
A symbol name in DBX-format debugging information is normally
continued (split into two separate @code{.stabs} directives) when it
exceeds a certain length (by default, 80 characters).  On some
operating systems, DBX requires this splitting; on others, splitting
must not be done.  You can inhibit splitting by defining this macro
with the value zero.  You can override the default splitting-length by
defining this macro as an expression for the length you desire.

@item DBX_CONTIN_CHAR
Normally continuation is indicated by adding a @samp{\} character to
the end of a @code{.stabs} string when a continuation follows.  To use
a different character instead, define this macro as a character
constant for the character you want to use.  Do not define this macro
if backslash is correct for your system.

@item DBX_STATIC_STAB_DATA_SECTION
Define this macro if it is necessary to go to the data section before
outputting the @samp{.stabs} pseudo-op for a non-global static
variable.

@item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} the assembler definition of a label named @var{name}.
Use the expression @code{assemble_name (@var{stream}, @var{name})} to
output the name itself; before and after that, output the additional
assembler syntax for defining the name, and a newline.

@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} any text necessary for declaring the name @var{name} of a
function which is being defined.  This macro is responsible for
outputting the label definition (perhaps using
@code{ASM_OUTPUT_LABEL}).  The argument @var{decl} is the
@code{FUNCTION_DECL} tree node representing the function.

If this macro is not defined, then the function name is defined in the
usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).

@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} some commands that will make the label @var{name} global;
that is, available for reference from other files.  Use the expression
@code{assemble_name (@var{stream}, @var{name})} to output the name
itself; before and after that, output the additional assembler syntax
for making that name global, and a newline.

@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} any text necessary for declaring the name of an external
symbol named @var{name} which is referenced in this compilation but
not defined.  The value of @var{decl} is the tree node for the
declaration.

This macro need not be defined if it does not need to output anything.
The GNU assembler and most Unix assemblers don't require anything.

@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
A C statement to output to the stdio stream @var{stream} a reference
in assembler syntax to a label named @var{name}.  The character
@samp{_} should be added to the front of the name, if that is
customary on your operating system, as it is in most Berkeley Unix
systems.  This macro is used in @code{assemble_name}.

@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
A C statement to store into the string @var{string} a label whose name
is made from the string @var{prefix} and the number @var{num}.

This string, when output subsequently by @code{ASM_OUTPUT_LABELREF},
should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL}
would produce with the same @var{prefix} and @var{num}.

@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
A C statement to output to the stdio stream @var{stream} a label whose
name is made from the string @var{prefix} and the number @var{num}.
These labels are used for internal purposes, and there is no reason
for them to appear in the symbol table of the object file.  On many
systems, the letter @samp{L} at the beginning of a label has this
effect.  The usual definition of this macro is as follows:

@example
fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
@end example

@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
Define this if the label before a jump-table needs to be output
specially.  The first three arguments are the same as for
@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
jump-table which follows (a @code{jump_insn} containing an
@code{addr_vec} or @code{addr_diff_vec}).

This feature is used on system V to output a @code{swbeg} statement
for the table.

If this macro is not defined, these labels are output with
@code{ASM_OUTPUT_INTERNAL_LABEL}.

@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
Define this if something special must be output at the end of a
jump-table.  The definition should be a C statement to be executed
after the assembler code for the table is written.  It should write
the appropriate code to stdio stream @var{stream}.  The argument
@var{table} is the jump-table insn, and @var{num} is the label-number
of the preceding label.

If this macro is not defined, nothing special is output at the end of
the jump-table.

@item ASM_OUTPUT_ALIGN_CODE (@var{file})
A C expression to output text to align the location counter in the way
that is desirable at a point in the code that is reached only by
jumping.

This macro need not be defined if you don't want any special alignment
to be done at such a time.  Most machine descriptions do not currently
define the macro.

@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
A C expression to assign to @var{outvar} (which is a variable of type
@code{char *}) a newly allocated string made from the string
@var{name} and the number @var{number}, with some suitable punctuation
added.  Use @code{alloca} to get space for the string.

This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
to produce an assembler label for an internal static variable whose
name is @var{name}.  Therefore, the string must be such as to result
in valid assembler code.  The argument @var{number} is different each
time this macro is executed; it prevents conflicts between
similarly-named internal static variables in different scopes.

Ideally this string should not be a valid C identifier, to prevent any
conflict with the user's own symbols.  Most assemblers allow periods
or percent signs in assembler symbols; putting at least one of these
between the name and the number will suffice.

@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
A C expression to output to @var{stream} some assembler code
which will push hard register number @var{regno} onto the stack.
The code need not be optimal, since this macro is used only when
profiling.

@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
A C expression to output to @var{stream} some assembler code
which will pop hard register number @var{regno} off of the stack.
The code need not be optimal, since this macro is used only when
profiling.

@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
This macro should be provided on machines where the addresses
in a dispatch table are relative to the table's own address.

The definition should be a C statement to output to the stdio stream
@var{stream} an assembler pseudo-instruction to generate a difference
between two labels.  @var{value} and @var{rel} are the numbers of two
internal labels.  The definitions of these labels are output using
@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
way here.  For example,

@example
fprintf (@var{stream}, "\t.word L%d-L%d\n",
         @var{value}, @var{rel})
@end example

@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
This macro should be provided on machines where the addresses
in a dispatch table are absolute.

The definition should be a C statement to output to the stdio stream
@var{stream} an assembler pseudo-instruction to generate a reference to
a label.  @var{value} is the number of an internal label whose
definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
For example,

@example
fprintf (@var{stream}, "\t.word L%d\n", @var{value})
@end example

@item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a @code{double} constant whose value is
@var{value}.  @var{value} will be a C expression of type
@code{double}.

@item ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a @code{float} constant whose value is
@var{value}.  @var{value} will be a C expression of type @code{float}.

@item ASM_OUTPUT_INT (@var{stream}, @var{exp})
@itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
@itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a @code{int}, @code{short} or @code{char}
constant whose value is @var{value}.  The argument @var{exp} will be an
RTL expression which represents a constant value.  Use
@samp{output_addr_const (@var{stream}, @var{exp})} to output this value
as an assembler expression.@refill

@item ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a @code{long long} constant whose value is
@var{exp}.  The argument @var{exp} will be an RTL expression which
represents a constant value.  It may be a @code{const_double} RTX,
or it may be an ordinary single-precision constant.  In the latter
case, you should zero-extend it.

@item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a single byte containing the number @var{value}.

@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to assemble a string constant containing the @var{len}
bytes at @var{ptr}.  @var{ptr} will be a C expression of type
@code{char *} and @var{len} a C expression of type @code{int}.

If the assembler has a @code{.ascii} pseudo-op as found in the
Berkeley Unix assembler, do not define the macro
@code{ASM_OUTPUT_ASCII}.

@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to advance the location counter by @var{nbytes} bytes.
@var{nbytes} will be a C expression of type @code{int}.

@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to advance the location counter to a multiple of 2 to the
@var{power} bytes.  @var{power} will be a C expression of type @code{int}.

@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} the assembler definition of a common-label named
@var{name} whose size is @var{size} bytes.  The variable @var{rounded}
is the size rounded up to whatever alignment the caller wants.

Use the expression @code{assemble_name (@var{stream}, @var{name})} to
output the name itself; before and after that, output the additional
assembler syntax for defining the name, and a newline.

This macro controls how the assembler definitions of uninitialized
global variables are output.

@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
A C statement (sans semicolon) to output to the stdio stream
@var{stream} the assembler definition of a local-common-label named
@var{name} whose size is @var{size} bytes.  The variable @var{rounded}
is the size rounded up to whatever alignment the caller wants.

Use the expression @code{assemble_name (@var{stream}, @var{name})} to
output the name itself; before and after that, output the additional
assembler syntax for defining the name, and a newline.

This macro controls how the assembler definitions of uninitialized
static variables are output.

@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
A C statment to output DBX or SDB debugging information which indicates
that filename @var{name} is the current source file to the stdio stream
@var{stream}.

This macro need not be defined if the standard form of debugging
information for the debugger in use is appropriate.

@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
A C statment to output DBX or SDB debugging information before code
for line number @var{line} of the current source file to the
stdio stream @var{stream}.

This macro need not be defined if the standard form of debugging
information for the debugger in use is appropriate.

@item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
A C statement to output something to the assembler file to handle a
@samp{#ident} directive containing the text @var{string}.  If this
macro is not defined, nothing is output for a @samp{#ident} directive.

@item TARGET_BELL
A C constant expression for the integer value for escape sequence
@samp{\a}.

@item TARGET_BS
@itemx TARGET_TAB
@itemx TARGET_NEWLINE
C constant expressions for the integer values for escape sequences
@samp{\b}, @samp{\t} and @samp{\n}.

@item TARGET_VT
@itemx TARGET_FF
@itemx TARGET_CR
C constant expressions for the integer values for escape sequences
@samp{\v}, @samp{\f} and @samp{\r}.

@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
Define this macro if you are using an unusual assembler that
requires different names for the machine instructions.

The definition is a C statement or statements which output an
assembler instruction opcode to the stdio stream @var{stream}.  The
macro-operand @var{ptr} is a variable of type @code{char *} which
points to the opcode name in its ``internal'' form---the form that is
written in the machine description.  The definition should output the
opcode name to @var{stream}, performing any translation you desire, and
increment the variable @var{ptr} to point at the end of the opcode
so that it will not be output twice.

In fact, your macro definition may process less than the entire opcode
name, or more than the opcode name; but if you want to process text
that includes @samp{%}-sequences to substitute operands, you must take
care of the substitution yourself.  Just be sure to increment
@var{ptr} over whatever text should not be output normally.

If you need to look at the operand values, they can be found as the
elements of @code{recog_operand}.

If the macro definition does nothing, the instruction is output
in the usual way.

@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
If defined, a C statement to be executed just prior to the output of
assembler code for @var{insn}, to modify the extracted operands so
they will be output differently.

Here the argument @var{opvec} is the vector containing the operands
extracted from @var{insn}, and @var{noperands} is the number of
elements of the vector which contain meaningful data for this insn.
The contents of this vector are what will be used to convert the insn
template into assembler code, so you can change the assembler output
by changing the contents of the vector.

This macro is useful when various assembler syntaxes share a single
file of instruction patterns; by defining this macro differently, you
can cause a large class of instructions to be output differently (such
as with rearranged operands).  Naturally, variations in assembler
syntax affecting individual insn patterns ought to be handled by
writing conditional output routines in those patterns.

If this macro is not defined, it is equivalent to a null statement.

@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
A C compound statement to output to stdio stream @var{stream} the
assembler syntax for an instruction operand @var{x}.  @var{x} is an
RTL expression.

@var{code} is a value that can be used to specify one of several ways
of printing the operand.  It is used when identical operands must be
printed differently depending on the context.  @var{code} comes from
the @samp{%} specification that was used to request printing of the
operand.  If the specification was just @samp{%@var{digit}} then
@var{code} is 0; if the specification was @samp{%@var{ltr}
@var{digit}} then @var{code} is the ASCII code for @var{ltr}.

If @var{x} is a register, this macro should print the register's name.
The names can be found in an array @code{reg_names} whose type is
@code{char *[]}.  @code{reg_names} is initialized from
@code{REGISTER_NAMES}.

When the machine description has a specification @samp{%@var{punct}}
(a @samp{%} followed by a punctuation character), this macro is called
with a null pointer for @var{x} and the punctuation character for
@var{code}.

@item PRINT_OPERAND_PUNCT_VALID_P (@var{code})
A C expression which evaluates to true if @var{code} is a valid
punctuation character for use in the @code{PRINT_OPERAND} macro.  If
@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
punctuation characters (except for the standard one, @samp{%}) are used
in this way.

@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
A C compound statement to output to stdio stream @var{stream} the
assembler syntax for an instruction operand that is a memory reference
whose address is @var{x}.  @var{x} is an RTL expression.

@item ASM_OPEN_PAREN
@itemx ASM_CLOSE_PAREN
These macros are defined as C string constant, describing the syntax
in the assembler for grouping arithmetic expressions.  The following
definitions are correct for most assemblers:

@example
#define ASM_OPEN_PAREN "("
#define ASM_CLOSE_PAREN ")"
@end example
@end table

@node Config,, Machine Macros, Top
@chapter The Configuration File

The configuration file @file{xm-@var{machine}.h} contains macro definitions
that describe the machine and system on which the compiler is running.
Most of the values in it are actually the same on all machines that GNU CC
runs on, so large parts of all configuration files are identical.  But
there are some macros that vary:

@table @code
@item FAILURE_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits after serious errors.

@item SUCCESS_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits without serious errors.

@item USE_C_ALLOCA
Define this macro to indicate that the compiler is running with the
@code{alloca} implemented in C.  This version of @code{alloca} can be
found in the file @file{alloca.c}; to use it, you must also alter the
@file{Makefile} variable @code{ALLOCA}.

This macro, unlike most, describes the machine that the compiler is
running on, rather than the one the compiler is compiling for.
Therefore, it should be set in the @file{xm-@var{machine}.h} file
rather than in the @file{tm-@var{machine}.h} file.

If you do define this macro, you should probably do it as follows:

@example
#ifndef __GNUC__
#define USE_C_ALLOCA
#else
#define alloca __builtin_alloca
#endif
@end example

@noindent
so that when the compiler is compiled with GNU CC it uses the more
efficient built-in @code{alloca} function.
@end table

In addition, configuration files for system V define @code{bcopy},
@code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
as a macro when compiled with GNU CC, in order to take advantage of the
benefit of GNU CC's built-in @code{alloca}.

@contents
@bye